diff options
| -rw-r--r-- | spec/1.md | 660 | ||||
| -rw-r--r-- | spec/2.md | 101 | ||||
| -rw-r--r-- | spec/3.md | 48 | ||||
| -rw-r--r-- | spec/4.md | 48 | ||||
| -rw-r--r-- | spec/5.md | 101 | ||||
| -rw-r--r-- | spec/Appendices.md | 39 | ||||
| -rw-r--r-- | spec/README.md | 51 |
7 files changed, 606 insertions, 442 deletions
@@ -6,332 +6,467 @@ Normal TNSL project structure has a root source folder with TNSL files contained within the folder and sub-folders. It is normal for the root folder to represent a single library or binary, although there is no strict rule enforcing this. Standard organization is to place sub-modules in sub-folders. The file name for the module's entry point should match the folder name. -The file representing the compile target is known as the root file, which generally resides in the root source folder. This file will contain a main method, and/or the pre-processor statement `rootfile` to denote the root of a library. If both are present, the compiler will generate an executable by default. +The file representing the compile target is known as the root file, which generally resides in the root source folder. If the program is built as an executible, it requires a function with the name `main` as the entrypoint to the program. ### TNSL Files TNSL files end with the `.tnsl` extension and may contain the following: -- Comments -- Pre-processor statements - Modules - Constant and variable definitions -- Named function blocks +- Enum declarations - Struct definitions +- Named function blocks - Method and interface blocks +- Import statements +- Asm statements -The following may only occur within named function or method blocks: +There are other language constructs which may only be used within functions: - Re-assignment of variables - Control flow blocks -- Function calls +- Value statements - Anonymous blocks (Scope blocks) +- Stream semantics -## Section 2 - Blocks - -### TNSL Block Notation - -Blocks in tnsl consist of a slash `/` and a character denoting the type of block. The reverse of these symbols end the block. The three types of blocks are comment, pre-processor, and code. Code blocks can be further broken down into modules, functions, control flow, methods, and interfaces. +Comments may appear anywhere in the file - Examples of standard block opening and closing characters: +### Comments - /# - open comment - #/ - close comment +Comments begin with `#` and end with a new line. Comment blocks start with `/#` and end with `#/`. - /: - open pre-processor - :/ - close pre-processor - - /; - open code - ;/ - close code - -In addition to the standard opening and closing characters, there exist "swivel" character sets to quickly close and open a block type +## Section 2 - Blocks - ;; - close code, then open code - #; - close comment, open code - ;# - close code, open comment - :: - close pre-processor, open preprocessor - #: - close comment, open pre-processor - :# - close pre-processor, open comment +Blocks in TNSL open with `/;` and close with `;/`. Keywords directly after the opening (and on the same line) affect the type of block created. +A quicker syntax for closing and re-opening a new block is to use `;;` which is equivalent to `;//;`; this can be helpful with series of `else if` blocks and `case` blocks. ### Modules Modules are akin to namespaces in C++ -They hold a group of related modules, functions, structs, and variables. These named definitions may be used by other projects if the `export` keyword is used in conjunction with the `module` keywor; otherwise, the names are not exported into the file's symbol table. +They hold a group of related sub-modules, functions, structs, and variables. +These named definitions may be used by other projects if the `export` keyword is used before the `module` keyword. +Otherwise, the names are not exported into the program/library's symbol table. ### Module definition example: *File a.tnsl (project a)* - - /; export module pubmod - /; module hidden - # Can access all from pubmod, and pubmod.hidden - ;/ - # Can access all from pubmod, and pubmod.hidden - ;/ +``` +/; export module pubmod + /; module hidden + # Can access all from pubmod, and pubmod.hidden + ;/ # Can access all from pubmod, and pubmod.hidden +;/ +# Can access all from pubmod, and pubmod.hidden +``` *File aa.tnsl (project a)* - - /; my_function_a - # Can access all from pubmod, and pubmod.hidden - ;/ +``` +/; my_function_a # Can access all from pubmod, and pubmod.hidden +;/ +# Can access all from pubmod, and pubmod.hidden +``` *File b.tnsl (project b)* - - /; my_function - # Can access all from pubmod, but not pubmod.hidden - ;/ - # Can access all from pubmod, but not pubmod.hidden +``` +/; my_function + # Can import all from pubmod, but not pubmod.hidden +;/ +# Can import all from pubmod, but not pubmod.hidden +``` ### Functions -TNSL functions are code blocks whose definition contains none of the following: control flow keywords, the module keyword, the method keyword. TNSL functions are called methods if they are contained within a method block. TNSL methods may only be called with relation to the user defined type they are linked to. If a TNSL function has no user defined name, it is anonymous. Anonymous functions can be stored as void type variables or called immediately. If an anonymous function is not stored, it is interpreted as inline and called immediately (this is known as a scope block). +Functions are blocks followed by a user defined name (not a keyword). +Functions may have inputs and/or outputs. +Inputs are enclosed by `()` and outputs are enclosed by `[]` -Function blocks may have inputs and/or outputs. Inputs are enclosed by `()` and outputs are enclosed by `[]` - -Input lists must begin with a type and conclude with at least one named parameter. If no type is given after a comma, it is assumed that the previous type carries over. +Input lists may begin with a type or be empty. +If they begin with a type they must conclude with at least one named parameter. +Parameters are separated by commas and use the previous type unless a new one is specified. Output lists consist of a comma seperated list of types. -Either of these may be omitted for no input and/or output. +Functions *may* be overloaded (that is, two functions may share names but have differing input type lists). +Overloaded functions *must not* share the same inputs and differing outputs, but *may* have both differing inputs and differing outputs. +Symbols can be defined in a separate build file or auto-generated by the compiler. +There is a standard for how the compiler will auto-generate names; this can be found in another chapter. -TNSL functions may have their call stack modified by the `raw` and/or `inline` keywords. If the `inline` keyword is placed before the function declaration, the function will still be exported (if it is being exported), but any time it is used in the project's code, it will be optimized as if in-line. +### Function definition example: -The use of the `raw` keyword has several effects: the function will have no generated assembly preamble, the function will allow `raw return` statements, the function will not be optimized, and the function will allow `asm` statements. Any function may be labeled `raw`, even `main` and anonymous functions. +*simple function with no inputs or outputs named "my_function"* +``` +/; my_function + tnsl.print("Hello from my_function!") +;/ +``` -Functions *may* be overloaded (that is, two functions may share names but have differing input type lists). Overloaded functions *may not* share the same inputs and differing outputs, but *may* have both differing inputs and differing outputs. +*functions with inputs and/or outputs* +``` +/; my_second_function (int input1, bool input2) [bool, int] + return input2, input1 +;/ -Examples: +/; sum_lists ({}int a, b) [int] + int sum = 0 + + /; loop (int i = 0; i < len a) [++i] + sum += a{i} + ;/ - # simple function with no inputs or outputs named "my_function" - /; my_function - <statements> - ;/ + /; loop (int i = 0; i < len b) [++i] + sum += b{i} + ;/ +;/ - # function with inputs and outputs - /; my_second_function ( <type> input1, <type (optional)> input2 ) [ <type 1>, <type 2>, ... , <type n> ] - <statements> - ;/ +int global_lol = 0 - # funtion with a scope block - /; my_third_function - <statements> - # a scope block - /; - <statements> - ;/ - ;/ +/; next [int] + return ++global_lol +;/ + +/; set_global (int i) + global_lol = i +;/ +``` ### Control Flow Blocks -Control flow blocks are code blocks whose definitions contain the keywords if, else, loop, match, case, or default. +Control flow blocks begin with the keywords `if`, `else`, `loop`, `match`, `case`, or `default`. -For if, else, loop, and match any inputs and/or outputs are a semicolon-separated list of statements. For case or default, only inputs are accepted in the form of a single value. Any variables defined in these inputs or outputs are scoped to the block only. Control flow blocks may not actually output any values; instead, any statements in the output are evaluated when the block ends, weather it loops or not. +Control flow blocks have a series of lists, generally these can be thought of as 'beginnings' encased in "()" and 'endings' encased in "[]". +What 'beginning' and 'ending' mean varries by the type of block and is explained below. -Examples: +### `if` Blocks - # simple if block - /; if ( <conditional> ) - <statements> - ;/ +`if` blocks generally work as you would expect in other procedural languages. +They can be followed by any number of `else if` blocks as well as a final `else` block. - # if block with else and else if - /; if ( <statements (optional)> ; ... ; <conditional> ) - <statements> - ;; else if ( <statements (optional)> ; ... ; <conditional> ) - <statements> - ;; else - <statements> - ;/ +The 'beginning' "()" of an `if` or `else if` block is a series of statements separated by `;`. +These are executed in order. The last of these must evaluate to a boolean (type `bool` with value `true` or `false`). +The code within the if block is executed if the boolean evaluates to `true` and does not execute if the boolean evaluates to `false`. - # loop block - /; loop ( <statements (optional)> ; ... ; <conditional (optional)> ) - [ <statements (optional)> ; ... ; <conditional (optional)> ] +If any block in the series has a condition which evaluates to true then it is executed and the others are skipped. +If none evaluate to true then the `else` block will execute if present. - <statements> - ;/ +The 'ending' "[]" of an `if` block is currently reserved and has undefined behavior. - # match block - /; match ( <statement (optional)> ; ... ; <input value> ) +*Examples:* +``` +/; if (true) + tnsl.print("this always prints") +;/ - /; case <match value> - <statements> - ;; case <match value> - <statements> - # Continue here would fall through to default - ;; default - <statements> - ;/ - ;/ +/; if (false) + tnsl.print("this never prints") +;; else if (true) + tnsl.print("this one will now print") +;; else + tnsl.print("this never prints either") +;/ + +/; if (0 !== 0) + tnsl.print("you have to use boolean values") +;; else if (1 < 0) + tnsl.print("standard equality operators work, see appendix for a list.") +;; else if (int i = 0; i < 2 && 5 > i) + tnsl.print("Statements!") +;/ -### Loops +/; if (false) + tnsl.print("this never prints") +;; else if (false) + tnsl.print("this never prints either") +;; else + tnsl.print("this one will now print") +;/ +``` + +### `loop` Blocks The `loop` block can be configured (based on weather or not each boolean statement is omitted) to act as any type of loop. -The *first* conditional is the **initial run condition**. It decides weather the loop is entered at all. If omitted, defaults to `true`, creating a `do ... while` type block. +The 'beginning' "()" of a `loop` is similar to an `if` in that it is a series of statements; however in the case of a `loop` the conditional is optional and defaults to `true` if omitted. +If the conditional evaluates to `true` then the inner code is evaluated. -The *second* conditional is the **subsequent run condition**. It decides weather the loop continues to loop or not. If omitted, it *mirrors* the **initial run condition** (this is equivalent to a `for` or `while` block). +The 'ending' "[]" of a `loop` is similar to the 'beginning' of the loop as it a series of statements with an optional conditional at the end. +If the conditional is omitted here it defaults to the same as the conditional from the 'beginning'. +Each of these statements are evaluated at the end of the loop and if the conditional evaluates to `true` then the loop repeats its execution from just after the 'beginning'. -Examples: - - # Same as a do ... while block - /; loop [ <conditional> ] - <statements> - ;/ +*Examples* +``` +# Same as a do ... while block +/; loop [ <conditional> ] + <statements> +;/ - # Same as a while loop - /; loop ( <conditional> ) - <statements> - ;/ +# Same as a while loop +/; loop ( <conditional> ) + <statements> +;/ - # Infinite loop - /; loop - <statements> - ;/ +# Infinite loop +/; loop + <statements> +;/ - # Adding statements to mimic a for loop - /; loop (int i = 0; i < 10) [i++] - <statements> - ;/ +# Adding statements to mimic a for loop +# Since i++ is not a bool it does not count +# as the conditional +/; loop (int i = 0; i < 10) [i++] + <statements> +;/ +``` -## Section 3 - Statements +### `match` Blocks -### TNSL Statement Notation +`TODO` -There are three types of tnsl statements: code, pre-processor, and comment. Code statements begin with `;` and end at the next statement. Pre-processor statements begin with `:` and end at the next statement. Comment statements (line comments) begin with `#` and end at the next new line. After a line comment ends, the previous statement resumes. +#### `case` Block -### Variable Declaration +`TODO` -Declaring a variable is done by referencing a type and then giving a list of names for the new variables. Optionally, a list of values may be given to initialize the new variables. +#### `default` Block -Variables may be augmented by the following keywords: `const`, `volatile`, and/or `static`. +`TODO` -Declaring a variable as `const` means that it is a constant and must be immediately initialized. A constant may not be re-assigned a value. +## Section 3 - Types -Declaring a variable as `volatile` means that the compiler will not attempt to optimize operations performed on it. +An exhaustive list of built-in and special types can be found in Appendix B. -Declaring a variable `static` means that the value will be kept between function calls. Static variables may create race conditions when paired with threads. +### Standard Types in `tnsl` -Examples: +The standard set of types will be familiar to programmers with experience in procedural languages. +Some common types are: - # list with initialization - ;int a, b = 0, 1 - - # single without initialization - ;int c - - # list with partial initialization - ;int d, e = 0 # d is defined, but e is not +- Signed integer variants (positive or negative): `int`, `int8`, `int16`, `int32`, `int64` +- Unsigned integer variants (positive only): `uint`, `uint8`, `uint16`, `uint32`, `uint64` +- Floating point variants: `float`, `float32`, `float64` +- Boolean (`true` or `false`): `bool` +- -## Section 4 - Types +TNSL restricts valid platforms to those with byte addressable memory and whose processors support at least 16-bit integers. -An exhaustive list of built-in types can be found in Appendix B. +TNSL basic types with unspecified length (`int`,`uint`, and `float`) default to the largest supported in standard registers (non-SIMD or vector operations). -### The `void` Type +I.E. for x86_32 `int` defaults to `int32`, on x86_64 `int` defaults to `int64` -The `void` type represents one of two things: an unknown data type, or a function. When the void type is paired with input and output parameters `void( <types> )[ <types> ]` it represents a function. When it is not paired with these things it represents an unknown data type. +### `libtnsl` Types -Pure `void` types can not be created. Function types are *always* references to the function, more like pointers than data holders. Otherwise, void types must be created as pure pointers. In this case, they are in a sense "un-typed" pointers which do not know the length of the object they are pointing at, only the address. +The following are well supported but rely on libtnsl: -Examples: +- The meta-type: `type` +- The vector (SIMD) type: `vect` - # simple function - /; func_1 - ;/ +They are discussed in more detail in the advanced features section of the specification. - # void example func - /; func_2 +### Pointers - # create a void type and assign it func_1's value - ;void()[] func_ref = func_1 - - # call func_1 using func_ref - ;func_ref() - ;/ +Pointer types are prefixed with the `~` (pointer to) operator. +This operator serves as both part of the type, and as a way to get a pointer from a variable. + +The de-reference operator `` ` `` is used as a postfix to pointer variables when getting or setting the underlying value. + +*Examples* +``` +# define int i as 0 +int i = 0 + +# pointer to int i +~int p = ~i + +# set the value of i using p (i is set to 1) +p` = 1 + +/; if (i == 1) + tnsl.print("That's pointers!") +;/ +``` + +### References + +Reference types are typically for use in function parameters but can be defined anywhere. Their type signature ends in the de-reference operator `` ` ``. + +A few quirks of reference types: + +- Reference types are similar to pointers and must be initialized with a pointer to be useful. +- When accessed or set in a normal statement they automatically de-reference the pointer they hold. +- When set in definition or function call they expect a pointer to the underlying variable they will access. +- The pointer which the reference variable uses can be set by prefixing with `~` + +*Examples* +``` +# this will be our underlying integer +int a = 0 + +# basic definition and immediate assignment of a reference type +# (immediate assignment is special as it allows setting the +# pointer of the reference without use of the ~ operator) +int` r = ~a + +# sets or gets in normal statements will use the underlying 'a' + +# a becomes 1 +r = 1 + +# b is defined and set to 1 +int b = r + +# an example of declaration without immediate assignment +int` s + +# setting what 's' points to requires use of the ~ operator +~s = ~a -More examples of pointer voids are available in the pointers section of this document. +# a becomes 2 +s++ -### Arrays +# a function with a reference parameter +/; add_one (int` i) + i++ +;/ -In memory, arrays store their length as a uint, then immediately follow with the contents of the array. This way, all arrays can be checked for length with the `len` operator. +# you must explicitly call using a pointer to the variable being referenced +add_one(~a) -Arrays are created by prefixing a type with `{ <# of elements> }` or simply `{}` so long as the array is immediately initialized. One can similarly access an element of an array by suffixing the variable name with `{ <value of element to return> }`. +/; if (a == 3) + tnsl.print("a is now three") +;/ +``` + +### Fixed-length Arrays + +Arrays are a repeated sequence of the same type of data in memory. + +Arrays store their length as a `uint` and immediately follow with the contents of the array. All arrays can be checked for length with the `len` operator. + +Arrays are created by prefixing a type with `{ <# of elements> }`. +One can similarly access an element of an array by suffixing the variable name with `{ <offset of element to return> }`. When initializing or assigning a new value to an entire array, use `{}` to encase a list of values. The length of the array can be gotten by `len <variable name>` -Examples: +*Examples* +``` +# create an array of five integers +{5}int i - # create an array of five integers - ;{5}int i +# assign values to the array +i{0} = 0 +i{1} = 2 +i{2} = 0 +i{3} = 2 +i{4} = 1 - # assign values to the array - ;i{0} = 0 - ;i{1} = 2 - ;i{2} = 0 - ;i{3} = 2 - ;i{4} = 1 +# store the length of the array (5) +uint array_length = len i - # store the length of the array - ;uint array_length = len i +# create an initialized array with length five +{5}int j = {1, 2, 3, 4, 5} - # create an initialized array with length five - ;{}int j = {1, 2, 3, 4, 5} +# loop through the array and add them. +/; loop (int k = 0; k < array_length) [k++] + i{k} += j{k} +;/ +``` - # loop through the array and add them. - /; loop (int k = 0; k < array_length) [k++] +### Unknown-length Arrays - ;i{k} += j{k} - ;/ +When creating an array where the length is not known at compile time (or accepting an array with unknown length as a parameter) use the `{}` prefix. +***When would I use this?*** +- When defining an array within a function body or module the compiler will optimize however it thinks is best and is functionally equivalent to a fixed length array. +- The difference matters more when **defining functions** or **defining structs** since in this case `{}` ***always*** denotes a ***pointer*** to an array. + - This can be useful when you want to accept arbitrarily long lists or have a recursive struct which has an array of itself as a member. -### Pointers +*Examples* +``` +# when defining an array +{}int i = {1, 2, 3, 4} +{}int j = {5, 6, 7, 8, 9, 10} -Pointer types are created using the `~` (pointer to) operator. This operator serves as both part of the type, and as a way to get a pointer from a type. To de-reference a pointer into it's base type, use the `` ` `` (de-reference) operator. +# when defining a recursive struct +struct Node { + int i, + # using a fixed-length here would result in a + # compile time error because the size could + # not be computed + {}Node sub +} -Passing by reference can be done by prefixing the type with the de-reference operator. This type is only available in function parameter declaration. To call a function with this type, a pointer to the desired variable must be given. +# when defining a function +/; sum({}int arr) [int] + int out = 0 + /; loop (int i = 0; i < len arr) [++i] + out += arr{i} + ;/ +;/ -Examples: +# sum can take any array of integers +int a = sum(i), b = sum(j) +``` - # define int - ;int i +### NOTE: Evaluation Order - # pointer to i - ;~int p = ~i +Order of evaluation of type prefixes and postfixes is first all prefixes in right to left order then all postfixes in left to right order. +This can be overridden using parenthesis. - # set i using p - ;`p = 1 +*Convoluted Examples* +``` +# a reference to a pointer which points to an int +~int` +(~int)` - # a function taking a pass by reference - /; add_two (`int i) - i += 2 - ;/ +# a reference to a reference to an array (unknown length) which holds pointers to floats +{}~float`` +({}(~(float))`` - # calling add_two in two different ways - ;add_two(p) - ;add_two(~i) +``` - # i is now 5 +### The `void` Type + +The `void` type can represent two different things: unknown memory or a function. +When `void` is prefixed with `~` it represents a pointer to arbitrary memory (byte aligned). +When the void type is paired with input and output parameters `void( <type list> )[ <type list> ]` it represents a function. This is considered part of the type and is not a postifx. + +*Examples* +``` +# simple function +/; func_1 + tnsl.print("hello!") +;/ + +# void example func +/; func_2 + + # create a void type and assign it func_1's value + void()[] func_ref = func_1 + + # call func_1 using func_ref + func_ref() +;/ +``` ### Casting Types -Casting between types uses the standard input and output enclosing `()` and `[]` in conjunction. Place a value in the input enclosing characters and a type to output in the output enclosing characters to cast one type to another (`( <value> )[ <type> ]`). +Cast by enclosing a value in `()` and following with the type to cast to enclosed in `[]`. -Examples: +*Examples* +``` +# define an int and a float +int i = 10 +float f = 11.5 - # define an int and a float - ;int i = 10 - ;float f = 11.5 +# define a void pointer and set it to reference i +~void v = ~i - # define a void pointer and set it to reference i - ;~void v = ~i - - # define an int pointer and cast the void pointer to initialize it - ;~int p = (v)[~int] +# define an int pointer and cast the void pointer to initialize it +~int p = (v)[~int] - # cast the float to an int and set the value of i - ;`p = (f)[int] +# cast the float to an int and set the value of i +p` = (f)[int] +``` ### Defining Types @@ -363,7 +498,7 @@ Examples: ;/ ;/ -### Interfaces +### Interface Types Interfaces are defined using the `interface` keyword. Interfaces have methods but no struct or members to accompany them. Instances of interfaces may not be created. Methods defined by interfaces must be overridden unless marked in the interface. Such marked methods may call on other methods, but may not use any members as interfaces have none. @@ -394,7 +529,7 @@ Example: ;/ ;/ -### Enums +### Enum Types Enums are defined using the `enum` keyword. An enum represents a set of possible states, and requires a single output type which can be compared. @@ -421,6 +556,10 @@ Examples: ROCK } +## Section 4 - Statements + +`TODO` + ## Section 5 - Operators An exhaustive list of operators can be found in Appendix A @@ -429,114 +568,101 @@ An exhaustive list of operators can be found in Appendix A Operator precedence is as follows (from greatest to least): - Pointer operators (p0): - - ~ - address of - - ` - de-reference - - - Access operator (p1): +``` +Pointer operators (p0): - . - get/access +~ - address of +` - de-reference - Increment/de-increment (p2): - ++ - increment +Access operator (p1): - -- - de-increment +. - get/access - Multiplication/division (p3): +Increment/de-increment (p2): - * - multiply +++ - increment - / - divide +-- - de-increment - Addition and subtraction (p4): +Multiplication/division (p3): - + - addition +* - multiply - - - subtraction +/ - divide - Modulus (p5): +Addition and subtraction (p4): - % - modulus ++ - addition +- - subtraction - Bitwise operators (p6): - & - and +Modulus (p5): - | - nor +% - modulus - ^ - xor - << - shift left - - >> - shift right +Bitwise operators (p6): - !& - nand +& - and - !| - nor +| - nor - !^ - xand +^ - xor - ! - not (bitwise or boolean) +<< - shift left +>> - shift right - Boolean operators (p7): +!& - nand - && - boolean and +!| - nor - || - boolean or +!^ - xand - == - boolean eq +! - not (bitwise or boolean) - > - greater than - < - less than - - !&& - boolean nand +Boolean operators (p7): - !|| - boolean nor +&& - boolean and - !== - boolean neq +|| - boolean or - !> - boolean not greater than +== - boolean eq - !< - boolean not less than +> - greater than - >== - boolean greater than or equal to +< - less than - <== - boolean less than or equal to +!&& - boolean nand -## Section 6 - `raw` and `asm` +!|| - boolean nor -### The `raw` Keyword +!== - boolean neq -The `raw` keyword can be used in four different scenarios, and each has a different meaning. +!> - boolean not greater than -1. The `raw` keyword can be used in function definitions. These effects were discussed in section 2.2. +!< - boolean not less than -2. The `raw` keyword may be used in conjunction with the `return` keyword, but only inside of raw functions. This causes an instant return regardless of stack or register state. It is recommended to clean up function and provide return types before using this. +>== - boolean greater than or equal to -3. The `raw` keyword may be used with the `struct` keyword to create a raw struct. Raw structs can not contain user defined types or generics. Raw types encode no type information and may not be extended. Raw structs, unlike static or dynamic structs, are only as wide their members. - - Static and dynamic structs contain a small amount of information pertaining to their actual type and generics so may be larger than only their members. - - In addition, since static and dynamic structs may be extended, they may not be the initially defined type and may be larger, further complicating matters. +<== - boolean less than or equal to +``` -4. The `raw` keyword may be used with the `enum` keyword to create a raw enum. Raw enums only have at most one state per bit and may bitwise or and bitwise and to generate a full state. Raw enums are much akin to bit-masks. +## Section 6 - `asm` -### The `asm` Keyword +`TODO` -The `asm` keyword may be used in `raw` functions or blocks to produce raw asm code for the assembler. Any valid assembly code may be used, and certain extensions are available such as variable pointer references. +## Section 7 - Crosscalling to C -Syntax: +`TODO` - ;asm "<valid line of assembly code>" ## License @@ -1,101 +0,0 @@ -# Related Features - -## Section 1 - Style Guide - -This style guide is primarially for anyone working on tnsl-lang and to a baseline good practice. However, different programmers and groups will feel differently, the real recommendation is to keep your project consistant. Pick and choose what you need such that it fits your needs and everyone is on board, just keep it consistant. - -This section will probably feel less formal than the others simply due to how subjective things are. - -### Tabs or Spaces - -You will for the most part see tabs being used over spaces in tnsl-lang. This is not to keep file sizes down, but instead so that anyone can tweak how the files look to fit their asthetic best without affecting anyone else. Adjust tab sizing on your machine and it won't change it on mine. - -### Naming Convention - -NOTE: Remember that naming convention is no substitute for readability. If your names don't make sense, neither does your code. x, y, and z may be fine, but that doesn't help anyone else figure out what you're using them for. If a particular implementation *does* use variables that are hard to name, feel free to use letter identifiers, but add some short comments to explain what you're doing and how (see comments for more info). - -- UPPER_SNAKE_CASE for constants and enum values - -- lowerCamelCase for functions, and methods - -- UpperCamelCase or flatcase for enums, types, and interfaces - - it is recommended that interfaces start with the letter i - -- lower_snake_case (hungarian notation acceptable) for type/struct members, variables - -- flatcase for modules - -## Comments - -Comments should strive to tell programmers what a function does or what a struct's member is for rather than how it goes about doing/generating said thing. Particularly obtuse implimentations are free to use comments to explain their code. - -Comment blocks starting with an extra number sign `/##` are documentation comments. If they are at the top of the file, they provide either info about the file or license information. If they appear directly before (or joined to using `#;`) a function or method they explain what the function or method does. - -## Directory Structure - -`src` will be the name of the root source files/folders, `build` will be the name of the outputed files/folders. - -The name of the *main* root file (there may be multiple root files) will be the project folder name followed by .tnsl (example: project tnslc's root file is `src/tnslc.tnsl`). - -Sub-modules shall be contained in their own folder, and the main entry point to the module will be named the same as that folder followed by .tnsl (example: module `tnsl.alg` in libtnsl has the main entry point for the module `/src/alg/alg.tnsl`). - -## Section 2 - Compiler Options - -An exhaustive list of all compiler options can be found in the spec for tnslc, but these are a general sub-set for working on lower-level projects and language bootstrapping. - -### ISA Options - -The tnslc compiler can output for a variety of backends. These can be set with the `--arch <desired isa>` option. - -### Pre-processor - -tnslc can preemptively set pre-processor variables using the `--V "VARIABLE=value, VARIABLE2=value2, ..."` option. - -### Standard Library - -Access to the standard library can be disabled (bare metal mode) by using the `--no-libtnsl` flag. Also use this to build the standard library as it will attempt to link improperly otherwise. - -### T-LETs - -What T-LETs exactly are is discussed later. You can have tnslc produce them by passing the `--otype tlet` flag. - -## Section 3 - The Pre-Processor - -An exhaustive account of the full pre-processor can be found in the tnslc specification. - -### Including Other Files - -Use the `include` directive to include other code. This can be a library using single quotation marks (example: `:include 'tnslc'`), another file using a path with double quotes (example: `:include "c.tnsl"` reads as `:include "./c.tnsl"`), or a module in a subfolder using expanded syntax (`:include "some_module"` reads as `:include "./some_module/some_module.tnsl"`). - -No header guard is needed, tnslc can pick up on if a file has already been included in the project. - -Cyclic dependency for files is fine. Cyclic dependency for structs is not. - -## Section 4 - libtnsl - -An exhaustive list of all features included in the standard libtnsl is provided in the libtnsl spec. This is a short list of minimum functions a libtnsl must provide to make full use of the tnsl programming language. - -### Method and type resolution for non-raw types - -**TBD - this sub-section is under construction** - -The type `tnsl.reflect.type` must exist and must be a raw struct. This is for storing type information. - -The module `tnsl.reflect` must provide the following functions/methods: - -- `type._get_member_ [tnsl.reflect.library]` -- `tnsl.reflect._is (type check, base) [bool]` - -### Vector types - -The type `tnsl.vector.vector` must exist. This is the generic simd/vector type and is referenced by `vect`. - -## Section 5 - TNSL-Lang Export Trees (T-LETs) - -TNSL doesn't use header files, and downloading full source code for every library being referenced would be a pain. This is where T-LETs come in. T-LETs contain a tree of all exported modules, functions, types, methods, and doc comments from a project. They are more compact and are simply named `<project name>.tlet`. - -## License - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at http://mozilla.org/MPL/2.0/. @@ -1,4 +1,50 @@ -# The TNSL Calling ABI +# Features in Position + +To use higher level features in TNSL, an implimentation of libtnsl must be in place with a minimum set of features. This document outlines what concepts are and are not considered "higher level". This document also covers what the minimum set of features are for a given implimentation of libtnsl. Finally, this document covers how to call between TNSL and other programming languages. + +## Section 1 - Bare Metal + +## Section 2 - libtnsl and Types + +`libtnsl` has the authority to define how types are stored in memory (to some extent) and how method resolution works on static and dynamic structs. `libtnsl` *must* provide certain methods for some language features to be available. These functions, and their uses are now listed. A comprehensive list of language keywords can be found in Appendix B. + +### 2.0 - nullptr + +`tnsl._null` *must* be defined as a universal null pointer value. **No type except pointers may be `null`**, but pointers *must* have a null value to distinguish if they point to a meaningful position in memory. + +### 2.1 - The libtnsl Type Extension + +`tnsl.reflect._type` *must* be defined as a raw struct which contains minimum information for type identification. This information is stored with every static or dynamic struct so that programs can reflect type information. + +`tnsl.reflect._member` *should* be defined as a raw struct which contains minimum information for member variable identification within a type. The information need not be stored with every member variable, but should be stored somewhere such that the `tnsl.reflect._get` method can make use of it. + +`tnsl.reflect._method` *must* be defined as a raw struct which contains minimum information for method identification within a type. The information need not be stored with every member function, but should be stored somewhere such that the `tnsl.reflect._call` method can make use of it. + +`tnsl.reflect._is` *must* be defined as a function taking two parameters of type `tnsl.reflect._type` and returning a single `bool` as output. This function is called when the `is` operator is envoked. + +`tnsl.reflect._get` *should* be defined as a function taking three parameters. The first parameter will be of type `tnsl.reflect._type`, the second parameter will be of type `~void`, and the third parameter will be of type `tnsl.reflect._member`. The function will return a single `~void` as output. + +In the parameters, the first relates to the type of the struct given, or at least how the callee views the struct. The second is a pointer to the struct itself. The third is the requested member to get. The `~void` returned must point to the requested value. + +`tnsl.reflect._call` *must* be defined as a function taking four parameters. The first parameter will be of type `tnsl.reflect._type`, the second parameter will be of type `~void`, the third parameter will be of type `tnsl.reflect._method`, and the fourth parameter will be of type `~void`. The function will return a single `~void` as output. + +In the parameters, the first relates to the type of the struct given, or at least how the callee views the struct. The second is a pointer to the struct itself. The third is the requested method to call. The fourth is a pointer to the parameters for the method. The `~void` returned must point to the return value of the method. + +### 2.2 - Memory allocation and de-allocation + +`tnsl.algo._alloc` *must* be defined as a function taking a single parameter of type `uint` as the number of bytes to allocate and returning a single `~void` as the pointer to the allocated memory. The memory must be allocated from the heap. + +`tnsl.algo._salloc` *should* be defined as a function taking a single parameter of type `uint` as the number of bytes to allocate and returning a single `~void` as the pointer to the allocated memory. The memory must be allocated from the stack. + +`tnsl.algo._dealloc` *must* be defined as a function taking a single parameter of type `~void` as the pointer to a chunk of allocated memory. The function should deallocate the memory. + +### 2.3 - Expanded Types Extension + +`tnsl.box._vect` *must* be a raw struct which vector or simd instructions can be preformed on. + +`tnsl.box._string` *must* be a raw struct which stores a string of text. This text may be ASCII or Unicode, and should be stored as `uint8` values internally. + +## Section 3 - Cross calling C ## License @@ -1,50 +1,4 @@ -# Features in Position - -To use higher level features in TNSL, an implimentation of libtnsl must be in place with a minimum set of features. This document outlines what concepts are and are not considered "higher level". This document also covers what the minimum set of features are for a given implimentation of libtnsl. Finally, this document covers how to call between TNSL and other programming languages. - -## Section 1 - Bare Metal - -## Section 2 - libtnsl and Types - -`libtnsl` has the authority to define how types are stored in memory (to some extent) and how method resolution works on static and dynamic structs. `libtnsl` *must* provide certain methods for some language features to be available. These functions, and their uses are now listed. A comprehensive list of language keywords can be found in Appendix B. - -### 2.0 - nullptr - -`tnsl._null` *must* be defined as a universal null pointer value. **No type except pointers may be `null`**, but pointers *must* have a null value to distinguish if they point to a meaningful position in memory. - -### 2.1 - The libtnsl Type Extension - -`tnsl.reflect._type` *must* be defined as a raw struct which contains minimum information for type identification. This information is stored with every static or dynamic struct so that programs can reflect type information. - -`tnsl.reflect._member` *should* be defined as a raw struct which contains minimum information for member variable identification within a type. The information need not be stored with every member variable, but should be stored somewhere such that the `tnsl.reflect._get` method can make use of it. - -`tnsl.reflect._method` *must* be defined as a raw struct which contains minimum information for method identification within a type. The information need not be stored with every member function, but should be stored somewhere such that the `tnsl.reflect._call` method can make use of it. - -`tnsl.reflect._is` *must* be defined as a function taking two parameters of type `tnsl.reflect._type` and returning a single `bool` as output. This function is called when the `is` operator is envoked. - -`tnsl.reflect._get` *should* be defined as a function taking three parameters. The first parameter will be of type `tnsl.reflect._type`, the second parameter will be of type `~void`, and the third parameter will be of type `tnsl.reflect._member`. The function will return a single `~void` as output. - -In the parameters, the first relates to the type of the struct given, or at least how the callee views the struct. The second is a pointer to the struct itself. The third is the requested member to get. The `~void` returned must point to the requested value. - -`tnsl.reflect._call` *must* be defined as a function taking four parameters. The first parameter will be of type `tnsl.reflect._type`, the second parameter will be of type `~void`, the third parameter will be of type `tnsl.reflect._method`, and the fourth parameter will be of type `~void`. The function will return a single `~void` as output. - -In the parameters, the first relates to the type of the struct given, or at least how the callee views the struct. The second is a pointer to the struct itself. The third is the requested method to call. The fourth is a pointer to the parameters for the method. The `~void` returned must point to the return value of the method. - -### 2.2 - Memory allocation and de-allocation - -`tnsl.algo._alloc` *must* be defined as a function taking a single parameter of type `uint` as the number of bytes to allocate and returning a single `~void` as the pointer to the allocated memory. The memory must be allocated from the heap. - -`tnsl.algo._salloc` *should* be defined as a function taking a single parameter of type `uint` as the number of bytes to allocate and returning a single `~void` as the pointer to the allocated memory. The memory must be allocated from the stack. - -`tnsl.algo._dealloc` *must* be defined as a function taking a single parameter of type `~void` as the pointer to a chunk of allocated memory. The function should deallocate the memory. - -### 2.3 - Expanded Types Extension - -`tnsl.box._vect` *must* be a raw struct which vector or simd instructions can be preformed on. - -`tnsl.box._string` *must* be a raw struct which stores a string of text. This text may be ASCII or Unicode, and should be stored as `uint8` values internally. - -## Section 3 - Cross calling C +# The TNSL Calling ABI ## License diff --git a/spec/5.md b/spec/5.md new file mode 100644 index 0000000..1f5a7ac --- /dev/null +++ b/spec/5.md @@ -0,0 +1,101 @@ +# Related Features + +## Section 1 - Style Guide + +This style guide is primarially for anyone working on tnsl-lang and to a baseline good practice. However, different programmers and groups will feel differently, the real recommendation is to keep your project consistant. Pick and choose what you need such that it fits your needs and everyone is on board, just keep it consistant. + +This section will probably feel less formal than the others simply due to how subjective things are. + +### Tabs or Spaces + +You will for the most part see tabs being used over spaces in tnsl-lang. This is not to keep file sizes down, but instead so that anyone can tweak how the files look to fit their asthetic best without affecting anyone else. Adjust tab sizing on your machine and it won't change it on mine. + +### Naming Convention + +NOTE: Remember that naming convention is no substitute for readability. If your names don't make sense, neither does your code. x, y, and z may be fine, but that doesn't help anyone else figure out what you're using them for. If a particular implementation *does* use variables that are hard to name, feel free to use letter identifiers, but add some short comments to explain what you're doing and how (see comments for more info). + +- UPPER_SNAKE_CASE for constants and enum values + +- lowerCamelCase for functions, and methods + +- UpperCamelCase or flatcase for enums, types, and interfaces + - it is recommended that interfaces start with the letter i + +- lower_snake_case (hungarian notation acceptable) for type/struct members, variables + +- flatcase for modules + +## Comments + +Comments should strive to tell programmers what a function does or what a struct's member is for rather than how it goes about doing/generating said thing. Particularly obtuse implimentations are free to use comments to explain their code. + +Comment blocks starting with an extra number sign `/##` are documentation comments. If they are at the top of the file, they provide either info about the file or license information. If they appear directly before (or joined to using `#;`) a function or method they explain what the function or method does. + +## Directory Structure + +`src` will be the name of the root source files/folders, `build` will be the name of the outputed files/folders. + +The name of the *main* root file (there may be multiple root files) will be the project folder name followed by .tnsl (example: project tnslc's root file is `src/tnslc.tnsl`). + +Sub-modules shall be contained in their own folder, and the main entry point to the module will be named the same as that folder followed by .tnsl (example: module `tnsl.alg` in libtnsl has the main entry point for the module `/src/alg/alg.tnsl`). + +## Section 2 - Compiler Options + +An exhaustive list of all compiler options can be found in the spec for tnslc, but these are a general sub-set for working on lower-level projects and language bootstrapping. + +### ISA Options + +The tnslc compiler can output for a variety of backends. These can be set with the `--arch <desired isa>` option. + +### Pre-processor + +tnslc can preemptively set pre-processor variables using the `--V "VARIABLE=value, VARIABLE2=value2, ..."` option. + +### Standard Library + +Access to the standard library can be disabled (bare metal mode) by using the `--no-libtnsl` flag. Also use this to build the standard library as it will attempt to link improperly otherwise. + +### T-LETs + +What T-LETs exactly are is discussed later. You can have tnslc produce them by passing the `--otype tlet` flag. + +## Section 3 - The Pre-Processor + +An exhaustive account of the full pre-processor can be found in the tnslc specification. + +### Including Other Files + +Use the `include` directive to include other code. This can be a library using single quotation marks (example: `:include 'tnslc'`), another file using a path with double quotes (example: `:include "c.tnsl"` reads as `:include "./c.tnsl"`), or a module in a subfolder using expanded syntax (`:include "some_module"` reads as `:include "./some_module/some_module.tnsl"`). + +No header guard is needed, tnslc can pick up on if a file has already been included in the project. + +Cyclic dependency for files is fine. Cyclic dependency for structs is not. + +## Section 4 - libtnsl + +An exhaustive list of all features included in the standard libtnsl is provided in the libtnsl spec. This is a short list of minimum functions a libtnsl must provide to make full use of the tnsl programming language. + +### Method and type resolution for non-raw types + +**TBD - this sub-section is under construction** + +The type `tnsl.reflect.type` must exist and must be a raw struct. This is for storing type information. + +The module `tnsl.reflect` must provide the following functions/methods: + +- `type._get_member_ [tnsl.reflect.library]` +- `tnsl.reflect._is (type check, base) [bool]` + +### Vector types + +The type `tnsl.vector.vector` must exist. This is the generic simd/vector type and is referenced by `vect`. + +## Section 5 - TNSL-Lang Export Trees (T-LETs) + +TNSL doesn't use header files, and downloading full source code for every library being referenced would be a pain. This is where T-LETs come in. T-LETs contain a tree of all exported modules, functions, types, methods, and doc comments from a project. They are more compact and are simply named `<project name>.tlet`. + +## License + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at http://mozilla.org/MPL/2.0/. diff --git a/spec/Appendices.md b/spec/Appendices.md index 7904af5..924be70 100644 --- a/spec/Appendices.md +++ b/spec/Appendices.md @@ -23,8 +23,6 @@ ; - beginning of statement, end of previous statement - : - beginning of pre-processor statement, end of previous - # - line comment, ends at newline @@ -297,8 +295,41 @@ NOTE: Static structs *can* allow generics so long as they do not store said gen Variable width structs (dynamic structs) can accomodate generics and variable width members. Dynamic structs may extend static structs or other dynamic structs. By extending a dynamic struct, even if one makes no use of the dynamic members, their struct is automatically a dynamic struct. These structs offer the least control over memory, and slightly slower call times, but offer the most flexability to the programmer. +## Appendix D - When can I use...? + +### Core Language + +The core language encompases what you would expect from any C-like language: +- Modules +- Variables +- Enums +- Types +- Functions +- Methods +- Interfaces +- Scalar Operators +- Control Flow +- Anonymous Functions +- Inline Assembly +- Interop with C ABI + +### Advanced Language Features +These may depend on support from `libtnsl`, though they are still considered "standard" and any complete implementation of TNSL must include them. +The table below shows what parts of the standard library must be present for the features to work as designed: + +| Feature | libtnsl - `reflect` | libtnsl - `thread` | libtnsl - `stream` | +| --------------- | ------------------- | ------------------ | ------------------ | +| Runtime type reflection | Yes | - | - | +| Threads | - | Yes | - | +| Mutex | - | Yes | - | +| Coroutines | - | Yes | - | +| Generators | - | Yes | - | +| Loop over Generator | - | Yes | - | +| Stream | - | - | Yes | +| Stream Operators | - | - | Yes | +| Loop over Streams | - | Yes | Yes | -## Appendix D - UN7+1 +## Appendix Z - UN7+1 Unicode Non-standard 7+1 bit (UN7+1) encoding is a non-standard way to represent any unicode character using a series of 8-bit values. The first bit in the 8-bit sequence represents if the next 8-bit sequence is included in the character code, the other seven bits are part of the character code. @@ -317,4 +348,4 @@ Examples: This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at http://mozilla.org/MPL/2.0/.
\ No newline at end of file + file, You can obtain one at http://mozilla.org/MPL/2.0/. diff --git a/spec/README.md b/spec/README.md index 67f7e39..2a3f652 100644 --- a/spec/README.md +++ b/spec/README.md @@ -1,47 +1,54 @@ -Version 0.0.1 -# The TNSL Language Specification +# The TNSL Specification +Version 0.0.2 ## Forward -I forgot what TNSL stands for. I now worry that it's one of those "ATM Machine" situations. +This is mostly meant to be a collection of valid TNSL syntax that interested parties can use to learn the language by example. Explanations are provided alongside. In-depth explanations may be provided for features which use a bit of "compiler magic". One goal of the language is to keep "compiler magic" to a minimum while still providing quality of life constructs for programmers to use, so these should be few. + +Also, I forgot what TNSL stands for. I now worry that it's one of those "ATM Machine" situations. -CircleShift ## Chapter Index -1. [The Language](./1.md) - +1. [The Core Language](./1.md) - Files - Blocks - - Statements - Types + - Basic Statements - Operators - - `raw` and `asm` + - `asm` + - Cross Calling to C -2. [Related features](./2.md) - - - Style guide - - Compiler Options - - The Pre-Processor - - libtnsl - - TNSL-lang export trees (T-LETs) +2. [Advanced Features](./2.md) + - Relation to `libtnsl` + - Generators and Coroutines + - Streams + - Anonymous Functions + - Interfaces and Runtime Type Reflection -3. [The TNSL Calling ABI](./3.md) +3. [Tweaking Features](./3.md) + - Bare Metal + - `libtnsl` as it relates to Types +4. [The TNSL Calling ABI](./4.md) - Differences from C - - Exporting C-like Functions + - Exporting and importing C-like Functions - Types and Arrays in Memory -4. [Features in Position](./4.md) - - - Bare Metal - - `libtnsl` as it relates to Types - - Cross Calling to C +5. [Related Reading](./5.md) + - Style guide + - Compiler Options + - The Pre-Processor + - libtnsl + - TNSL export trees (TETs) - [Appendix](./Appendices.md) - A: Reserved Characters - B: Reserved Words - - C: Speed vs the Type System + - C: Speed of Advanced Features + - D: When can I use [Feature]? + - Z: UN7+1 (A unicode nonstandard format) ## License |