1.0 Release Candidate 1

A stack-based Programming language implemented in Python.

Sayak Brahmachari

TABLE OF CONTENTS

Contents

About struixLang__________________________________________________________________________________________1

Use Cases __________________________________________________________________________________________________2

Usage_______________________________________________________________________________________________________3

Data Model ________________________________________________________________________________________________4

List of Primitive Words in this Implementation ________________________________________________________5

struixLang 101 ____________________________________________________________________________________________7

Execution Process _________________________________________________________________________________________________7

Syntax and Other Stuff ____________________________________________________________________________________________7

Basics of struixLang ______________________________________________________________________________________8

Input and Output __________________________________________________________________________________________________8

Variables and Constants _________________________________________________________________________________________10

Mathematical Operations________________________________________________________________________________________11

Mathematical Operators: _____________________________________________________________________________________12

Stack Operations _________________________________________________________________________________________________13

DUP – Duplicate ToS __________________________________________________________________________________________13

DROP – Remove ToS __________________________________________________________________________________________13

SWAP – Swap ToS and 2oS ___________________________________________________________________________________13

OVER – Copy 20S on top of ToS ______________________________________________________________________________14

ROT – Move 3oS on top of ToS _______________________________________________________________________________14

Comments ________________________________________________________________________________________________________14

List ________________________________________________________________________________________________________________15

Nested Lists____________________________________________________________________________________________________15

LEN or LENGTH – Find length of List________________________________________________________________________15

ITEM – To access an element from the List _________________________________________________________________15

Executable Lists _______________________________________________________________________________________________16

Conditional Statements__________________________________________________________________________________________17

IFTRUE_________________________________________________________________________________________________________17

IFFALSE ________________________________________________________________________________________________________17

TABLE OF CONTENTS

IFELSE _________________________________________________________________________________________________________17

Looping Techniques _____________________________________________________________________________________________18

TIMES __________________________________________________________________________________________________________18

WHILE _________________________________________________________________________________________________________18

DOWHILE ______________________________________________________________________________________________________18

STRUIX LANG

Page 1

About struixLang

A stack-based case-insensitive programming language implemented in Python3.

struixLang implements a stack, which is a list of objects which the program operates

on.

Also, a dictionary is present, containing words (functions/subroutines) which may be

executed in a program.

Several primitive (read: built-in) words are pre-defined and mechanisms to define new

user-defined words within struixLang itself are in place.

INPUT

OUTPUT

Stack = Struix

STRUIX LANG

Page 2

Use Cases

The most potential use case for struixLang is as an embedded domain specific

scripting language.

Being so compact, struixLang can be easily adapted to the specifics of the host language

and of the intended task. Not to mention its inherent simplicity should ensure

acceptable performance even on top of another interpreted language (like this

implementation).

STRUIX LANG

Page 3

Usage

To run the default shell for struixLang, run the repl.py file under Python 3.

The interpreter can also be imported from within other Python programs.

import struixTerp

However, the interpreter by itself does not form the language. To import the

primitives, do:

import struixPrimitives

Then create a new instance of the interpreter:

terp = struixTerp.Terp()

Add the primitives to it:

struixPrimitives.AddWords(terp)

And give the interpreter a string of struixLang code to run:

terp.run("""

var a

a = 10

"Hello, World!"

a fetch

[ print ] 2 times

""")

However, some potentially dangerous operations can be enabled by passing True to

struixPrimitives.AddWords():

struixPrimitives.AddWords(terp, True)

STRUIX LANG

Page 4

Data Model

struixLang supports the following data types:

 Integers,

 Floats,

 Strings,

 Boolean,

 Lists, and

 Words.

However, the current implementation can utilize words which put or use values of any

type supported in Python 3.

Also, note that as struixLang is a Homoiconic Language, it can treat code as data and

data as code, hence words are included in the list above.

STRUIX LANG

Page 5

List of Primitive Words in this Implementation

1. PRINT – Pops and displays the last item put in the stack.

2. INPUT – Accepts input from the user.

3. PSTACK – Displays all items of the stack in Last-In-First-Out (LIFO) order.

4. RAISE – Raises

5. EXIT – Stops the execution of the struixLang code.

6. Operators from CALCGEN:

a. + - Adds last 2 numbers from stack or concatenates

b. – - Subtracts last 2 numbers from stack.

c. * - Multiplies last 2 numbers form stack.

d. ** - Raises 2

last number to the power of last number.

e. / - Divides last 2 numbers.

f. // - Divides last 2 numbers and removes decimal part to produce an integer.

g. % - Gives the remainder of division of last 2 numbers.

h. @

i. <<

j. >>

k. |

l. ^

m. ~

n. < - Relational operator LESS THAN.

o. > - Relational operator GREATER THAN.

p. <= - Relational operator LESS THAN OR EQUAL TO.

q. >= - Relational operator GREATER THAN OR EQUAL TO.

r. == - Relational operator EQUAL TO.

s. != - Relational operator NOT EQUAL TO.

t. IN – Check if 2

last item is present within last item (string, list, etc).

u. IS – Checks if the 2

last item is the same item (same instance of same

class) as last item.

v. OR – Logical or Boolean OR.

w. AND – Logical or Boolean AND.

7. DUP – Duplicates last item in stack.

8. DROP – Removes last item from stack.

9. SWAP – Swaps last item with 2

last item.

10. OVER – Duplicates and pushes 2

last item to stack.

STRUIX LANG

Page 6

11. ROT – Duplicates and pushes 3

last item to stack.

12. VAR – Creates a variable with following name.

13. CONST – Creates constant with following name and value.

14. = – Stores a value to a variable. (Infix)

15. STORE – Stores a value to a variable. (Postfix)

16. FETCH – Retrieves value from variable.

17. # – Flags a line for no execution.

18. IMPORT – Imports struixLang code from a .sxLib library.

19. REQUESTUNSAFE – Asks user for permission to allow potentially unsafe code.

20. PYEVAL – Evaluates a Python expression.

21. PYEXEC – Executes a Python statement.

22. PYIMPORT – Imports a python module.

23. PYLITEVAL – Evaluates a Python expression safely.

24. DEF – Starts creation of a user-defined new word.

25. END – Ends a new user-defined word definition.

26. NEXT – Skips a word and appends it to the stack.

27. [ - Starts a list.

28. ] – Ends a list.

29. LENGTH – Finds the length of a list or a string.

30. ITEM – Returns an item from a list

31. NOT – Logical or Boolean NOT.

32. TRUE – Logical or Boolean value TRUE, HIGH, or 1.

33. FALSE – Logical or Boolean value FALSE, LOW, or 0.

34. RUN – Runs a list containing struixLang code.

35. TIMES – Runs a list a number of times.

36. IFTRUE – Runs a list on receiving TRUE.

37. IFFALSE – Runs a list on receiving FALSE.

38. IFELSE – Runs one of two lists on receiving either TRUE or FALSE.

39. WHILE – Runs a list while another list yields TRUE.

40. DOWHILE – Exit-Control Loop similar to WHILE.

STRUIX LANG

Page 7

struixLang 101

EXECUTION PROCESS

1. Any integer, float or string goes to the stack.

2. Any comments are ignored.

3. Anything else is interpreted.

SYNTAX AND OTHER STUFF

a. Parts of code are separated only by whitespace.

“Enter 2 Numbers:” print [ input ] 2 times + print is same as

“Enter 2 Numbers:” print

[ input ] 2 times

b. Integers are numbers with no decimal points.

c. Floats are numbers with decimal points

d. Strings start with either ‘ or “.

e. Comments start with either # followed by a space.

f. struixLang is case-insensitive (except for strings; struixLang can be made case-

sensitive with minor modifications to the interpreter code).

g. Infinity (inf) is a float.

STRUIX LANG

Page 8

Basics of struixLang

INPUT AND OUTPUT

Keeping the above rules in mind, specifically Rule 1, the following should put the

integer 10 on the stack:

sxL> 10

To verify, type PSTACK and press enter:

sxL> pstack

Let’s try again:

sxL> 11.5

sxL> pstack

The output now will not be just 11 but will list both values:

11.5

PSTACK is the word (command/function) which is used for displaying the entire stack

(working memory) in Last-In-First-Out (LIFO) order.

To display the last element put in the stack, use PRINT:

sxL> print

11.5

sxL> pstack

NOTE: PRINT and most other words remove the item which it prints or operates on from

the stack.

STRUIX LANG

Page 9

Strings can be put in the stack is a similar way:

sxL> “Hello, World!” print

Hello, World!

sxL> ‘Hello Again!’ print

Hello Again!

The INPUT word comes to your rescue when you want to accept a value from the user:

sxL> “Enter a number:” print input

Enter a number:

The last line is a prompt for the user to type something. Whatever the user enters is

pushed (appended) to the stack.

The following number accepts a number, squares it and displays it.

sxL> “Enter a number:” print input 2 ** print

Enter a number:

100

STRUIX LANG

Page 10

VARIABLES AND CONSTANTS

Sometimes a value needs to be stored for easy reference. Variables are used for that. A

variable can be created with the VAR word:

sxL> var a

To store values in it, the = word is used:

sxL> a = 10

Values are retrieved using the FETCH word:

sxL> a fetch print

But for some instances a permanent value need be assigned a name, a value which is

not supposed to change after it has been assigned. The CONST word is what’s needed:

sxL> const a “Constant String”

sxL> a pstack

“Constant String”

NOTE: Constants don’t need a FETCH word to get its value, it is accessed directly.

STRUIX LANG

Page 11

MATHEMATICAL OPERATIONS

In almost all programming languages, and in formal mathematics, the operator is

almost always placed in between the operands like 1 + 2. This is called infix notation.

struixLang is a stack-based language and before an operator can work, the operands

need to be on the stack. Hence, to reduce the complexity of the interpreter,

mathematical (and most other) operations are expressed in postfix notation.

1 + 2  1 2 +

(34 + 78) * 8  34 78 + 8 *

Let’s try them out:

sxL> “Enter a number:” print const n input n 2 + n *

Enter a number:

120

What happens:

1. A message is displayed.

2. The input (10) is set as constant.

3. n 2 + n * = (n + 2) n * [∵ n 2 +  n + 2]

= (n + 2) * n [∵ m n *  m * n,

m = (n + 2)]

4. = (10 + 2) * 10 [Putting value of n]

5. The result (120) is displayed.

STRUIX LANG

Page 12

Mathematical Operators:

1. Add:

sxL> a b + = a + b

2. Subtract:

sxL> a b - = a ‒ b

3. Product:

sxL> a b * = a × b

4. Divide as Integer:

sxL> a b // = ˻a ÷ b˼

5. Divide as Real Number:

sxL> a b / = a ÷ b

6. Power:

sxL> a b ** = a

7. Remainder:

sxL> a b % = a mod b

NOTE about Integer and Real Division: 5 2 / will produce 2.5 while 5 2 // will produce 2.

STRUIX LANG

Page 13

STACK OPERATIONS

One of the most important parts of a stack-based language, stack operations are

necessary for almost everything more complex than adding 2 numbers and displaying

them.

ToS – Top of Stack; last element put in stack.

2oS – 2

Item on Stack; below ToS.

3oS – 3

Item on Stack, and so on…

DUP – Duplicate ToS

sxL> 10 pstack

sxL> dup pstack

DROP – Remove ToS

sxL> 10 11 12 pstack

sxL> drop pstack

SWAP – Swap ToS and 2oS

sxL> 10 11 pstack

sxL> swap pstack

STRUIX LANG

Page 14

OVER – Copy 20S on top of ToS

sxL> 10 11 pstack

sxL> over pstack

ROT – Move 3oS on top of ToS

sxL> 10 11 12 pstack

sxL> rot pstack

COMMENTS

sxL> 10 11 + print # This is a comment.

Note that a space is needed after the # for the comment to work.

STRUIX LANG

Page 15

LIST

Lists are like miniature versions of the stack

†

; they can store anything the stack can

store.

Lists start with the [ symbol and items in it are separated by spaces. Its end is marked

by a ].

sxL> [ 1 2 3 ] pstack

[1, 2, 3]

Nested Lists

Lists can store anything the stack can store, and the stack can store lists. When a list is

stored in a list the structure is known as nested lists.

sxL> [ 1 2 3 [ 'a' 'b' 'c' ] ] pstack

[1, 2, 3, ['a', 'b', 'c']]

LEN or LENGTH – Find length of List

sxL> [ 1 2 3 ] length print

ITEM – To access an element from the List

The index at whose element is to be extracted is to be placed at ToS and the list at 2oS.

Indexing of lists start from 0, like most other programming language. Thus, the first

element is at index 0 and the last element at index (length of list – 1).

sxL> [ 9 8 7 6 ]

sxL> 1 length print

INDEX

ELEMENTS

†

The stack is actually a list.

STRUIX LANG

Page 16

Executable Lists

As mentioned in the Data Model, struixLang is a homoiconic language and can treat

code as data and data as code. Lists are made to store sequences of data and thus can

also store sequences of code to be treated as a single unit.

sxL> [ 10 20 + print ]

sxL> pstack

[10, 20, <function NAME at MEMORY>, <function NAME at MEMORY>]

However, having lists with code without being able to execute them is useless. The RUN

word is used to execute a list in the stack.

sxL> [ 10 20 + print ]

sxL> run

STRUIX LANG

Page 17

CONDITIONAL STATEMENTS

Conditional statements are an integral part of any programming language. struixLang

includes 3 conditional structures which executes a particular list depending on a logical

condition:

 IFTRUE

 IFFALSE

 IFELSE

IFTRUE

It executes the list at ToS if 2oS is TRUE.

sxL> 2 3 < [ "2 is less than 3" print ] iftrue

2 is less than 3

IFFALSE

It executes the list at ToS if 2oS is FALSE.

sxL> 2 3 > [ "2 is not greater than 3" print ] iffalse

2 is not greater than 3

IFELSE

It executes the list at 2oS if 3oS is TRUE, else executes ToS.

sxL> 2 3 < [ "2 is less than 3" print ] [ "2 is greater than 3"

...> print ] ifelse

2 is less than 3

sxL> 3 2 < [ "3 is less than 2" print ] [ "3 is greater than 2"

...> print ] ifelse

3 is greater than 2

STRUIX LANG

Page 18

LOOPING TECHNIQUES

Quite often, a section of code needs to be executed repeatedly. struixLang includes 3

looping structures which helps execute a particular list multiple times:

 TIMES

 WHILE

 DOWHILE

TIMES

It executes the list at 2oS the number of times as determined by the ToS.

sxL> [ "Hello, World!" print ] 2 times

Hello, World!

WHILE

It keeps executing the list at ToS while the list at 2oS is TRUE. Checking is done before

execution.

sxL> var i i = 0

sxL> [ i fetch 3 < ] [ i fetch print i += 1 ] while

DOWHILE

It keeps executing the list at ToS while the list at 2oS is TRUE. Checking is done after

execution.

sxL> var i i = 0

sxL> [ i fetch 3 < ] [ "Hello" print i += 1 ] dowhile

Hello