Introduction & Design

At the heart of Stof is not a data format or language, but rather a tried and tested strategy for organizing and combining large amounts of diverse data types and relationships.

Stof is a special kind of DAG with an Entity Component System built into it. Data in Stof can be thought of as components, and the nodes of the DAG are entities. Each node is capable of housing an unknown amount of diverse data types.

If those words don't make a whole lot of sense, think about Stof as a fancy version of your file explorer - directories (nodes) organize different types of files (data).

The purpose of this page is to provide you with a mental model of Stof, which will help immensely in getting started and in understanding what Stof can do.

Mental Model

This structure is not new - it's one of the most common ways to store data. Every data format that exists is a DAG (or can be expressed as/within one), which is how Stof can be so universal.

Concrete Example

The language around Stof is just a set of data components that know how to manipulate and describe the document that contains them. As such, we can express the following Stof document in terms of our mental model.

person: {
    name: {
        first: "Bob"
        last: "Jones"
    }
    fn get_name() -> str { return self.name.first + " " + self.name.last; }
}

#[main]
fn main() {
    pln(self.person.get_name());
}

Actual Model

So far, we have a convenient and human-friendly way to think about Stof. For using Stof, that's all you need to get started!

However, Stof, in reality, is a bit more complicated, so it can be more efficient and model more complex relationships.

This strategy allows Stof to structure data in many ways simultaneously and more than once, without any copies, while preserving the simplicity of our mental model (behaviorally).

Data is kept as a flat collection, completely separate from their relationships and any structure Stof introduces.

Stof's DAGs are also kept completely separate and flat, offering a lightweight and flexible way to model data. Each node can be thought of as its own DAG, but Stof also has the concept of having multiple roots. These roots can be traversed with the language and used to compartmentalize different sections of unified data entirely.

Concrete Example

For consistency, let's use the same example as before:

person: {
    name: {
        first: "Bob"
        last: "Jones"
    }
    fn get_name() -> str { return self.name.first + " " + self.name.last; }
}

#[main]
fn main() {
    pln(self.person.get_name());
}

Although still a bit simplistic, this is how Stof represents data and relationships. By now, you've probably put together a lot about the language - how paths are just a dot-separated way to traverse nodes by name, or maybe how objects are just fields pointing to other nodes that contain general buckets of data (not just fields and functions).