TagScript Docs

Basic Syntax

Basic Tag Structure

A tag in TagScript is opened with an opening angle bracket < and closed with a closing one >. There must be a tag which opens the body <example> and a tag that closes it </example>. Inside the opening tag, the programmer must specify the name of the tag to use. Tags also have attributes that can be declared on the opening tag. Everything between the opening and closing tag is considered 'body'.

<ex foo="bar">
    # Body goes here...
</ex>

Here, we have the 'ex' tag, which defines a 'foo' attribute with a value of "bar". The # symbol is used to mark a comment in TagScript, in this case, it marks where the body is.

Self Closing Tags

Some tags in TagScript do not need a body to be used, so they can be written as self-closing tags. These are declared by putting a forward slash just before the closing bracket in a regular opening tag.

<ex foo="bar"/>

This is equivalent to:

<ex foo="bar"></ex>

Attributes

Attributes in TagScript are the primary way to pass information on how a tag should be executed. Attributes can be self-declared or require a value.

<output>
    "Hello World!"
</output>

This displays:

Hello World!

The output tag accepts multiple tags in its body, so we can print multiple things in one go.

<output>
    "Hello "
    "World!"
</output>

This displays:

Hello 
World!

To change this behavior, we can add the no-autobreak attribute:

<output no-autobreak>
    "Hello "
    "World!"
</output>

This now displays:

Hello World!

Nesting

Nesting is TagScript's way of passing static and non-static information directly into a tag via its body. For example:

<var name="foo" type="string">
    "Hi!"
</var>

This will directly insert the string literal "Hi!" into the value of the variable 'foo'. We can then insert the value of 'foo' into an output tag by using the get tag:

<output>
    <get name="foo"/>
</output>

This displays:

Hi!

Memory & Data

Data Types

The three data types in TagScript are:

string
number
boolean

Data Literals

Data literals are shorthands for the <text-lit/> and <number-lit/> tags.

"Hi!" # This is a string literal

Is a shorthand for:

<text-lit body="Hi!"/>

While:

[2] # This is a number literal

Is a shorthand for:

<number-lit value="2"/>

Variables

Variables are declared using the var tag and can be assigned values using the set tag.

<var name="foo" type="string"/>
<set name="foo">
    "Hello"
</set>

Constants

Constants are planned for the future, stay tuned!

Expressionism

Operative Tags

Operative tags are used for arithmetic operations. Each operative tag only accepts a certain number of tags in its body depending on the operation.

<output>
    <negate>
        [2]
    </negate>
</output>

This displays:

-2

And:

<output>
    <add>
        [3]
        [4]
    </add>
</output>

displays:

Auto-Operative Tags

Auto-Operative tags automatically assume their body is an expression and try to obtain the result of it. Examples of auto-operative tags include var, condition, return, and set.

<var name="auto-operation" type="number">
    <add>
        [2]
        [5]
    </add>
</var>

This declares the variable auto-operation with a value of 7.

<set name="auto-operation">
    <multiply>
        [7]
        [8]
    </multiply>
</set>

Now the value of auto-operation is 56.

Control

If / Elif / Else

Control flow in TagScript is managed using if, elif, and else tags. Each if/elif tag must have a condition tag, which is auto-operative. The result of the expression in the condition tag must be a boolean.

<if>
    <condition>
        <compare>
            <get name="auto-operation"/>
            [56]
        </compare>
    </condition>
    <output>
        "The number is 56!"
    </output>
</if>
<elif>
    <condition>
        <compare>
            <get name="auto-operation"/>
            [54]
        </compare>
    </condition>
    <output>
        "The number is 54!"
    </output>
</elif>
<else>
    <output>
        "Could not recognize the number!"
    </output>
</else>

While

The while tag executes a piece of code until the condition is no longer true.

<while>
    <condition>
        <negate>
            <compare>
                <get name="auto-operation"/>
                [100]
            </compare>
        </negate>
    </condition>
    
    <set name="auto-operation">
        <add>
            <get name="auto-operation"/>
            [1]
        </add>
    </set>
</while>

This will add 1 to auto-operation until it is equal to 100.

For

For loops are planned for the future, stay tuned!

Functions

Built-In Functions

Built-In functions are planned for the future, stay tuned!

User defined Functions

User defined Functions are planned for the future, stay tuned!

Error Handling

Try / Catch

Error handling in TagScript is managed using try and catch tags. If something goes wrong in the try block, the catch block gets executed. You can also save the error message if you want to.

<var name="errormsg" type="string"/>

<try>
    # Unsafe code
    <input save-to="auto-operation" prompt="PLEASE type a number"/>
    <output>
        "Thanks!"
    </output>
</try>
<catch save-to="errormsg">
    <output>
        "Why didn't you type a number :("
        "This is the error you caused!:"
        <get name="errormsg"/>
    </output>
</catch>

Error Format

If you don't handle possible unsafe code with a try / catch block or just make a mistake while programming, you'll run into interpreting exceptions, for example:

# Declare the variable
<var name="MyNum" type="number"/>

# Now get the user input
<input save-to="MyNum" prompt="Please type a number: " no-autobreak/>

# Output the number
<output no-autobreak>
    "Your number is: "
    <get name="MyNum"/>
</output>

This piece of code looks innocent enough, but when we try to run it:

### FATAL ###
i: nummer is not valid datatype
ERR-4003: ATTRIBUTE VALUE ERROR
| AT LINE 2 : COLUMN 2
|0000| # Declare the variable
|0001| <var name="MyNum" type="nummer"/>
        ^^^

TagScript has its own exception system to assure the programmer has the most information available when trying to debug the program, so let's break down the format of an exception.

Exception Type: In this case, as we can see in the first line, it's fatal exception, there also are 'warnings' and 'info' although they are currently not implemented.
Error Information: A little bit more specific than the error code, while the error code tells us that it was an attribute error, the error information tells us that is has something to do with the 'type' attribute, as it's the only one that has the value nummer.
Error Code: Serves the purpose of being the identifier of the error, you can look up the error number on this documentation to see common causes and solutions.
Source code visual: Depending on the error, this visual may or may not be present, but it is very useful for pinpointing the error source, in this case, line 2 at the 'var' tag.

Thanks to all this, we can now see that the error was that we misspelled 'number' as 'nummer'. We fix this mistake and now we see the intended output:

Please type a number: 8
Your number is: 8

Internal Errors

Internal errors are formatted as IMODULENAME_ERROR at the beginning of the error code. These errors are not the fault of the programmer. If you encounter one without having made any modifications to the interpreter, you should report it immediately as a GitHub issue, including the source code that triggered the error.

If you are modifying the interpreter, these errors indicate a failure in the correct implementation of certain features. For example, this might occur if you bind a tag as operative but do not assign it an operative type.