Introduction

XMLang is an esolang, that is also valid XML. It is a fully-functional, turing-complete programming language, that features the basic things you would expect from a programming language, such as standard input/output, variables, functions, and control flow.

Interpreter

The interpreter is written in Rust, allowing it to be relatively fast and very portable. You can run it locally on your machine, or use the WebAssembly-powered online playground to try it out easily.

License

This project is open-source on GitHub and is licensed under the GNU GPL 3.0 license.

Local installation

The XMLang interpreter is written in Rust, and can be run locally on your machine.

GitHub Actions

The interpreter is built automatically on every commit using GitHub Actions.

You can get the latest built executables for your platform from this link.

Most likely you'll want to download these files:

Building from source

Install Rust.

Clone the repository:

git clone https://github.com/GGORG0/xmlang.git

Change to the project directory:
```
cd xmlang
```
Build the project:
```
cargo build --release
```
The built executable will be located in the target/release directory. You can run it with:
```
./target/release/xmlang examples/hello.xml
```

Online playground

The online playground is available at https://xmlang.ggorg.xyz.

It automatically saves your code in the browser's local storage, so you don't lose it.

Loading code from GitHub

Note: This will replace the code you saved in the browser's local storage.

Gist

The playground supports loading code from GitHub Gist.

The Gist has to contain a single XML file with your code. If it contains multiple files, the first one will be used.

To load a Gist, get its ID (the part after your username in the URL) and append it to the playground URL like this:

https://xmlang.ggorg.xyz/?gist=8da581666cbfd662d6d5fbbe8fce3ca7

The above URL will load the code from this Gist.

Repository

The playground also supports loading code from a file in a GitHub repository.

To load a file, append the repository owner, name, branch and the path to the file to the playground URL like this:

https://xmlang.ggorg.xyz/?owner=GGORG0&repo=xmlang&branch=master&file=examples/hello.xml

The above URL will load the code from this file.

Stack

WebAssembly (via Wasmer.js) - allows running the XMLang interpreter in the browser inside a full WASI environment with a virtual filesystem.
CodeMirror - code editor
Xterm.js - terminal emulator
Vite - build tool

Building

Install the following dependencies:
- Node.js
- Pnpm (corepack enable)
- Rust (with the wasm32-wasip1 target: rustup target add wasm32-wasip1) - to build the WebAssembly module
- mdBook (optional) - to build the documentation

Clone the repository:

git clone https://github.com/GGORG0/xmlang.git

Change to the project directory:
```
cd xmlang
```
Build the WebAssembly module (optional - this will be done automatically by Vite during the build):
```
cargo build --release --target wasm32-wasip1
```
Build the documentation (optional):
```
mdbook build
```
The documentation will be built in the book directory.
Change to the playground directory:
```
cd playground
```
Install the dependencies:
```
pnpm install
```
Build the project:
```
pnpm build
```
Or start the development server:
```
pnpm dev
```

Language introduction

All XMLang code is valid XML, and can be parsed by any XML parser.

Comments are standard XML comments, and are ignored by the parser:

<!-- This is a comment -->
<element attribute1="value1" attribute2="value2">
    <child1>Child 1 content</child1>
    <child2>Child 2 content</child2>
    <!-- This is another comment -->
</element>

Note: Support for CDATA sections and entity references (for example <) is not implemented yet.

Elements

Everything in XMLang is an XML element.

An element is a tag in the XML document, which can have attributes, children, and text content.

<element attribute1="value1" attribute2="value2">
    <child1>Child 1 content</child1>
    <child2>Child 2 content</child2>
</element>

Attributes

Attributes are defined in the opening tag of an element, and are used to provide constant, static values to the element. They can't be dynamically generated or changed at runtime.

Attribute values are always strings by default, but certain built-in elements parse them as other types.

Children

Children are elements that are nested inside another element.

Some elements accept 0, 1, a predefined number, or an arbitrary number of children.

Every child element of an expression is considered an argument to that expression, and the order of the children matters. The children are evaluated in the order they appear in the XML document, and the result of each child is passed to the parent element as an argument.

An element can also be self-closing, as defined by the XML standard:

<element attribute1="value1" attribute2="value2" />

That is equivalent to:

<element attribute1="value1" attribute2="value2"></element>

Text content

Text content is the text that appears between the opening and closing tags of an element.

It is always considered a string, and has to be converted to other types if needed.

You can mix text content with other child elements, but due to parser limitations, the whitespace between the text and the child elements is not preserved, and will be ignored.

<element attribute1="value1" attribute2="value2">
    Text content
    <child1>Child 1 content</child1>
    <child2>Child 2 content</child2>
    Other text content
</element>

If you want to preserve whitespace, you can use tricks like the <space /> element or the <join> element.

<program>
    <set var="myVar">wonderful</set>
    <print>Hello <space /> <get var="myVar" /> <space /> world!</print>
</program>

When mixing text content with child elements, each text node and child element is considered a separate child of the parent element, and the order of the children matters. If you want to concatenate text content with child elements, keeping them as 1 string child, you can use the <string> element to wrap the text content and child elements together.

<element attribute1="value1" attribute2="value2">
    <string>Text content <child1>Child 1 content</child1> Other text content</string>
</element>

Internally each text content node is represented as an unnamed element (<></>), with the text as its _text attribute.

Expressions and statements

There are 2 main types of elements in XMLang: expressions and statements. Almost everything is an expression.

The 2 are distinguished by the fact that statements contain children that aren't valid elements anywhere else in the language, for example, the <if> statement contains <condition>, <then>, and optionally <else> elements, which are not valid outside an <if> statement.

Every element returns a value, which can be used by its parent element. If an element does not return a value, it is considered to return null.

Data types

XMLang has several built-in data types.

All text content in XMLang is considered a string, and can be converted to other types as needed. For example, these are different:

<set var="n"><int>42</int></set>

<print>
    <add>
        <get var="n" />
        1
    </add>
</print> <!-- prints 421 -->

<print>
    <add>
        <get var="n" />
        <int>1</int>
    </add>
</print> <!-- prints 43 -->

XMLang supports the following data types:

null: Represents the absence of a value.
int: Represents an integer value.
float: Represents a floating-point number.
bool: Represents a boolean value, either true or false.
string: Represents a UTF-8 encoded string of text.

There are no lists, arrays, dictionaries, objects, classes, or other complex data types in XMLang.

`<type>`

The <type> element is used to get the type name of a value as a string. If multiple children are present, their types are concatenated with a space.

<type>42</type> <!-- int -->
<type>3.14</type> <!-- float -->
<type>true</type> <!-- bool -->
<type>hello</type> <!-- string -->

<type>
    <int>42</int>
    <float>3.14</float>
    <true />
    hello
</type> <!-- int float bool string -->

Null

Type name: null

Rust type: ()

This is the most basic data type, representing the absence of a value.

<null />

Conversion to other types

When converting null to other types, it converts to the following values:

int: 0
float: 0.0
bool: false
string: the string null

`<unwrap>`

The <unwrap> element is used to throw an error if its child is null. If the child is not null, it returns the child value.

It optionally receives the message attribute, which is used as the error message if the child is null.

<unwrap><null /></unwrap> <!-- Error: "Unwrapped value is null" -->
<unwrap message="Custom error message"><null /></unwrap> <!-- Error: "Custom error message" -->
<unwrap><int>42</int></unwrap> <!-- 42 -->

Integer

Type name: int

Rust type: i64

An integer is a whole number, which can be positive, negative, or zero. Under the hood, integers are represented as 64-bit signed integers.

<int>42</int>
<int>-7</int>
<int>0</int>

Conversion to other types

When converting an int to other types, it behaves exactly as you would expect:

float: A float with the same value and a fractional part of .0.
bool: true if the value is non-zero, false if it is zero.
string: The string representation of the integer, e.g., the string 42.

Float

Type name: float

Rust type: f64

A float is a number that can have a fractional part, represented in decimal notation. Under the hood, floats are represented as 64-bit double-precision floating-point numbers.

<float>1.0</float>
<float>3.14</float>
<float>-2.71828</float>
<float>0.0</float>

Conversion to other types

When converting a float to other types, it behaves exactly as you would expect:

int: An integer with the same value, discarding the fractional part (always rounding down).
bool: true if the value is non-zero, false if it is zero (0.0).
string: The string representation of the float, e.g., the string 42.5.

Boolean

Type name: bool

Rust type: bool

A boolean is a data type that can have one of two values: true or false.

<bool>true</bool>
<bool>yes</bool>
<bool>anything</bool>
<true />

<bool>false</bool>
<bool>no</bool>
<false />

Conversion to other types

When converting a bool to other types, it converts to the following values:

int: 1 for true, 0 for false.
float: 1.0 for true, 0.0 for false.
string: The string representation, which is always true or false.

String (and string operations)

Type name: string

Rust type: String

A string is a UTF-8 encoded sequence of characters.

All text content in XMLang is considered a string, and wrapping it in a <string> element is optional, although sometimes it's necessary for, for example, concatenation - it ensures that the value is treated as a single string, rather than multiple children.

All children of a <string> element are evaluated, converted to strings and then concatenated into a single string (without any separators). Null values are ignored.

<string>Hello, world!</string>
<string>42</string>
<string>3.14</string>
<string>true</string>
<string>false</string>
<string />

Conversion to other types

When converting a string to other types, it behaves as follows:

int: Parses the string as an integer. If the string is not a valid integer, it will throw an error.
float: Parses the string as a float. If the string is not a valid float, it will throw an error.
bool: Converts the string to a boolean value, where all values except for the following are considered true:
- false
- 0
- off
- no
- empty string

`<space />`

The <space /> element returns a string with a single space character.

Attributes

count (int, optional): Specifies the number of space characters to return. Defaults to 1.

Keyboard shortcuts

XMLang docs