language

Some fools attempt at an interpreted language
Log | Files | Refs

SPECIFICATION (15489B)


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
                             Detailed Specification for
                                  Various Componets

                           Paul Longtine (paul@nanner.co)

OVERVIEW
    This language will look and feel like any other normal, ordinary language.
The goal is not to innovate, but to see if _I_ can. This is a personal refuge
before my inevitable contributions to large group projects where individuals
are deemed inferior.

 SYNTAX
    #TO BE DETERMINED#

 TYPES

    The following types are paraphrased to give you a breif overview:
 0 VOID    - Null, no data
 1 ADDR    - Address type (bytecode)
 2 TYPE    - A `type` type
 3 PLIST   - Parameter list
 4 FUNC    - Function
 5 OBJBLDR - Object builder
 6 OBJECT  - Object/Class
 7 G_PTR   - Generic pointer
 8 G_INT   - Generic integer
 9 G_FLOAT - Generic double
10 G_CHAR  - Generic character
11 G_STR   - Generic string
12 S_ARRAY - Static array
13 D_ARRAY - Dynamic array
14 H_TABLE - Hashtable
15 G_FIFO  - Stack

 RUNTIME

    The runtime architecture is based off of stack machines. If you don't know
about stack machines, go refresh yourself on stack machines along with basic
computer architecture / turing machines. Then come back here, I'm not explaining
that stuff for you.

--------------------------------------------------------------------------------
General Architecture Overview
--------------------------------------------------------------------------------
RUNTIME ELEMENTS

    RUNTIME CONTEXT DEFINITION

The runtime context keeps track of a invidual threads metadata, such as:

 * The operating stack
    The operating stack where current running instructions push/pop to.
    - refer to STACK DEFINITION

 * Namespace instance
    Data structure that holds the references to variable containers, also provi
    ing the interface for Namespace Levels.
    - refer to NAMESPACE DEFINITION

 * Arguement stack
    Arguements to function calls are pushed on to this stack, flushed on call.
    - refer to STACK DEFINITION, FUNCTION DEFINTION

 * Program counter
    An interface around bytecode to keep track of traversing line-numbered
    instructions.
    - refer to PROGRAM COUNTER DEFINITION

This context gives definition to an 'environment' where code is executed.

    NAMESPACE DEFINITION

A key part to any operational computer language is the notion of a 'Namespace'.
This notion of a 'Namespace' refers to the ability to declare a name, along with
needed metadata, and call upon the same name to retrieve the values assosaited
with that name.

In this definition, the namespace will provide the following key mechanisms:

 * Declaring a name

 * Assigning a name to a value

 * Retreiving a name's value

 * Handle a name's scope

 * Implicitly move in/out of scopes

Scopes are handled by referencing to either the Global Scope or the Local Scope.
The Local Scope is denoted by '0' in the scope arguement when refering to names,
and this scope is initialized when evaluating any new block of code. When a diff
erent block of code is called, a new scope is added as a new Namespace level.
Namespace levels act as context switches within function contexts. For example,
the local namespace must be 'returned to' if that local namespace context needs
to be preserved on return. Pushing 'Namespace levels' ensures that for every n
function calls, you can traverse n instances of previous namespaces.
For example, take this namespace level graphic, where each Level is a namespace
instance:

 Level 0: Global namespace, denoted by '1'.
 Level 1: Namespace level, where Local Level is at 1, denoted by '0'.

When a function is called, another namespace level is created and the local
level increases, like so:

 Level 0: Global namespace, denoted by '1'.
 Level 1: Namespace level.
 Level 2: Namespace level, where Local Level is at 2, denoted by '0'.

Global scope names (denoted by a '1' in the scope arguement) are persistient
through the runtime as they handle all function definitions, objects, and
names declared in the global scope. The "Local Level" is at where references
that have a scope arguement of '0' refer to when accessing names.

    VARIABLE DEFINITION

Variables in this definiton provide the following mechanims:

 * Provide a distinguishable area of typed data

 * Provide a generic container around typed data, to allow for labeling

 * Declare a set of fundemental datatypes, and methods to:

   * Allocate the proper space of memory for the given data type,

   * Deallocate the space of memory a variables data may take up, and

   * Set in place a notion of ownership

For a given variable V, V defines the following attributes

    V -> Ownership
    V -> Type
    V -> Pointer to typed space in memory

Each variable then can be handled as a generic container.

In the previous section, the notion of Namespace levels was introduced. Much
like how names are scoped, generic variable containers must communicate their
scope in terms of location within a given set of scopes. This is what is called
'Ownership'. In a given runtime, variable containers can exist in the following
structures: A stack instance, Bytecode arguements, and Namespaces

The concept of ownership differentiates variables existing on one or more of the
structures. This is set in place to prevent accidental deallocation of variable
containers that are not copied, but instead passed as references to these
structures.

    FUNCTION DEFINITION

Functions in this virtual machine are a pointer to a set of instructions in a
program with metadata about parameters defined.

    OBJECT DEFINITION

In this paradigm, objects are units that encapsulate a seperate namespace and
collection of methods.

    BYTECODE SPEC

Bytecode is organised in the following manner:

    <opcode> (arg 0... (arg n < 3 ) )

Where the <opcode> is a single byte denoting which subroutine to call with the
following arguements when executed.

 Interpreting Bytecode Instructions

    A bytecode instruction is a single-byte opcode, followed by at maximum 3
arguements, which can be in the following forms:

 * Static (single byte)
 * Name (single word)
 * Address (depending on runtime state, usually a word)
 * Dynamic (size terminated by NULL, followed by (size)*bytes of data)
   * i.e. FF FF 00 <0xFFFF bytes of data>,
          01 00 <0x1 bytes of data>,
          06 00 <0x6 bytes of data>, etc

Below is the specification of all the instructions with a short description for
each instruction, and instruction category:
________________________________________________________________________________
OPCODE SPEC
--------------------------------------------------------------------------------
Keywords:
 TOS           - 'Top Of Stack' The top element
 TBI           - 'To be Implemented'
 S<[variable]> - Static Arguement.
 N<[variable]> - Name.
 A<[variable]> - Address Arguement.
 D<[variable]> - Dynamic bytecode arguement.
-------------------------------------------------------------------------------
Hex | Memnonic | arguments - description
-------------------------------------------------------------------------------
1 - Stack manipulation

    These subroutines operate on the current-working stack(1).
-------------------------------------------------------------------------------
10 POP S<n>  - pops the stack n times.
11 ROT       - rotates top of stack
12 DUP       - duplicates the top of the stack
13 ROT_THREE - rotates top three elements of stack
-------------------------------------------------------------------------------
2 - Variable management
-------------------------------------------------------------------------------
20 DEC S<scope> S<type> N<ref> - declare variable of type
21 LOV S<scope> N<ref>         - loads reference variable on to stack
22 STV S<scope> N<ref>         - stores TOS to reference variable
23 CTV S<scope> N<ref> D<data> - loads constant into variable
24 CTS D<data>                 - loads constant into stack
-------------------------------------------------------------------------------
3 - Type management

   Types are in the air at this moment. I'll detail what types there are when
the time comes
-------------------------------------------------------------------------------
30 TYPEOF       - pushes type of TOS on to the stack                        TBI
31 CAST S<type> - Tries to cast TOS to <type>                               TBI
-------------------------------------------------------------------------------
4 - Binary Ops
    OPS take the two top elements of the stack, preform an operation and push
the result on the stack.
-------------------------------------------------------------------------------
40 ADD  - adds
41 SUB  - subtracts
42 MULT - multiplies
43 DIV  - divides
44 POW  - power, TOS^TOS1                                                   TBI
45 BRT  - base root, TOS root TOS1                                          TBI
46 SIN  - sine                                                              TBI
47 COS  - cosine                                                            TBI
48 TAN  - tangent                                                           TBI
49 ISIN - inverse sine                                                      TBI
4A ICOS - inverse consine                                                   TBI
4B ITAN - inverse tangent                                                   TBI
4C MOD  - modulus                                                           TBI
4D OR   - or's                                                              TBI
4E XOR  - xor's                                                             TBI
4F NAND - and's                                                             TBI
-------------------------------------------------------------------------------
5 - Conditional Expressions

    Things for comparison, < > = ! and so on and so forth.
Behaves like Arithmetic instructions, besides NOT instruction. Pushes boolean
to TOS
-------------------------------------------------------------------------------
50 GTHAN    - Greater than
51 LTHAN    - Less than
52 GTHAN_EQ - Greater than or equal to
53 LTHAN_EQ - Less than or equal to
54 EQ       - Equal to
55 NEQ      - Not equal to
56 NOT      - Inverts TOS if TOS is boolean
57 OR       - Boolean OR
58 AND      - Boolean AND
-------------------------------------------------------------------------------
6 - Loops
-------------------------------------------------------------------------------
60 STARTL - Start of loop
61 CLOOP  - Conditional loop. If TOS is true, continue looping, else break
6E BREAK  - Breaks out of loop
6F ENDL   - End of loop
-------------------------------------------------------------------------------
7 - Code flow

    These instructions dictate code flow.
-------------------------------------------------------------------------------
70 GOTO A<addr> - Goes to address
71 JUMPF A<n>   - Goes forward <n> lines
72 IFDO         - If TOS is TRUE, do until done, if not, jump to done
73 ELSE         - Chained with an IFDO statement, if IFDO fails, execute ELSE
                  block until DONE is reached.
74 JTR          - jump-to-return.                                           TBI
75 JTE          - jump-to-error. Error object on TOS                        TBI
7D ERR          - Start error block, uses TOS to evaluate error             TBI
7E DONE         - End of block
7F CALL N<ref>  - Calls function, pushes return value on to STACK.
-------------------------------------------------------------------------------
8 - Generic object interface. Expects object on TOS
-------------------------------------------------------------------------------
80 GETN N<name>   - Returns variable assosiated with name in object

81 SETN N<name>   - Sets the variable assosiated with name in object
                    Object on TOS, Variable on TOS1

82 CALLM N<name>  - Calls method in object

83 INDEXO         - Index an object, uses arguement stack

84 MODO S<OP>     - Modify an object based on op. [+, -, *, /, %, ^ .. etc]
-------------------------------------------------------------------------------
F - Functions/classes
-------------------------------------------------------------------------------
FF DEFUN N<ref> S<type> D<args> - Un-funs everything. no, no- it defines a
                                  function. D<ref> is its name, S<type> is
                                  the return value, D<args> is the args.

FE DECLASS N<ref> D<args>       - Defines a class.

FD DENS S<ref>                  - Specifies a namespace scope

F2 ENDCLASS                     - End of class block

F1 NEW S<scope> N<ref>          - Instantiates class

F0 RETURN                       - Returns from function
-------------------------------------------------------------------------------
0 - SPECIAL BYTES
-------------------------------------------------------------------------------
00 NULL          - No-op

01 LC N<name>    - Calls OS function library, i.e. I/O, opening files, etc  TBI

02 PRINT         - Prints whatever is on the TOS.

03 DEBUG         - Toggle debug mode

0E ARGB          - Builds arguement stack

0F PC S<ref>     - Primitive call, calls a subroutine A<ref>. A list of     TBI
                   primitive subroutines providing methods to tweak
                   objects this bytecode set cannot touch. Uses argstack.
_______________________________________________________________________________
COMPILER/TRANSLATOR/ASSEMBLER
--------------------------------------------------------------------------------

LEXICAL ANALYSIS

    Going from code to bytecode is what this section is all about. First off an
abstract notation for the code will be broken down into a binary tree as so:

                                    <node>
                                      /\
                                     /  \
                                    /    \
                                  <arg> <next>

    <node> can be an argument of its parent node, or the next instruction.
Instruction nodes are nodes that will produce an instruction, or multiple based
on the bytecode interpretation of its instruction. For example, this line of
code:

                                   int x = 3

    would translate into:
                                      def
                                       /\
                                      /  \
                                     /    \
                                    /      \
                                   /        \
                                 int        set
                                 /\          /\
                                /  \        /  \
                              null 'x'    'x'  null
                                          /\
                                         /  \
                                       null  3

    Functions are expressed as individual binary trees. The root of any file is
treated as an individual binary tree, as this is also a function.

    The various instruction nodes are as follows:

 * def <type> <name>
   - Define a named space in memory with the type specified
   - See the 'TYPES' section under 'OVERVIEW'
 * set <name> <value>
   - Set a named space in memory with value specified

                    Going from Binary Trees to Bytecode

    The various instruction nodes within the tree will call specific functions
that will take arguemets specified and lookahead and lookbehind to formulate the
correct bytecode equivilent.