summaryrefslogtreecommitdiff
path: root/spec
diff options
context:
space:
mode:
Diffstat (limited to 'spec')
-rw-r--r--spec/compiler/compiler.txt9
-rw-r--r--spec/compiler/pre-processor.txt6
-rw-r--r--spec/iex/iex-spec.txt128
-rw-r--r--spec/libts.txt93
-rw-r--r--spec/spec.txt99
5 files changed, 312 insertions, 23 deletions
diff --git a/spec/compiler/compiler.txt b/spec/compiler/compiler.txt
index dbc64c0..df7a591 100644
--- a/spec/compiler/compiler.txt
+++ b/spec/compiler/compiler.txt
@@ -10,9 +10,14 @@ in their own file.
2) Validation
- 2a) The expander - expands pre-processor commands and macrosoperations
+ 2a) The expander - expands pre-processor commands and macro operations
2b) The validator - checks all requirements for all functions and expressions are valid
3) Translation
- 3a) ??? \ No newline at end of file
+ 3a) Variable resolver - chooses and creates an internal model of where variables are on the stack, as well as calling conventions for functions
+ 3b) Type translator - places and translates types (internal and external)
+ 3c) Container resolver - checks container (elf, exe, dll, app, out, etc.) and decides how to map the types for future linking
+ 3d) Final translation - translates all logic and expressions into native binary code
+ 3e) Optimization
+ 3f) Container Writer - writes the final output of the previous steps into the specified container
diff --git a/spec/compiler/pre-processor.txt b/spec/compiler/pre-processor.txt
index 3203ff8..8297e7d 100644
--- a/spec/compiler/pre-processor.txt
+++ b/spec/compiler/pre-processor.txt
@@ -2,4 +2,8 @@ A set of components in the compiler (all before the translator) which expand,
resolve, and validate pre-processor directives into code which can be compiled
Consists of the resolver in the parsor.
-The expander and part of the indexer in the validator. \ No newline at end of file
+The expander and part of the indexer in the validator.
+
+Special (compiler specififc) definitions can be added with _<compiler>_<variable name>
+
+E.X. if the official implementation wanted to provide the exact time of the compilation, it could use _TNSLC_TIME_NOW for instance \ No newline at end of file
diff --git a/spec/iex/iex-spec.txt b/spec/iex/iex-spec.txt
new file mode 100644
index 0000000..6979cfc
--- /dev/null
+++ b/spec/iex/iex-spec.txt
@@ -0,0 +1,128 @@
+This is the IEX file specification.
+
+Document version (semver): 0.0.1
+Main Author: Kyle Gunger
+
+License: Apache 2.0
+
+----------------------------------
+
+Contents:
+
+Organization
+
+----------------------------------
+
+Organization
+
+Magic number starts the file "IEX" or 0x49 0x45 0x58
+
+The header of the file can be represented as such
+
+;struct IEX_HEAD {
+ raw {3}char # Always "IEX"
+ magic,
+
+ {}char
+ name,
+ arch,
+ os,
+
+ uint8 # Version info
+ major,
+ minor,
+ patch,
+ # OS abi info
+ os_major,
+ os_minor,
+ os_patch,
+
+ bool # Tells loader that the file holds a main function
+ can_execute,
+
+ ~void ({}{}char args) [int]
+ # Address of main in file
+ start_addr,
+
+ {}IEX_SECTION
+ sections,
+
+ {}IEX_LIB
+ dependencies,
+
+ IEX_MODULE
+ self
+}
+
+a section is defined as
+
+;struct IEX_SECTION {
+ {}char
+ name,
+
+ uint8 # Denotes dependency, symbol table, data, bss, text, etc.
+ type,
+
+ ~void # Points to start and end of section
+ start,
+ end
+}
+
+;struct IEX_LIB {
+ {}char
+ name,
+
+ uint8 # Version info
+ major,
+ minor,
+ patch
+}
+
+;struct IEX_MODULE {
+ {}char
+ name,
+
+ {}IEX_FUNCTION
+ func,
+
+ {}IEX_TYPE
+ types,
+
+ {}IEX_MODULE
+ sub
+}
+
+;struct IEX_FUNCTION {
+ {}char
+ name,
+
+ uint32
+ overload,
+ bytes_in,
+ bytes_out,
+
+ ~void
+ addr
+}
+
+;struct IEX_TYPE {
+ {}char
+ name,
+
+ bool
+ raw_struct,
+ interface,
+ dynamic,
+
+ uint32
+ size,
+
+ {}IEX_FUNCTION
+ methods,
+
+ {}IEX_TYPE
+ supers,
+
+ ~void
+ addr
+}
diff --git a/spec/libts.txt b/spec/libts.txt
index e69de29..e31d59d 100644
--- a/spec/libts.txt
+++ b/spec/libts.txt
@@ -0,0 +1,93 @@
+This is the LIBTS specification, a document related to the definition of the TNSL language,
+meta-language, it's usage, and where it's standard libraries may be ported.
+
+Document version (semver): 0.0.1
+Main Author: Kyle Gunger
+
+License: Apache 2.0
+
+----------------------------------
+
+Contents:
+
+Part 1 -- About the Library
+ 1.1: libts and TNSL
+ 1.2: Short overview
+
+Part 2 -- Library Features
+ 2.1: Bitwise operations
+ 2.2: Standard algorithms
+ 2.3: Continer structs
+ 2.4: Standard abstractions
+ 2.5: Time related APIs
+ 2.6: Method resolution
+
+----------------------------------
+
+Part 1: About the Library
+
+----------------------------------
+
+Section 1: libts and TNSL
+
+ libts or the TNSL standard library is a library to be found on almost all systems containing
+ a TNSL implimentation. The library contains both common APIs which ease common programming
+ feats as well as core program logic for the more high-level features of TNSL. TNSL can
+ indeed run without a libts, however doing so limits many parts of the language to the "raw"
+ variants. These limited features include structs, types, and interfaces primarially.
+
+ libts contains a standard method resolution algorithm such that method calls can be resolved
+ on runtime for the high level dynamic type system.
+
+----------------------------------
+
+Section 2: Short overview
+
+ The library contains many standard algoritims and abstractions found in other languages such
+ as C, as well as helpers for these containers.
+
+
+----------------------------------
+
+Part 2: Library Features
+
+----------------------------------
+
+Section 1: Bitwise Operations
+
+----------------------------------
+
+Section 2: Standard algorithms
+
+----------------------------------
+
+Section 3: Continer structs
+
+----------------------------------
+
+Section 4: Standard abstractions
+
+----------------------------------
+
+Section 5: Time related APIs
+
+ Time is important for any program, and libts provides an interface through which to query
+ the operating system for it. libts also provides conversion, projection, and timing features
+ so that programs can make use of user inputs relating to time. If bugs in the time projection
+ of the library, they will be fixed. No reguard to existing data should be given, accuracy is
+ the goal above breakage.
+
+ That being said, the library should attempt to work around erronious data in a way that
+ provides an alternative date if the data is in a good format but pointing to a non-existant
+ date. An error code will still be thrown in these cases, but indicating that the date does
+ not exist, not that the input was complete garbage. Programs may catch errors in any way
+ they choose.
+
+----------------------------------
+
+Section 6: Method resolution
+
+ As previously stated, the library performs method resolution for calls on high-level types.
+ In an iex file, this is done by finding the associated IEX_TYPE of the object and following
+ along the "supers" array and checking with the "methods" arrays until the IEX_TYPE contains
+ a definition for the method called which fits the caller's arguments. \ No newline at end of file
diff --git a/spec/spec.txt b/spec/spec.txt
index 033bb32..4086d3c 100644
--- a/spec/spec.txt
+++ b/spec/spec.txt
@@ -87,7 +87,7 @@ Each file may contain 0 or more of the following:
6) Module blocks
-Code blocks are the only blocks which may contain statements (1.3)
+Code blocks and method blocks are the only blocks which may contain statements (1.3) and logical blocks.
----------------------------------
@@ -321,13 +321,19 @@ Statements make up the actual "doing" part of TNSL
1) Literal values
Literal numbers start with a decimal number, and can contain up to one non-number element:
- 0b1001 - valid
0 - valid
0.2341 - valid
120000 - valid
.34567 - invalid
- 0
+ 0asd...kj - invalid
+
+ Special bases:
+
+ 0b1001 - valid (binary)
+ 0o0127 - valid (octal)
+ 0xABCD - valid (hex)
+ 0BZZZZ - valid (base 64)
These rules will be ammended and are mostly for ease of parsing in the first version of the language.
@@ -344,14 +350,24 @@ Statements make up the actual "doing" part of TNSL
" - invalid
Literal characters use '' and either an escape character or a single character/code point between them
-
+ ' ' - valid
+ '\u2000' - valid
+ '\\' - valid
+ '\'' - valid
+
+ invalid:
+ '\u200220202asdasdaw qwe '
+ '\\asd asd '
+ 'ab'
+ '\'
+ '
2) Call with a return
calling a function is as simple as naming a block of code and then calling it with parentheses
# Define
- /; add ()
+ /; add
;/
# Call (not expression)
@@ -403,8 +419,7 @@ Statements make up the actual "doing" part of TNSL
1.4: Types
TNSL's type system consists of built-in types, user interfaces, and user structs.
-The built-in types are always on the stack, while user types can be on the stack, on the heap,
-or somewhere in between.
+The built-in types are always on the stack, while user types can be on the stack or the heap.
1.4.1: Built-in types
Built-in types are meant to be portable so that tnsl can be backported to whatever system one may want.
@@ -453,20 +468,17 @@ or somewhere in between.
uint64 - 64 bit unsigned int
float64 - 64 bit floating point
- simd (NICE):
- not really sure how these work yet. I'll get back to you
+ vect (NICE):
+ vector, simd, etc. not really sure how these work yet. I'll get back to you
size 128 (NICE):
int128
uint128
float128
- comp128 - complex 128 bit (2 64 bit floats in a trenchcoat)
1.4.2: User defined types (stack)
Any structs defined not using pointers are automatically allocated on the stack.
- The meta type is really a pointer, and so structs using it will not be completely on
- the stack.
Structs are normally alligned to byte boundaries
@@ -474,11 +486,11 @@ or somewhere in between.
Defining a struct can be done as follows:
- ;struct <struct name> ( <optional inputs> ) { <list of members (may use inputs)> }
+ ;struct <struct name> (<list of inputs (makes this a dynamic type)>) { <list of members (may use inputs)> }
e.g.
- ;struct Vector2 {x, y int32}
+ ;struct Vector2 {int32 x, y}
Creating a variable from the struct can be done in two ways:
@@ -501,14 +513,14 @@ or somewhere in between.
method block example using operator
- /; method ~Vector2
+ /; method Vector2
- /; operator + (v ~Vector2)
+ /; operator + (~Vector2 v)
;self.x += `v.x
;self.y += `v.y
;/
- /; dot (v ~Vector2) [int32]
+ /; dot (~Vector2 v) [int32]
;return self.x * `v.x + self.y * `v.y
;/
@@ -605,12 +617,12 @@ and how functions are first-class in TNSL
Anonymous blocks can be written only as scope, or with inputs and outputs for function calls.
- /; call_func (to_call void(int32)[int32]) [int32]
+ /; call_func (void(int32)[int32] to_call) [int32]
;return to_call(5)
;/
/; provide_anon () [int32]
- ;return call_func(/; (a int32) [int32]
+ ;return call_func(/; (int32 a) [int32]
;return a + 1
;/)
;/
@@ -866,4 +878,51 @@ Augmented boolean operators (a !<op> b) = !(a <op> b)
>== - Same as !<
-<== - Same as !> \ No newline at end of file
+<== - Same as !>
+
+----------------------------------
+
+Appendix C: Memory control (and speed) with each type of struct
+
+Each type of user-definable type or struct or interface grants
+it's own level of memory control. These (and their ramifications) are
+listed here from low to high.
+
+---
+
+High level, low control structs (dynamic structs) are created when using
+the parameters for structs/types. They allow variable length which can
+house different information at the cost of speed, memory, and control.
+
+These are the only type of structs which can house other dynamic structs.
+Dynamic structs can only be passes by reference due to undefined size at
+compilation.
+
+---
+
+Medium level, medium control structs (type structs) are created normaly
+through the struct keyword without parameters. These structs are fixed
+length, but the compiler encodes extra info into them. This means they
+get method resolution and override checks which may reduce speed of the
+application.
+
+---
+
+Low level, high control structs (raw structs) are created using the "raw"
+keyword before the "struct" keyword. There are no frills, and method
+resolution is not performed for these structs. These structs may not
+extend or be extended. They may, however, implement interfaces. They
+perform as a "what you see is what you get" kind of memory model. They
+may not use parameters, and all internal types must be consistant length
+(no dynamic structs or dynamic type identifiers).
+
+---
+
+To summerize:
+All these structs can encode the same info, but as you get lower to
+the system, you get the bonus of speed and control while losing higher
+level functions provided by the language.
+
+This shouldn't matter much to most programmers unless they are doing
+embedded development, systems programming, or firmware programming,
+but it is still a consideration to make for time-sensitive applications. \ No newline at end of file