GSP(5) Manual Page

  • Home
  • Back

  • GSP(5) File Formats Manual GSP(5)

    gsplanguage reference for gsp

    The gsp language is an alternative language to HTML which can be transpiled by making use of the gsp(1) transpiler. The gsp language allows you to structure data in the same manner as HTML while offering an easier-to-read and less verbose syntax, and also some nice shortcuts. An example gsp document might look as follows:

    html lang="en" {
      head {
        meta charset="UTF-8" {}
        meta
          name="viewport"
          content="width=device-width, initial-scale=1.0"
        {}
        link href="/favicon.svg" rel="shortcut icon" type="image/svg" {}
        link href="/style.svg" rel="stylesheet" {}
        title {-My Website Title}
      }
      body {
        p #my-id  {- This is a paragraph with the id ‘my-id’     }
        p .my-cls {- This is a paragraph with the class ‘my-cls’ }
    
        p
          #some-id
          .class-1
          .class-2
          key-1="value-1"
          key-2 = "value-2"
        {-
          This paragraph has an ID, two classes, and two additional
          attributes.  GSP allows us to use the ‘#ident’ and ‘.ident’
          syntaxes as shorthands for applying IDs, and classes.  This is a
          text node, so nothing is being interpreted as GSP nodes, but we can
          include them inline if we want.  As an example, here is some @em
          {-emphatic} text.  Your inline nodes can also have attributes @em
          #id .cls {-just like a regular node}.
        }
      }
    }

    As can be seen in the above example, nodes in gsp take the form of ‘name attributes {...}’ as opposed to the more verbose ‘<name attributes>...</name>’.

    Nodes are the central building block of a gsp document, and take the form of ‘name attributes {...}’. For example, a footer node with the attributes ‘foo’ and ‘bar’ and no child nodes is written as:

    footer foo bar {}

    To nest nodes within other nodes, simply place them within the braces. As such, the following defines a footer with the attributes ‘foo’ and ‘bar’ with two empty div-nodes as children:

    footer foo bar { div{} div{} }

    When compiling an empty node ‘foo{}’, you get the result ‘<foo>’. If you want both an opening- and closing tag with no children, such as in ‘<foo></foo>’, then you can use an empty text-node as in ‘foo{-}’.

    Node names follow the exact same naming rules as names do in XML. See the XML reference in SEE ALSO for more details.

    Attributes are optional components of a node. They take the form of an attribute name and an optional attribute value. To specify an attribute, simply write the attribute name:

    name

    If you want to provide a value, you must follow the name with an equals sign (‘=’) and then wrap the value in double quotes (‘"’):

    name="value"

    You can optionally include whitespace for visual clarity, and double quotes and backslashes (‘\’) can be escaped using a backslash:

    name = "he said \"hello there\""

    Like with node names, the details about which characters are allowed within an attribute name are detailed in the XML reference found in the SEE ALSO section of this manual.

    When transpiling, you will be wanting to use IDs and classes all of the time. Due to the frequency of use of these parts of HTML, gsp offers a shorthand syntax for specifying them. The shorthand syntax looks like the equivalent CSS selectors for said IDs and classes. Valueless attributes prefixed with a period (‘.’) or hash (‘#’) are transpiled to classes and IDs respectively. Therefore the following two examples are identical:

    div #foo .bar .baz {
      div .bar {}
    }
    div id="foo" class="bar baz" {
      div class="bar" {}
    }

    It is important to note that HTML5 allows for an ID- or class name to contain just about anything, therefor ‘.→Ħ{}’ is a valid class shorthand. This is important because it means that the following doesn’t actually create a node with no children:

    div .foo{}

    You must instead include a space:

    div .foo {}

    gsp does not support document types. The HTML5 document type is automatically generated when transpiling to HTML. If you want to use a different document type, you’ll have to do that yourself. There is an example of this in the gsp(1) manual.

    If you want to include literal text within a node you can make use of the special node name ‘-’. Unlike with the usual node name, you do not need to include whitespace between the special node name and the attributes. The following example shows how you can set a page title and paragraph text:

    html {
      head {
        title {-My Amazing Website}
      }
    
      body {
        p {-
          Welcome to my website!  Here on my website you can find cute cat
          pictures, amongst other things.
        }
      }
    }

    When writing literal text, all occurrences of ‘}’, ‘@’, and ‘\’ must be backslash escaped as they have special meaning.

    If you want to embed a node within literal text, you can make use of an embedded node. Embedded nodes are exactly the same as regular nodes, but they are prefixed with the at (‘@’) symbol. For example if you want to emphasize some text in a paragraph, you could do the following:

    p {-
      This is some text, but @em .my-class {-some} of it is emphatic!
    }

    By default GSP transpiled to HTML will be automatically minified with the exception of literal text whose whitespace is untouched. Sometimes though, we want to have proper control over whitespace. The first trick to manual whitespace control is to make use of the special node name ‘=’. It acts identially to the special ‘-’ node, except it removes all leading- and trailing whitespace:

    Before
    
    p {=   Hello World
    
    }
    
    After
    
    <p>Hello World</p>

    This can be useful for trimming whitespace, but sometimes we want to preserve it. This is especially crucial with HTML ‘<pre>’ tags for which whitespace is not squashed. We can get around this issue by making use of the fact that the special ‘-’ node does not trim whitespace. The following is an example of how not to display two seperate lines in a ‘<pre>’ tag:

    Before
    
    pre {
    	code{-Foo}
    	code{-Bar}
    }
    
    After
    
    <pre><code>Foo</code><code>Bar</code></pre>

    Instead, you can do the following:

    Before
    
    pre {-
      @code{-Foo}
      @code{-Bar}
    }
    
    After
    
    <pre>
      <code>Foo</code>
      <code>Bar</code>
    </pre>

    If you would like to have the whitespace between the opening- and closing ‘pre’ tags and the inner ‘code’ tags removed, you can use the ‘=’ node instead of the ‘-’ node.

    gsp(1)

    Extensible Markup Language (XML) Reference

    Thomas Voss <[email protected]>

    November 1, 2023 MangoOS