From 8c5769484521385f93848e04fdd8648110b6291f Mon Sep 17 00:00:00 2001 From: Marrub Date: Wed, 7 Feb 2018 20:20:54 +0000 Subject: [PATCH] --- zscript-doc.md | 196 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 165 insertions(+), 31 deletions(-) diff --git a/zscript-doc.md b/zscript-doc.md index a24ac47..10249b9 100644 --- a/zscript-doc.md +++ b/zscript-doc.md @@ -7,6 +7,10 @@ Table of Conents * [Enumeration definitions](#enumeration-definitions) * [Constant definitions](#constant-definitions) * [Include directives](#include-directives) +* [Types](#types) +* [Expressions and Operators](#expressions-and-operators) +* [Statements](#statements) +* [API](#api) Examples: @@ -290,74 +294,204 @@ Floating-point types Floating-point types hold exponents, generally represented as regular decimal numbers. There are two such types available to ZScript: -| Name | Notes | -| -------- | --- | -| `float` | Fastest floating-point type available on the platform. Limited use. | -| `double` | 64-bit standard floating-point type. | +| Name | Notes | +| -------- | --- | +| `float` | 32-bit in structures and classes, 64-bit otherwise. | +| `double` | 64-bit floating-point number. | +| `float32` | 32-bit floating-point number. Not implemented correctly, unusable. | +| `float64` | Alias for `double`. | Strings ------- -string +The `string` type is an immutable, garbage-collected string reference type. Strings are not structures or classes, however there are methods attached to the type, detailed in the API section. Names ----- -name +The `name` type is an indexed string. While their contents are the same as a string, their actual value is merely an integer which can be compared far quicker than a string. Names are used for many internal purposes such as damage type names. + +Color +----- + +The `color` type can be converted from a string using the X11RGB lump or a hex color in the format `#RRGGBB`. There are 4 accessible members in `color`: `r`, `g`, `b`, and `a`, for each color channel. Vectors ------- -vector2 -vector3 +There are two vector types in ZScript, `vector2` and `vector3`, which hold two and three members, respectively. Their members can be accessed through `x`, `y` and (for `vector3`,) `z`. `vector3` can additionally get the X and Y components as a `vector2` with `xy`. + +Vectors can use many operators and even have special ones to themselves. See the Expressions and Operators section for more information. Other types ----------- -| Name | Description | -| ----------- | --- | -| `bool` | Holds one of two values: `true` or `false`. | -| `sound` | Similar to `int`, but holds a sound identifier. | -| `textureid` | Similar to `int`, but holds a texture identifier. | -| `color` | A string which cannot be `null`. Holds the name or hex value of a color. | -| `state` | A reference to a state. Similar to `name`. | -| `void` | Holds no data. Nothing can be done with it. | +| Name | Description | +| ------------ | --- | +| `bool` | Holds one of two values: `true` or `false`. | +| `sound` | Similar to `int`, but holds a sound identifier. | +| `textureid` | Similar to `int`, but holds a texture identifier. | +| `spriteid` | Similar to `int`, but holds a sprite identifier. | +| `state` | A reference to an actor state. | +| `statelabel` | The name of an actor state. Similar to `name`. | +| `void` | Alias for `None`. Unknown purpose. | Fixed-size arrays ----------------- -Type[Expr] +Fixed-size arrays take the form `Type[size]`. They hold `size` number of `Type` elements, which can be accessed with the array access operator. Multi-dimensional arrays are also supported. Dynamic-size arrays ------------------- -array +Dynamically sized arrays take the form `array`, and hold an arbitrary number of `Type` elements, which can be accessed with the array access operator. Multi-dimensional dynamic arrays are not supported. Maps ---- -map +Map types take the form `map`. They are not yet implemented. -Class types ------------ +Class type references +--------------------- -class -class +Class type references are used to describe a concrete *type* rather than an object. They simply take the form `class`, and can be restrained to descendants of a type with the syntax `class`. User types ---------- -Ident -@Ident +Any other identifier used as a type will resolve to a user class, structure or enumeration type. + +Identifiers prefixed with `@` are internal types which are not exposed to ZScript. Do not use this in user code. + +A type name that is within a specific scope can be accessed by prefixing it with a `.`. The type `.MyClass.MySubStructure` will resolve to the type `MySubStructure` contained within `MyClass`. Read-only types --------------- -readonly -readonly<@Ident> +A read-only type, as its name implies, may only be read from, and is effectively immutable. They take the form `readonly`. -Fully-specified types ---------------------- +Expressions and Operators +========================= -.DotId -TypeList, Type \ No newline at end of file +Constant: +StringConst (can be concatenated like C) +IntConst +UIntConst +FloatConst +NameConst +False +True +Null + +PrimExpr: +Ident +Super +Constant +Vector3Const (x, y) +Vector2Const (x, y, z) +ParenExpr (x) +FuncCall +(class)(params) +ArraySubscript +MemberAccess +PostIncr +PostDecr + +UnaryExpr: +PrimExpr +Negate +Positive +PreIncr +PreDecr +BitNot +LogNot +Sizeof +Alignof (why) + +BinExpr: +UnaryExpr +Add +Sub +Mul +Div +Mod +Pow ** +CrossProduct cross +DotProduct dot +LSh +RSh +URSh >>> +Concat .. +Lt +Gt +LtEq +GtEq +Difference <>= +Is +Eq +NEq +ApproxEq ~== only works on floats, vecs strings - casecmp for strings, LT epsilon diff. for floats & vectors +BitAnd +BitXor +BitOr +LogAnd +LogOr +Assign +AddAssign +SubAssign +MulAssign +DivAssign +ModAssign +LShAssign +RShAssign +URShAssign +OrAssign +XorAssign +Scope (x scope ui etc.) (why does this exist?) + +TriExpr: +BinExpr +TernaryOp + +Statements +========== + +while +until +for +if +if-else +do-while +do-until +switch +continue +break +return +multiassign-stmt +local-var +static array stmt + +API +=== + +String +------ + +Replace +Format +AppendFormat +Mid +Left +Truncate +Remove +CharAt +CharCodeAt +Filter +IndexOf +LastIndexOf +ToUpper +ToLower +ToInt +ToDouble +Split +Length \ No newline at end of file