STxT: The Book

If you were to read only one chapter of this book, this would be the chapter. We explain what STxT is directly, without further ado. And we also give you enough knowledge to read any other chapter.

An Example... Right Now!

Documents Without Namespace

This is the first language I know of where you can start with an example and everyone can understand it.

The example will be a recipe. Let's go!

Recipe: Macaroni Recipe
    Description:
        :This is the description of the macaroni recipe.
        :Bla, bla, bla
        :Bla, bla, bla
    Servings: 3
    Difficulty: easy
    Ingredients:
        Ingredient: (100g) Tomato
        Ingredient: (240g) Macaroni
    Steps:
        Step: (1) Make the sauce
        Step: (2) Boil the macaroni
        Step: (3) Mix the macaroni with the sauce and serve

Easy, right? Okay, I'm not a great chef :-D but it’s perfectly understandable.

Well, you’ve just seen what a STxT document without a namespace looks like. These types of documents are structured, but we don’t know the shape of the nodes. However, you can already see that they have structure, with a main node Recipe, which has a Description node, Ingredients, etc. These nodes in turn have others, and so on, forming a hierarchical structure.

It’s worth mentioning the Description node, which is a node that allows multilines. Without a predefined structure, they are distinguished by being indented but with lines that have no preceding label. This is very important for documents without a namespace.

Documents With Namespace

Now we’ll go further and define the same recipe with a namespace. First, we’ll show the recipe, and then we’ll show the namespace. You might think it should be done the other way around, but the reality is that most of the time, we’ll have an example and later define the general case.

Here’s the recipe:

Recipe (www.kocinando.com/receta.stxt): Macaroni Recipe
    Description:
        This is the description of the macaroni recipe.
        Bla, bla, bla
        Bla, bla, bla
    Servings: 3
    Difficulty: easy
    Ingredients:
        Ingredient: (100g) Tomato
        Ingredient: (240g) Macaroni
    Steps:
        Step: (1) Make the sauce
        Step: (2) Boil the macaroni
        Step: (3) Mix the macaroni with the sauce and serve

What has changed? Well, now the recipe has an associated namespace, which is www.kocinando.com/receta.stxt, and the Description node seems more natural. That’s it :-) We’ve converted a document without a namespace into one with a namespace, just by adding who it belongs to and removing the : character from the multiline fields.

It couldn’t be simpler ;-)

Now let’s create the namespace. The namespace definition is found in a document without a namespace. In the previous version of STxT, it wasn’t like this, but it complicated the parsers and forced you to always have a namespace definition. Now this has changed, and everything has been greatly simplified.

Here’s the namespace we can create for the example:

Namespace: www.kocinando.com/receta.stxt
    Recipe:
        Description: (?) TEXT
        Servings: (?) NUMBER
        Difficulty: (?) ENUM
               : easy
               : medium
            : hard
        Ingredients: (1)
            Ingredient: (+)
        Steps: (1)
            Step: (+)

It’s very intuitive, the structure itself is a reflection of the hierarchical order, indicating the type of node if necessary.

The namespace should be accessible via the internet, at the same URL that indicates it. Thus, this namespace should be available at https://www.kocinando.com/receta.stxt. Parsers should also have it available locally, and it’s better that way for performance.

We’ll talk more about namespaces later, but creating a document from them should be much simpler than in other languages.

Other Elements

Comments

It’s possible to insert comments in the documents to express unfinished parts, the author’s thoughts, etc. Comments won’t be used but allow enriching the document.

Recipe (www.kocinando.com/receta.stxt): Macaroni Recipe
# This recipe was given to me by XX and I’ve made it many times
# You’ll love it!!
    Description:
        This is the description of the macaroni recipe.
        Bla, bla, bla
        Bla, bla, bla
    Servings: 3
    Difficulty: easy
    Ingredients:
        Ingredient: (100g) Tomato
        Ingredient: (240g) Macaroni
    Steps:
        Step: (1) Make the sauce
        Step: (2) Boil the macaroni
        Step: (3) Mix the macaroni with the sauce and serve

Different Namespaces in a Document

A namespace can refer to another one, to indicate that part of the document has its structure in another namespace. It’s better to see an example:

Namespace: www.kocinando.com/recetario.stxt
    RecipeBook:
        Recipe: (+) (www.kocinando.com/receta.stxt)

Here we see that Recipe is from another namespace, and instead of providing the structure, it refers to another namespace.

So, an example of a recipe book would be:

RecipeBook (www.kocinando.com/recetario.stxt): Mom’s Recipes 
    Recipe: Macaroni Recipe
        Description:
            This is the description of the macaroni recipe.
            Bla, bla, bla
            Bla, bla, bla
        Servings: 3
        Difficulty: easy
        Ingredients:
            Ingredient: (100g) Tomato
            Ingredient: (240g) Macaroni
        Steps:
            Step: (1) Make the sauce
            Step: (2) Boil the macaroni
            Step: (3) Mix the macaroni with the sauce and serve    
    Recipe: Pizza Recipe
        Ingredients:
            Ingredient: (1u) Pizza dough
            Ingredient: (100g) Tomato
            Ingredient: (50g) Cheese
        Steps:
            Step: (1) Add tomato and cheese to the pizza
            Step: (2) Bake for 15 minutes

End of the Tutorial