struixLang Documentation

About struixLang
Use Cases
Getting Started
Data Types
Core Concepts
Basic Operations
Advanced Operations
Built-in Functions
Examples
Conclusion

About struixLang

struixLang is a stack-based, case-insensitive programming language implemented in Python 3. It operates on a stack, which is a list of objects that the program manipulates. The language also utilizes a dictionary containing words (functions or commands) that can be executed within a program.

struixLang includes a rich set of built-in words and provides mechanisms for defining new user-defined words within the language itself.

Use Cases

struixLang is ideal for:

Embedded Scripting: Adding scripting capabilities to applications.
Educational Purposes: Teaching programming concepts in a simple and interactive way.
Rapid Prototyping: Quickly testing ideas and algorithms.

Getting Started

To run the struixLang interpreter, execute the repl.py file using Python 3:

python3 repl.py

Alternatively, you can integrate the interpreter into your own Python programs:

import struixTerp
import struixPrimitives

# Create a new interpreter instance
terp = struixTerp.Terp()

# Add built-in words to the interpreter
struixPrimitives.AddWords(terp)

# Run struixLang code
terp.run("""
    var a
    a = 10
    "The value of a is:" print
    a fetch print
""")

Data Types

struixLang supports the following data types:

Integers
Floats
Strings
Booleans
Lists (Arrays)
Variables
Words (Functions)

Core Concepts

The Stack

At the heart of struixLang is the stack. The stack operates on a Last-In-First-Out (LIFO) principle. Items are pushed onto the stack and popped off the stack during operations.

Words (Commands)

Words are the commands or functions in struixLang. They manipulate the stack or perform actions.

Built-in Words: Predefined commands provided by the language.
User-defined Words: Custom commands created using DEF and END.

Variables and Constants

Variables: Named storage locations that can hold values.
```
var x
x = 42
x fetch print
```
Constants: Named values that cannot be changed after initialization.
```
const PI 3.14159
PI print
```

Comments

Comments are used to include explanatory notes in the code and are ignored during execution.

Single-line comments start with #.
```
# This is a comment
```

Basic Operations

Input and Output

PRINT: Pops and displays the top item on the stack.
```
"Hello, World!" print
```
INPUT: Prompts the user for input and pushes the entered value onto the stack.
```
"Enter your name:" print
input
"Hello, " swap + print
```
PSTACK: Displays all items in the stack.
```
pstack
```

Mathematical Operations

struixLang uses postfix notation (Reverse Polish Notation) for operations.

Addition (+)
```
5 3 + print  # Outputs 8
```
Subtraction (-)
```
10 4 - print  # Outputs 6
```
Multiplication (*)
```
7 6 * print  # Outputs 42
```
Division (/)
```
20 5 / print  # Outputs 4.0
```
Integer Division (//)
```
20 3 // print  # Outputs 6
```
Modulus (%)
```
20 3 % print  # Outputs 2
```
Exponentiation (**)
```
2 8 ** print  # Outputs 256
```

Stack Manipulation

DUP: Duplicates the top item on the stack.
```
5 dup print print  # Outputs 5 twice
```

DROP: Removes the top item from the stack.

1 2 3 drop pstack  # Stack now has 2 and 1

SWAP: Swaps the top two items on the stack.

"World" "Hello" swap print print  # Outputs "Hello" then "World"

OVER: Copies the second item on the stack and pushes it to the top.
```
1 2 over print print print  # Outputs 2, 1, 2
```
ROT: Rotates the third item to the top of the stack.
```
1 2 3 rot pstack  # Stack order is now 1, 3, 2
```

Advanced Operations

Logical Operations

Logical operations in struixLang work with boolean values (true and false).

NOT: Logical NOT operation.
```
true not print  # Outputs False
```
AND: Logical AND operation.
```
true false and print  # Outputs False
```
OR: Logical OR operation.
```
true false or print  # Outputs True
```

NAND: Logical NAND operation. Returns the negation of AND.

true false nand print  # Outputs True
true true nand print   # Outputs False

NOR: Logical NOR operation. Returns the negation of OR.

true false nor print   # Outputs False
false false nor print  # Outputs True

XOR: Logical XOR operation. Returns true if one operand is true and the other is false.
```
true false xor print   # Outputs True
true true xor print    # Outputs False
```

Bitwise Operations

BITNOT (~): Bitwise NOT.
```
5 ~ print  # Outputs -6
```
BITAND (&): Bitwise AND.
```
6 3 & print  # Outputs 2
```
BITOR (|): Bitwise OR.
```
6 3 | print  # Outputs 7
```
BITXOR (^): Bitwise XOR.
```
6 3 ^ print  # Outputs 5
```
SHL (<<): Bitwise shift left.
```
2 3 << print  # Outputs 16
```
SHR (>>): Bitwise shift right.
```
16 2 >> print  # Outputs 4
```

String Manipulation

STRCAT: Concatenates two strings.

"Hello, " "World!" strcat print  # Outputs "Hello, World!"

STRLEN: Retrieves the length of a string.
```
"Hello" strlen print  # Outputs 5
```

SUBSTR: Extracts a substring.

"Hello, World!" 7 12 substr print  # Outputs "World"

Multiline Strings

Multiline strings are enclosed in triple quotes (""" or ''').
They allow for more readable code when dealing with long text or multiline outputs.
```
"""This is a 
multiline string""" print
```
Multiline strings can also contain embedded newlines or special characters without requiring explicit escape sequences:
```
"""Line 1
Line 2
Line 3""" print
```

Lists and Arrays

Creating Lists:

[ 1 2 3 4 5 ]  # Pushes a list onto the stack

Accessing Elements (ITEM):

[ 10 20 30 ] 1 item print  # Outputs 20

Modifying Elements (STORE_ITEM):

[ 0 0 0 ] 1 99 store_item pstack  # List becomes [0, 99, 0]

Getting Length (LENGTH):
```
[ 1 2 3 ] length print  # Outputs 3
```

Control Structures

Conditional Execution:
- IFTRUE: Executes a block if the condition is true.
```
true [ "Condition is true" print ] iftrue
```
- IFFALSE: Executes a block if the condition is false.
```
false [ "Condition is false" print ] iffalse
```
- IFELSE: Chooses between two blocks based on a condition.
```
true [ "True block" print ] [ "False block" print ] ifelse
```
Loops:
- TIMES: Repeats a block a specified number of times.
```
[ "Hello!" print ] 3 times
```
- WHILE: Repeats a block while a condition is true.
```
var i
i = 0
[ i fetch 5 < ] [ i fetch print i incr ] while
```
- DOWHILE: Executes a block at least once and repeats while a condition is true.
```
var i
i = 0
[ i fetch 3 < ] [ "Looping" print i incr ] dowhile
```

Defining Functions:

def greet
  "Hello from function!" print
end

greet  # Calls the function

Built-in Functions

Mathematical Functions

SIN, COS, TAN: Trigonometric functions.

0.5 sin print  # Outputs the sine of 0.5 radians

LOG: Natural logarithm.

10 log print  # Outputs the natural log of 10

EXP: Exponential function.
```
2 exp print  # Outputs e^2
```

Time and Date Functions

CURRENT_TIME: Gets the current timestamp.
```
current_time print
```
SLEEP: Pauses execution for a specified number of seconds.
```
2 sleep  # Pauses for 2 seconds
```

FORMAT_TIME: Formats a timestamp.

current_time "%Y-%m-%d %H:%M:%S" format_time print

Random Number Generation

RANDOM: Generates a random float between 0 and 1.
```
random print
```

RANDINT: Generates a random integer between two values.

1 10 randint print  # Random integer between 1 and 10

CHOICE: Selects a random element from a list.
```
[ "apple" "banana" "cherry" ] choice print
```

File Input/Output

OPEN_FILE: Opens a file.

"r" "example.txt" open_file  # Opens file in read mode

READ_FILE: Reads content from a file.
```
file_variable read_file print
```

WRITE_FILE: Writes data to a file.

"Some data to write" file_variable write_file

CLOSE_FILE: Closes a file.
```
file_variable close_file
```

Networking Functions

HTTP_GET: Performs an HTTP GET request.
```
"http://example.com" http_get print
```

HTTP_POST: Performs an HTTP POST request.

"http://example.com/api" "{'key':'value'}" http_post print

Examples

Hello, World

"Hello, World!" print

Factorial Calculation

var n
"Enter a number:" print
input n store
var result
1 result store

[ n fetch 1 > ]  # Condition
[
  n fetch result fetch * result store
  n fetch 1 - n store
] while

"Factorial is:" print
result fetch print

Fibonacci Sequence

var a
var b
var temp
0 a store
1 b store
10 var count count store  # Number of terms

[ count fetch 0 > ]  # Condition
[
  a fetch print
  b fetch a store
  a fetch b fetch + b store
  count fetch 1 - count store
] while

File Reading

"r" "data.txt" open_file var file file store
file fetch read_file print
file fetch close_file

Conclusion

struixLang is a versatile and powerful stack-based programming language that provides a rich set of features for both simple and complex programming tasks. Its simplicity and extensibility make it suitable for a wide range of applications, from scripting and automation to educational purposes.

struixLang Documentation

A stack-based programming language implemented in Python3.

struixLang Documentation

Table of Contents

About struixLang

Use Cases

Getting Started

Data Types

Core Concepts

The Stack

Words (Commands)

Variables and Constants

Comments

Basic Operations

Input and Output

Mathematical Operations

Stack Manipulation

Advanced Operations

Logical Operations

Bitwise Operations

String Manipulation

Multiline Strings

Lists and Arrays

Control Structures

Built-in Functions

Mathematical Functions

Time and Date Functions

Random Number Generation

File Input/Output

Networking Functions

Examples

Hello, World

Factorial Calculation

Fibonacci Sequence

File Reading

Conclusion