From a27fe1a4cdee714fccf9126e7516143bbcb2a480 Mon Sep 17 00:00:00 2001 From: Kyle Gunger Date: Sun, 8 Aug 2021 09:23:36 -0400 Subject: Appendix work + ch 1 work --- spec/1 - language.md | 86 ++++++++++++++- spec/Appendices.md | 294 +++++++++++++++++++++++++++++++++++++++++++++++++++ spec/README.md | 8 +- 3 files changed, 384 insertions(+), 4 deletions(-) create mode 100644 spec/Appendices.md diff --git a/spec/1 - language.md b/spec/1 - language.md index 50ccf68..ad8b530 100644 --- a/spec/1 - language.md +++ b/spec/1 - language.md @@ -4,22 +4,102 @@ ### Folder Structure -TNSL project structure has a root source folder with TNSL files contained within the folder and sub-folders. There is no strictly enforced system, but good practice is to place code sub-modules in sub-folders, and name the module entry point file the same name as its enclosing folder. +TNSL project structure has a root source folder with TNSL files contained within the folder and sub-folders. There is no strictly enforced system, but the standard organization is to place code sub-modules in sub-folders, and name the module entry point file the same name as its enclosing folder. The main file to compile is known as the root file, which generally resides in the root source folder. This file will contain either a main method, or the pre-processor statement `rootfile` to denote the root of a library. A main file may contain both. ### TNSL Files +TNSL files contain the .tnsl extension and contain one or more of the following: +- Comments +- Pre-processor statements +- Modules +- Named function blocks +- Method and interface blocks +- Constant, variable, and type definitions +TNSL files may only contain the following enclosed in function blocks: +- Re-assignment of variables +- Control flow blocks +- Use of variables in definition of variables +- Function calls ## Section 2 - Blocks ### TNSL Block Notation +Blocks in tnsl consist of a slash and a character denoting the type of block as opening, and the inverse of these symbols as closing. The three types of blocks are comment, pre-processor, and code. Code blocks can be further broken down into modules, functions, methods, and control blocks. + + Examples of standard block opening and closing characters: + + /# - open comment + #/ - close comment + + /: - open pre-processor + :/ - close pre-processor + + /; - open code + ;/ - close code + +In addition to the standard opening and closing characters, there exist "swivle" character sets to quickly close and re-open a block type + + ;; - 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 + +Code blocks may have inputs and/or outputs. Inputs are enclosed by `()` and outputs are enclosed by `[]` + +Usage examples: + + # This is a line comment + + /# + This is a block comment, the next block is a module named "my_module", + it contains one function named "my_function" with no inputs or + outputs. + #/ + + /; module my_module + + /## + This is a documentation comment, notice the two #s at the + beginning of the block instead of just one. + + #; my_function + + ;/ + ;/ + ### Modules +Modules are to TNSL what namespaces are to c++, a way to contain a group of related functions, types, methods, and other namespaces such that they won't interfere with outside code. Modules may only be accessed (by other programs) if they are exported using the `export` keyword when defining the module. Modules contained within the module (Sub-modules) are not automatically exported, and must also use the keyword if they wish to be accessable by other programs. Unexported modules may still be used within the project from which they originate. + +### Module definition example: + +*File a.tnsl (project a)* + + /; export module my_module + /; module my_hidden_module + # Can access all from my_module, and my_hidden_module + ;/ + # Can access all from my_module, and my_hidden_module + ;/ + # Can access all from my_module, and my_hidden_module + +*File b.tnsl (project b)* + + /; my_function + # Can access all from my_module, but not from my_hidden_module + ;/ + # Can access all from my_module, but not from my_hidden_module + ### Functions +TNSL functions are + ### Control Flow Blocks ### Anonymous Blocks @@ -40,6 +120,10 @@ The main file to compile is known as the root file, which generally resides in t ### The Void Type +### Arrays + +### Pointers + ### Defining Types ### Interfaces diff --git a/spec/Appendices.md b/spec/Appendices.md new file mode 100644 index 0000000..02757f4 --- /dev/null +++ b/spec/Appendices.md @@ -0,0 +1,294 @@ +# Appendices + +## Appendix A - Reserved characters and their uses + +### A.1 - Single reserved characters + + Delimiters: + + ( - start of input list (functions, control flow, and types) + + ) - end of input list + + [ - start of output list (functions, control flow) + + ] - end of output list + + { - start of array/data set list (arrays, types) + + } - end of array/data set list + + + Statement seperators: + + ; - beginning of statement, end of previous statement + + : - beginning of pre-processor statement, end of previous + + # - line comment, ends at newline + + + In-line sepreator: + + , - seperates argument lists + + + "Augmentation" characters (operators): + + = - assignment operator + + . - get/access operator + + & - bitwise and + + | - bitwise or + + ^ - bitwise not + + > - greater than + + < - less than + + ! - not (can also prefix any bitwise or boolean operator) + + + - addition + + - - subtraction + + * - multiplication + + / - division + + % - modulus + + ~ - address of (pointer) + + ` - de-reference pointer + +### A.2 - Multi reserved characters + + Delimiters: + + /; - start of code block + + ;/ - end of code block + + /: - start of pre-processor block + + :/ - end of pre-processor block + + /# - start of comment block + + #/ - end of comment block + + ;; - re-define code block (end previous code block and open new code block) + + #; - re-define comment to code block + + ;# - re-define code to comment block + + :: - re-define pre-processor block + + #: - re-define comment to pre-processor block + + :# - re-define pre-processor to comment block + + + Augmentation character sets: + + == - boolean equals + + && - boolean and + + || - boolean or + + << - bit-shift left + + >> - bit-shift right + + &= - bitwise and assignment expansion (x &= y -> x = x & y) + + |= - bitwise or assignment expansion + + ^= - bitwise not assignment expansion + + += - addition assignment expansion + + -= - subtraction assignment expansion + + *= - multiplication assignment expansion + + /= - division assignment expansion + + %= - modulus assignment expansion + + ~= - address of assignment expansion + + `= - de-reference assignment expansion + + !& - bitwise nand + + !| - bitwise nor + + !== - boolean neq + + !&& - boolean nand + + !|| - boolean nor + + !> - not greater than + + !< - not less than + + >== - greater than or equal to + + <== - less than or equal to + +## Appendix B - Reserved words and their uses + + Built-in Types: + + bool - boolean + + char - ascii + + int8 - 8-bit integer + + int16 - 16-bit integer + + int32 - 32-bit integer + + int64 - 64-bit integer + + uint8 - 8-bit integer + + uint16 - 16-bit integer + + uint32 - 32-bit integer + + uint64 - 64-bit integer + + float32 - floating point number (32-bit) + + float64 - floating point number (64-bit) + + void - void type + + type - meta type + + + Values: + + true - boolean true value + + false - boolean false value + + + User defined types: + + struct - define a struct + + interface* - define an interface + + enum - define an enum + + extends* - extends a struct or interface + + is* - checks if the variable's type is or extends another type + + method - creates a block of type-associated functions + + + Control flow: + + if - define a conditional code block, or use after "else" to define an "else if" block + + else - code which runs if and only if an if block is not taken + + loop - begin a loop block + + continue - skip the rest of the code in the top-most loop block + + break - break out of a loop or match block + + match - match a variable to a value + + case - code to run in case of a value match in a match block + + default - code to run in the case of no match in a match block + + label - defines an in-function label to jump to from another part of code + + goto - jump to a previously defined label + + + Modifier keyewords: + + const - marks a variable as constant + + volatile - marks a variable so any operations on it will not be optimized by the compiler + + static - marks a variable to keep value between function calls + + raw - strips down the calling conventions as they relate to normal functions. See Appendix C as it relates to structs + + inline - puts the function code inline and optimizes as such when compiling. If exported, still creates a block for reference by external code. + + + Method modifiers: + + override* - override a method from the struct's super type + + self - reference to the struct the method was called on + + operator - define a method for when a reserved opertaor is used on a user defined struct + + super - can reference the method of an extended type or interface + + + Modules: + + module - a related group of functions, types, and sub-modules + + export - allows the module to be referenced by outside projects, and puts the module into the symbol tree of the binary (if one exists) + + + Memory control: + + alloc* (and related) - allocate (or reallocate) memory from somewhere + + delete* - free allocated memory + +\* keyword requires a libtnsl implimentation + +## Appendix C - Memory operations and code speed as it relates to user-defined types + +In TNSL there exist three different levels of complexity structs can take on. In this appendix these levels will be examined in order of least complex to most complex. + +### Raw structs + +Raw structs are the simplist structs with the fastest lookup times. Raw structs can not be extended, though they may themselves extend interfaces (but not other structs). All members of raw structs must be built-in types, other raw structs, or pointers. Raw structs are always fixed-width and all methods are linked directly, thus there is no lookup time for calling one (they are essentially as fast as calling a regular function as long as you are referencing the struct directly and not by one of it's extended interfaces). + +### Static structs + +Static structs are similar to raw structs except they may be extended. This creates a small delay for calling functions on static structs as there is a lookup time to find the method the call is actually referencing (as it may be calling the function on an extension of the type). All members of static structs must be built-in types, other raw structs, or pointers. Static structs can only extend static structs. + +### Dynamic structs + +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. + +## Credits + + Copyright 2021 Kyle Gunger + + This file is licenced under the CDDL 1.0 (the Licence) + and may only be used in accordance with the Licence. + You should have recieved a copy of the Licence with this + software/source code. If you did not, a copy can be found + at the following URL: + + https://opensource.org/licenses/CDDL-1.0 + + THIS SOFTWARE/SOURCE CODE IS PROVIDED "AS IS" WITH NO + WARRENTY, GUARANTEE, OR CLAIM OF FITNESS FOR ANY PURPOSE + EXPRESS OR IMPLIED \ No newline at end of file diff --git a/spec/README.md b/spec/README.md index 6b788cc..0f05a37 100644 --- a/spec/README.md +++ b/spec/README.md @@ -3,9 +3,7 @@ Version 0.0.1 ## Forward -As of writing this forward, TNSL is not even a language yet. Right now, it's mostly just a stupid idea that I've devoted too much brain-space to, and I'm not confident will ever take off. The hard-core C folk probably will hate it, as well as the new-fangled rust/golangers with all their type safty. - -I'm trying not to think too hard about that. +As of writing this forward, TNSL is not even a language yet. Right now, it's mostly just a stupid idea that I've devoted too much brain-space to, and I'm not confident will ever take off. The hard-core C folk will probably write it off, as well as the new-fangled rust/golangers with all their type safty. Right now, TNSL isn't a language. But it *could* be. And, really, I think it's a cool challenge to try to pack high-level features into a low-level environment. I hope you find it interesting as well. @@ -42,6 +40,10 @@ Right now, TNSL isn't a language. But it *could* be. And, really, I think it's - `libtnsl` as it relates to Types - Cross Calling to C +- Appendix A - Reserved Characters +- Appendix B - Reserved Words +- Appendix C - Speed vs the Type System + ### Credits Copyright 2021 Kyle Gunger -- cgit v1.2.3