VORKUTA5 Documentation

Semicolons

Use ; to separate statements from other ones. This allows for multiple lines to be compressed to 1.

Original:

REPEAT 5 AS i:
    OUT i
END

Compressed:

REPEAT 5 AS i; OUT i; END;

When using semicolons to separate statements, all colons on any command (like repeat) should be replaced with ;. Also keep in mind you can mix compressed and uncompressed lines but it is recommended to not.

Output

Use OUT to print a value. By default it does not add a newline.

OUT "Hello, World!"

Add &wrap (or &w) at the end to print with a newline:

OUT "Hello" &wrap
OUT "World" &wrap

Use WRAP on its own line to print a blank newline:

OUT "Hello"
WRAP
OUT "World"

Variables

Variables store text values. Declare and assign them with VARIABLE (shorthand: v).

VARIABLE name = "Alice"
OUT name

You can reassign a variable at any time:

VARIABLE color = "red"
VARIABLE color = "blue"
OUT color

Variables, along with all other value types, can be defined automatically by simply not providing a type.

color = "red"
color = "blue"
OUT color

For the rest of the documentation, I will continue to use explicit type definition. Just know that it's NOT required.

String Interpolation

Embed a variable or expression inside a string using {...}:

VARIABLE name = "Alice"
OUT "Hello, {name}!"

Global Variables

To make variables accessible in every scope, prefix the declaration with GLOBAL:

GLOBAL VARIABLE name = "Alice"

String Literals

VORKUTA5 has two kinds of string literals: regular strings and raw strings.

Regular Strings

Written with double or single quotes. Supports {...} interpolation.

VARIABLE item = "apple"
OUT "I have an {item}"

Raw Strings (backticks)

Written using backticks. Raw strings do not support interpolation. Useful for JSON, templates, and literal content.

VARIABLE greeting = "Hello, world!"
OUT `Greeting: {greeting}`
^ Outputs 'Greeting: {greeting}' NOT 'Greeting: Hello, world!'

String Methods

String methods are accessed with dot notation on any string variable.

Counters

Counters are integer variables. Explicitly define them with COUNTER (shorthand: c).

COUNTER score = 0
OUT score

Or implicitly define them like so:

score = 0
OUT score

Quickly increment or decrement with + / -:

COUNTER score = 0
+ score
+ score
- score
OUT score
^ Outputs: 1

Floats

When explicitly defining variables, you cannot use COUNTER for floats. Instead use FLOAT.

FLOAT pi = 3.145

Compound Assignment

All assignment shorthands work on both variables and counters:

COUNTER n = 10
n += 5
n -= 2
n *= 3
n /= 2
OUT n

VARIABLE text = "hello"
text += " world"
OUT text
^ Outputs: hello world

Counter Properties

COUNTER x = 0
OUT x.zero? &wrap
^ true
+ x
OUT x.zero? &wrap
^ false

Operators & Expressions

VORKUTA5 supports arithmetic, comparison, and logical operators anywhere an expression is expected.

Arithmetic

COUNTER result = 3 + 4 * 2
OUT result
^ Outputs: 11

COUNTER result = (3 + 4) * 2
OUT result
^ Outputs: 14

Comparison

Logical

Taking User Input

Get user input with the .take method. The string it's called on is the prompt shown to the user.

VARIABLE name = "What's your name? ".take
WRAP
COUNTER age = "How old are you? ".take
WRAP
OUT "My name is {name}! I am {age} year(s) old!" &wrap

TAKE requires the user to press Enter. For single-keystroke input without waiting for Enter, use KEYPRESS:

KEYPRESS -> key
OUT "You pressed: {key}" &wrap

Control Flow

Run a block of code only when a condition is true. The body is indented under the IF line.

VARIABLE score = "85"
IF score >= 80:
    OUT "Pass" &wrap
END

IF / ELSE

VARIABLE score = "55"
IF score >= 60:
    OUT "Pass" &wrap
ELSE:
    OUT "Fail" &wrap
END

ELSE IF

VARIABLE score = "72"

IF score >= 90:
    OUT "A" &wrap
ELSE IF score >= 80:
    OUT "B" &wrap
ELSE IF score >= 70:
    OUT "C" &wrap
ELSE:
    OUT "D" &wrap
END

Combining Conditions

VARIABLE age = "25"
VARIABLE member = "true"
IF age >= 18 AND member = "true":
    OUT "Welcome!" &wrap
END

Using Boolean Properties

COUNTER score = 0
IF score.zero?:
    OUT "You lose!"
END

Ternary IF-ELSE statements

Ternary IF-ELSE statements are if else statements that return 1 of 2 values depending on if they are true or not. They are intended to be used directly in strings for simplicity. Example: true ? condition : false !

REPEAT 5 AS i:
    OUT "three!" ? i = 3 : "not three." ! &w
END

You can also nest them like so:

REPEAT 5 AS i:
    OUT "one!" ? i = 1 : ("two!" ? i = 2 : "higher than 2" ! ) ! &w
END

Loops

WHILE

Repeats a block as long as a condition is true.

COUNTER i = 0
WHILE i < 5:
    OUT "{i} " &wrap
    i += 1
END

Use EXIT to break out of a loop early:

COUNTER i = 0
WHILE i < 100:
    IF i = 3:
        EXIT
    END
    OUT "{i} " &wrap
    i += 1
END

REPEAT

Repeats a block a fixed number of times.

REPEAT 5:
    OUT "hello" &wrap
END

Track the current iteration count with AS:

REPEAT 3 AS i:
    OUT "Iteration {i}" &wrap
END

Increment by more than 1 with +=:

REPEAT 4 AS i: += 2
    OUT "Iteration {i}" &wrap
END

Lists

Lists are ordered collections of values, pretty much just arrays. Explicitly declare them with LIST (shorthand: l).

LIST fruits = ["apple", "banana", "cherry"]

^ Multi-line form:
LIST fruits = [
  "apple",
  "banana",
  "cherry"
]

Access items by index (starts at 0), print the whole list, or get its length:

OUT fruits[0] &wrap
OUT fruits[2] &wrap
OUT fruits       ^ print entire list
OUT fruits.length &wrap

Assign to an index:

fruits[1] = "blueberry"
OUT fruits[1] &wrap

Empty List

LIST items

Nested Lists

LIST matrix = [["1", "2"], ["3", "4"]]
OUT matrix[0][1] &wrap
^ Outputs: 2

FOR Loop

LIST colors = ["red", "green", "blue"]
FOR color IN colors:
    OUT color &wrap
END

Count iterations with AS:

LIST colors = ["red", "green", "blue"]
FOR color IN colors AS reps:
    OUT reps &wrap
END

List Methods

Called with dot notation on any list variable.

Tables

Tables are key-value stores identical to JSON dictionaries. Declare them with TABLE (shorthand: t).

TABLE person = {
    "name": "Alice",
    "age": "30",
    "city": "New York"
}

Access values, assign to keys, and get the entry count:

OUT person["name"] &wrap
OUT person.name &wrap
^ values can be accessed like this however you cannot update values like this.

person["age"] = "31"

person.age = "31"
^ This doesn't work

OUT person.length() &wrap

Nested Tables

TABLE config = {
    "server": {
        "host": "localhost",
        "port": "8080"
    },
    "debug": false
}

OUT config["server"]["host"] &wrap

Tables with List Values

TABLE data = {
    "colors": ["red", "green", "blue"],
    "count": "3"
}

FOR i IN data["colors"]:
    OUT i &wrap
END

FOREACH loop

TABLE scores = {"Alice": "95", "Bob": "87", "Carol": "92"}
FOREACH name, score IN scores:
    OUT "{name}: {score}" &wrap
END

Count iterations with AS:

FOREACH name, score IN scores AS reps:
    OUT "{name}: {score} | {reps}" &wrap
END

Table Methods

All table methods use dot notation.

TABLE inventory = {"apples": "10", "bananas": "5"}

OUT inventory.has("bananas") &wrap   ^ true
inventory.drop("bananas")
OUT inventory.size &wrap              ^ 1
inventory.set("oranges", "20")
OUT inventory["oranges"] &wrap        ^ 20

.keys and .values

TABLE prices = {"apple": "1", "banana": "2", "cherry": "3"}
LIST k = prices.keys
LIST v = prices.values

JSON Serialization

^ Table to JSON string:
VARIABLE json = myTable.static

^ JSON string to Table:
TABLE parsed = jsonString.dynamic()

Sleep

Pause the script temporarily with SLEEP time

Example

OUT "1"
SLEEP 5
OUT "2"

Functions (Programs)

Define functions with PROGRAM. Explicitly call them with CALL or just use the function name without call. Return a value with RETURN.

Basic Function

PROGRAM greet:
    OUT "Hello from greet!" &wrap
END

CALL greet
^ Or alternatively:
greet()

Function with Parameters

PROGRAM add(a, b):
    VARIABLE result = a + b
    RETURN result
END

OUT add(10, 5) &wrap
^ Outputs: 15

Inline Call in Expressions

Use funcname(args) directly inside {...} to embed a call inline:

PROGRAM square(x):
    RETURN x * x
END

OUT "Square of 5 is: {square(5)}" &wrap

Returning a List

PROGRAM make_list:
    RETURN ["x", "y", "z"]
END

LIST result = make_list()
OUT result &wrap

Returning a Table

PROGRAM make_user(n, a):
    RETURN {"name": n, "age": a}
END

TABLE user = make_user("Bob", "25")
OUT user["name"] &wrap

Built-in functions

VORKUTA5 has a few built-in functions for your convenience

Classes

Classes define a reusable blueprint for object-oriented programming. Data stored in classes uses the class's own scope, not the global scope.

CLASS Animal:
    VARIABLE name = "unknown"
    VARIABLE sound = "..."
END

VARIABLE cat = Animal.new
VARIABLE cat.name = "Cat"
VARIABLE cat.sound = "Meow"
OUT cat.name &wrap
OUT cat.sound &wrap

Methods in Classes

Classes can contain programs that act as methods. Programs inside classes cannot see class-level variables directly, you can use RELATIVE for shared scope:

CLASS Counter:
    RELATIVE COUNTER count = 0
    PROGRAM increment:
        + count
    END
    PROGRAM reset:
        RELATIVE COUNTER count = 0
    END
END

VARIABLE timer = Counter.new
CALL timer.increment
CALL timer.increment
CALL timer.increment
OUT timer.count &wrap
^ Outputs: 3
CALL timer.reset
OUT timer.count &wrap
^ Outputs: 0

Libraries

Import libraries from the stdlibs folder with IMPORT. Template:

IMPORT 'library_name.v5' AS alias

Any library outside of the stdlibs folder can still be used by providing the entire directory instead of just the name.

After importing libraries, you can access their functions, variables, etc. using their alias. All custom methods however will be directly put into and accessible in the main script without needing the alias.

Libraries have completely separate scopes from the main script and the only way to access data from the library's script is via the alias. Libraries cannot use functions or get variables from the main script.

Example:

main.v5

IMPORT 'example.v5' AS ex
ex.say("Test!", 3)

example.v5

PROGRAM say(text, amt):
    REPEAT amt:
        OUT text &w
    END
END

Custom Methods

In addition to built-in methods, you can define your own. Methods are similar to programs but attached to a data type. self holds the value being operated on; self.type holds its type name.

VARIABLE:METHOD method_name:
    ^ ... put code here ...
    RETURN self
END

Accept multiple types by separating them with commas:

VARIABLE, COUNTER:METHOD name:
    ^ ...
    RETURN self.type
END

Methods with Parameters

VARIABLE:METHOD multiply(amount):
    RETURN self * amount
END

OUT `hello`.multiply(3)
^ Outputs: hellohellohello

Using Ruby in VORKUTA5

VORKUTA5 lets you embed and run Ruby code directly. The last expression in the Ruby block is the return value.

RUBY ():
    puts "Hello, world!"
    200
END

Passing Variables and Getting Output

VARIABLE input_example = "Hello, world!"
RUBY (input_example):
    puts input_example
    "Done executing!"
END => output_var

OUT output_var
^ Outputs: Done executing!

Sending Commands to the System

Run system shell commands with exec(). It's recommended to use a raw string (backticks) for the command to avoid symbol conflicts.

OUT exec(`ls`) &wrap

Miscellaneous Commands

COLOR

Set the terminal text color. Available colors: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, bold variants (BOLDRED, etc.), and RESET.

COLOR RED
OUT "This is red"
COLOR RESET
OUT "Normal again"

DEBUG

Print each line before it executes, useful for tracing bugs.

DEBUG true
OUT "This line will be traced"
DEBUG false

SAVE

Save the current script state to a file.

SAVE "output.v5"

FORCE_CLOSE

Immediately terminate the interpreter.

FORCE_CLOSE

DISABLE

Disable a command so it does nothing when encountered.

DISABLE $OUT

!IGNOREWARNINGS

Suppress all runtime warnings and errors.

!IGNOREWARNINGS

Interacting with Files

Before being able to interact with files, you need to import the file library. IMPORT 'file.v5' AS File.

Writing to Files

IMPORT 'file.v5' AS File
f = File.open('example.txt')

f.write("Hello, world!")
^ Puts Hello, world! on the first line of the file.
			
f.write(["Line 1!", "Line 2!", "Line 3!"])
^ Each index of a list/array is a new line on the file. 
^If you want to put the raw array into the file for like JSON, first convert it to a string with .static

Reading Files

IMPORT 'file.v5' AS File
f = File.open('example.txt')
contents = f.read()

FOR i IN contents:
    OUT i &w
END
^ .read() returns an array with each index assigned to each line

Deleting Files

IMPORT 'file.v5' AS File
File.open('example.txt').delete()

Creating Web Applications

Defining Routes

Each route is defined with SERVER. You must always specify the allowed HTTP methods.

^ GET only:
SERVER ('/', ('GET')):
    OUT "Got a GET request!" &wrap
    RETURN "Hello from VORKUTA5"
END

^ GET and POST:
SERVER ('/', ('GET', 'POST')):
    RETURN "Handled"
END

Request Object

Starting the Server

SERVER ('/', ('GET')):
    RETURN "Hello"
END

SERVER.start()

Serving External Files

Return a filename string to serve an HTML file directly:

SERVER ('/', ('GET')):
    RETURN 'index.html'
END

SERVER.start()

Multiple Routes

SERVER ('/', ('GET')):
    RETURN 'main'
END

SERVER ('/about/', ('GET')):
    RETURN 'about'
END

SERVER.start()

Full Example

^ app.v5
SERVER ('/', ('GET')):
    RETURN 'index.html'
END

SERVER.start()