include homepage.en.yhtml2

page "The Features" {
    h2 id="text" > Text

    p   >>
        To output text nodes (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax character data¬),
        write literals. There are integer literals, floating point literals and text literals.
        >>

    p   >>
        Literals are written
        ¬http://docs.python.org/reference/lexical_analysis.html#id7 like in Python¬,
        that means, text literals are in single or double quotes, or in triple double quotes:
        >>

    Code    ||
            "text" 'also text' """some more text"""
            42 "an integer and" 42.23 "a floating point literal"
            ||

    h2 id="functioncalls" > Function Calls

    p   >>
        The main idea of YML scripts is calling functions which then generate
        XML tags (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax Markup¬).
        Functions are generating single tags, lists or trees of tags.
        >>
    
    p   >>
        To call a function, write the name of the function, followed by a comma separated list
        of function parameters (C like syntax). Unlike C, you don't need to insert the parameter
        list into parentheses. A simple function call is terminated by a semicolon «;»
        >>
    
    p   >>
        It does not matter, if you're calling your function using parentheses or brackets or without.
        So these statements are equal:
        >>

    Code    ||
            foo "hello, world";
            foo("hello, world");
            foo["hello, world"];
            ||

    h3 id="subtree" > Subtrees

    p   >>
        If you omit the tailing semicolon, you're creating a Subtree; YML Subtrees can also be
        opened and closed with braces:
        >>

    Code    ||
            foo {
                bar {
                    something;
                }
            }
            ||

    p > If a Subtree only consists of one single subelement, then you may omit the braces:

    Code    ||
            foo
                bar;
            ||

    h3 id="named" > Named Parameters

    p   >>
        To generate ¬http://www.w3.org/TR/2008/REC-xml-20081126/#attdecls attributes¬ by calling
        a function, you can use Named Parameters.
        >>

    p   >>
        For that case, assign literals to attribute names like the following.
        The name of the parameter then will be used as the name of the generated attribute.
        An example:
        >>

    Code    ||
            div id="sample" {
                "this is a " a href="#sample" "link sample"
            }
            ||

    p > This generates:

    Code | <div id="sample">this is a <a href="#sample">link sample</a></div>

    h3 > Unnamed Parameters

    p   >>
        Unnamed Parameters prepare values for predefined attributes. The following example is
        equivalent to the sample above:
        >>

    Code    ||
            decl a(href);
            decl div(id);

            div "sample" {
                "this is a " a "#sample" "link sample"
            }
            ||

    p > If no predefined attribute can be allocated, the value of the parameter is added to the body.

    h3 > Calling with &

    p   >>
        Especially if you have a ¬#defaultbody default body¬ for your function, calling with
        a leading «&» can be sensible: then the tag itself is omitted and only the body is being output:
        >>

    Code    ||
            decl something { tag1; tag2; };

            list {
                &something;
            }
            ||

    p > results in:

    Code    ||
            <list>
              <tag1/>
              <tag2/>
            </list>
            ||

    p   >>
        This has the same result as ¬#alias aliasing¬ «something» to «-».
        >>

    h3 id="funclist" > Function Lists

    p   >>
        Function Lists are a feature of YML to simulate a more C like syntax. Let's have some
        examples. You can have a list of functions whereever you can have a function. Function
        Lists are comma separated:
        >>

    Code    ||
            x i, j, k
            ||

    p > compiles to:

    Code    ||
            <x>
              <i/>
              <j/>
              <k/>
            </x>
            ||

    h3 id="paramlists" > Parameter Lists

    p   >>
        A sample together with ¬#descending Descending Attributes¬:
        >>

    Code    ||
            decl Interface +name;
            decl attr +type +name;
            decl func +type +name;

            Interface Icecream {
                attr color flavour;
                attr long number;
                func int getPrice();
                func void addFlavour(in color flavour, in long number);
            }
            ||

    p > compiles to:
    
    Code    ||
            <Interface name="Icecream">
              <attr type="color" name="flavour"/>
              <attr type="long" name="number"/>
              <func type="int" name="getPrice"/>
              <func type="void" name="addFlavour">
                <parm>
                  <in/>
                  <color/>
                  <flavour/>
                </parm>
                <parm>
                  <in/>
                  <long/>
                  <number/>
                </parm>
              </func>
            </Interface>
            ||

    p   >>
        Note the «parm» tags - they're generated by default, if you write a Parameter List
        behind a Function Call. That differs from calling the function with parameters -
        ¬#functioncalls calling¬ means using ¬#text text¬ values.
        >>

    p   >>
        The «parm» tags are emitted, because the «_parm» function is called each time
        such a parameter will be emitted.
        >>

    p   >>
        If you want to have the «_parm» function doing other things, just ¬#decl declare¬
        it in another way.
        >>

    h3 id="generics" > Generic Declarations

    p   >>
        Using Generic Declarations is just like using ¬#paramlists Parameter Lists¬ - use angle brackets
        instead of parentheses. For Generic Declarations, the «_generic» function is called each
        time such a Generic Declaration will be emitted, generating «generic» tags as the default:
        >>

    Code | max<int>(x, y)

    p > compiles to:

    Code    ||
            <max>
              <generic>
                <int/>
              </generic>
              <parm>
                <x/>
              </parm>
              <parm>
                <y/>
              </parm>
            </max>
            ||

    h2 id="decl" > Declaring Functions: decl

    p   >>
        As default, each Function Call generates one XML tag, which has the same name. To be exact,
        the XML tag has dashes in it's name where the YML function has underscores.
        >>

    p   >>
        To define, how tags and attributes look like, which are created by a Function Call, you
        can use the «decl» statement.
        >>

    h3 > Trivial Declarations

    p > In a trivial declaration, you're just declaring the Function Name and so the XML tag name:

    Code | decl html, head, title, body, p, a;

    p > As seen in the example, multiple declarations can be done in a comma separated list.

    p   >>
        Because trivial declarations are done automatically, if you're using a function for the
        first time, you usually don't need to declare this way.
        >>

    h3 > Specifying Unnamed Parameters

    p   >>
        To specifiy Unnamed Parameters, give the parameter list comma separated in parentheses
        or provide one or more brackets with parameter lists in them:
        >>

    Code | decl a(href), img[src];

    p   >>
        If you're using the corresponding functions a() and img() together with an unnamed parameter
        in a call, then these attributes are used for applying the values, respectively:
        >>

    Code | a "http://www.ccc.de" "The Club Homepage" img "logo.png";

    p > These Function Calls generate:
    
    Code | <a href="http://www.ccc.de">The Club Homepage</a><img src="logo.png"/>

    h3 id="defaultattr" > Giving Default Values for parameters

    p   >>
        To give default values for generating XML attributes, assign a literal to each named parameter
        in the declaration parentheses or brackets. Two examples, which do the same:
        >>

    Code
        ||
        decl img(src, alt="picture");
        decl img[src][alt="picture"];
        ||

    h3 id="alias" > Aliasing: using different YML functions for the same XML tag for different tasks

    p   >>
        Sometimes tags are used in different ways to do different things. For this case, you can
        use aliasing. Aliasing means, the YML function name and the XML tag name differ. For example:
        >>

    Code | decl a(href), target(name) alias a;

    p > Both defined YML functions then generate «<a />» tags - but the Unnamed Parameter differs.

    p   >>
        The alias name «-» has a special meaning: it omits the tag in the output. That is especially
        sensible if you have a ¬#defaultbody default body¬. Then an alias to «-» has the same meaning
        as starting the function call with the «&» character: only the body is emitted.
        >>

    h3 id="descending" > Specifying Descending Attributes

    p   >>
        Maybe you want to write something like this:
        >>

    Code    ||
            Module ERP {
                Interface Customer {
                    // ...
                }
            }
            ||

    p > Without any extras, this compiles to:

    Code    ||
            <Module>
                <ERP>
                    <Interface>
                        <Customer />
                    </Interface>
                </ERP>
            </Module>
            ||

    p   >>
        For this case, it would be practical, if «ERP» would not be interpreted as extra tag
        but as value for an attribute «name». This you can achive with Descending Attributes:
        >>

    Code | decl Module +name, Interface +name;

    p > With this declaration, the code sample above is compiling to:

    Code    ||
            <Module name="ERP">
                <Interface name="Customer" />
            </Module>
            ||

    h3 id="defaultbody" > Supplying a Default Body

    p   >>
        Additionally, you can supply a Default Body for each tag. For that case, add a YML function
        block in braces to your declaration:
        >>

    Code    ||
            decl pageContent alias body {
                a name="top";
                include heading.en.yhtml2;
                div id="entries"
                content;
            };
            ||

    p > The sample above is used for generating this homepage, for example.

    p id="contentfc"  >>
        The «content;» Function Call has a special meaning: it does not generate a tag, but instead
        the tags of a supplied body in a call will be inserted at each place where the «content;»
        function call is existing in the Default Body.
        >>

    h3 > Inheritance

    p   >>
        Declarations can ¬http://en.wikipedia.org/wiki/Inheritance_(computer_science) inherit¬
        information from previous declarations. For that case, there is the
        possibility to use an «is» clause to give a function name to inherit from.
        >>

    p > The following is an example from the YSLT specification:

    Code    ||
            decl stylesheet(version="1.0", xmlns:xsl="http://www.w3.org/1999/XSL/Transform");

            decl estylesheet is stylesheet (
                xmlns:exsl='http://exslt.org/common',
                xmlns:math='http://exslt.org/math',
                xmlns:func='http://exslt.org/functions',
                xmlns:str='http://exslt.org/strings',
                xmlns:dyn='http://exslt.org/dynamic',
                xmlns:set='http://exslt.org/sets',
                extension-element-prefixes='exsl func str dyn set math'
            );

            decl textstylesheet is estylesheet {
                output "text";
                const "space", !"'" + " " * 200 + "'"!;
                param "autoindent", 4;
                content;
            }, tstylesheet is textstylesheet;
            ||

    p   >>
        Here «estylesheet» inherits the tag name and the Default Values from «stylesheet»,
        while «textstylesheet» inherits all from «estylesheet» again. «estylesheet» then adds
        a Default Body, and «tstylesheet» does exactly the same as «textstylesheet».
        >>

    p > All of these YML functions output «stylesheet» XML tags, but with different defaults.

    h3 > Namespaces

    p   >>
        ¬http://www.w3.org/TR/xml-names/ XML namespaces¬ can be used just by providing an
        «alias» clause. Additionally, they can be used by an «in» clause; these two lines
        are equivalent:
        >>

    Code    ||
            decl apply(select) alias xsl:apply-templates;
            in xsl decl apply(select) alias apply-templates;
            ||

    p > «in» clauses also can be used with a block of declarations in braces:

    Code    ||
            in xsl {
                decl template(match);
                decl apply(select) alias apply-templates;

                decl function(name) alias template;
                decl call(name) alias call-template;
            }
            ||

    h3 id="pointer" > Pointers

    p   >>
        In some situations, it is good to have information in a Function Call, which then
        changes the way XML tags are generated. For this case, there are Pointers.
        >>

    p   >>
        The name should not mislead you; I took it because I chose the «*» symbol to declare them,
        and that is the meaning of this symbol in the programming language C. The concept behind
        is very easy.
        >>

    p   >>
        For example, it could be a good idea to generate a small HTML document containing some
        content. For this case, the title of the page is a good case for using pointers:
        >>

    Code    ||
            decl page(*title) alias html {
                head {
                    title *title;
                }
                body {
                    h1 *title;
                    content;
                }
            };
            ||

    p   >>
        In the example above, calling «page('My Page') { p 'hello, world'; }» will result in
        this XML output:
        >>

    Code    ||
            <html>
                <head>
                    <title>My Page</title>
                </head>
                <body>
                    <h1>My Page</h1>
                    <p>hello, world</p>
                </body>
            </html>
            ||

    p   >>
        Pointers can be referenced in any place in the Default Body of a «decl» statement, also for
        generating extra tags. Then the value for a Pointer will be the tag name.
        >>

    p   >>
        Additionally, you can insert the value of a pointer as text by calling it with two leading
        asterisks, i.e. if the pointer is defined as «*x», you can insert its value as text using: «**x».
        >>

    h3 id="macros", "Macros";

    p   >>
        Macros are a way to generate values for attributes with variable content. Macros can be set
        like any other parameters; they're used for a text search & replace in the values of attributes
        when attributes are generated.
        >>

    p   >>
        Parameters, which represent macros, are determined with a preceding «%» sign. They're
        accounted for before any other parameter is accounted for in a function call, even if
        they were defined after other parameters.
        >>

    p > An example:

    Code    ||
            decl foo(%macro, myAttr="something %macro for testing");

            testing
                foo "nice";
            ||

    p > This generates:

    Code    ||
            <testing>
              <foo myAttr="something nice for testing"/>
            </testing>
            ||

    h3 id="nullfunction" > The Null Function

    p   >>
        The function with the name «_» (underscore) is called Null Function. If you define this
        function, then you're switching off the default behaviour, that trivial declares are done
        automatically.
        >>

    p   >>
        Instead, unknown functions now call the Null Function. This can be very sensible together
        with ¬#descending Descending Attributes¬:
        >>

    Code    ||
            decl _ +type +name alias func;
            decl interface +name;

            interface Testcase {
                void f(in string input);
                long getOptions();
            }
            ||

    p > compiles to:

    Code    ||
            <interface name="Testcase">
              <func type="void" name="f">
                <parm>
                  <in/>
                  <string/>
                  <input/>
                </parm>
              </func>
              <func type="long" name="getOptions"/>
            </interface>
            ||

    h2 id="quoting" > Quoting Operators

    p > Five different quoting operators implement different functionality:

    h3 id="quote" > Quote >

    p > The «>» operator quotes into text nodes, doing XML escaping of text. An example:

    Code | > this text will be put into a text node and these angle brackets <> will be quoted

    p > Additionally, it can be used to implement an indention system, see ¬yslt YSLT¬ below.

    p   >>
        Then an integer literal can be the first part of the operator; it gives the indention
        level. For example:
        >>

    Code    ||
            0> this text is indented to the actual level and then output,
             >  followed by this text.\\n

            1> this text is indented one indention level\\n
            2> two levels\\n
            1> one level again\\n
            ||

    h3 id="blockquote" > Block Quote >>

    p {
        > To include more lines of text into a single quoted area, use double «>>». The lines 
        > are concatenated together then. An example:
    }

    Code    ||
            p   >>
                This generates a text paragraph for HTML. All this text, which you can find in
                these lines, is being concatenated together to one single text node, and then put
                into the body of the <p> ... </p> tag.
                >>
            ||

    h3 > Line Quote |

    p > The «|» operator does the same as the «>» operator, adding a newline character to the text node.

    p > Additionally, it can be used to implement an indention system, see ¬yslt YSLT¬ below.

    p > Then it's used together with additional «>» symbols showing the grade of indention:

    Code    ||
            | not indented
            |> single indent
            |>> double indent
            (...)
            ||

    h3 > Block Line Quote ||

    p   >>
        The «||» operator opens and closes a block of lines, which then are handled like if each of
        them would be preceeded with a Line Operator «|».
        >>

    p > Sample:

    Code {
        | ||
        ||
        this is code being quoted through
        this is the second line
        ||
        | ||
    }
     
    p > is equivalent to:

    Code {
        ||
        | this is code being quoted through
        | this is the second line
        ||
    }

    h3 > Inserting Commands

    p   >>
        Just like with a ¬http://en.wikipedia.org/wiki/Shell_(computing)#Unix_shells Unix shell¬,
        you can insert statements into text by using backticks:
        >>

    Code ] | Click `a href="http://fdik.org/yml/" "this link"`, please!

    p {
        >>
        Being in a Block Line Quote «||», you additionally can use the Line Command operator
        (two backquotes,
        >>
        ]  ``).
    }

    p > This is very interesting to have in YSLT, for example:

    Code {
        | ||
        | some code
        ] ``
        > apply "myTemplate";\n
        | some other code
        | ||
    }

    h3 id="userop" > User defined in-text Operators

    p > You can define short cuts for inserting commands into text by defining operators.

    p   >>
        Therefore, you need a ¬http://en.wikipedia.org/wiki/Regular_expression regular expression¬
        for matching text and YML text for replacing with. Here an example, how this is used by YSLT:
        >>

    Code ] define operator "«(.*?)»" as value "%1";

    p > The RegEx have ¬http://docs.python.org/library/re.html Python syntax¬.

    p   >>
        In this example all matches to the RegEx will be replaced by the YML text in the «as» clause.
        The text of the first group in the RegEx will replace the «%1» in the resulting YML text. You
        can do that for more than one group - just use «%2» for the second group, «%3» for the third
        one and so on.
        >>

    h3 id="quotethrough" > Quote Through ]

    p   >>
        The ¬http://en.wikipedia.org/wiki/Apple_II_series Apple ][¬ prompt operator just quotes
        through directly into XML what it gets.
        >>

    p   >>
        If the first character of a command is a «<», then quote through is applied
        automatically.
        >>
    
    p > This is the preferred way to output XML tags directly in YML:

    Code    ||
            <output me="directly" />
            
            ] <!--
            ]     add some comment, which then appears in XML
            ] -->
            ||

    h2 id="including" > Including YML files

    p   >>
        You can include a second YML script file into an existing YML script file
        at any place using:
        >>

    Code | include something.yml2

    a name="ymlpath";
    p   >>
        If you're not starting the filename with '.' or '/' as in the example above, then
        if the «YML_PATH» environment variable is set to a colon separated list of directories,
        these directories are being searched for the given filename. Otherwise, the local
        directory is searched.
        >>

    p   >>
        Filename ¬http://en.wikipedia.org/wiki/Glob_(programming) globbing¬ using «*» and «?»
        placeholders is supported to include more than one file at a time:
        >>

    Code | include part*.yml2

    p   >>
        Filename globbing also can be used reverted; that means, the files are included in reverse
        order:
        >>

    Code | include reverse part*.yml2

    p > If there are the files part1.yml, part2.yml and part3.yml, part3.yml is included first now.

    p > To include plain text as text nodes, you can use:

    Code | include text some.txt

    p > To include ready made XML, use:

    Code | include xml some.xml

    h2 id="python" > Escaping into Python - the Escape Operator !

    p > You can insert a Python command at any place by using the «!» operator:

    Code | !class X(str): pass

    h3 > Python script Operator !!

    p > You can use the double «!!» to include more than one line of Python code:

    Code    ||
            !!
            def fak(n):
                if n == 0:
                    return 1
                else:
                    return n * fak(n - 1)

            def getName(id):
                return SQL("select name from customers where id='"+str(id)+"';")[0]
            !!
            ||

    h3 > Python generated parameters in Function Calls

    p   >>
        You may use Python expressions to generate names and/or values in Function Calls.
        To do so, embed the Python expression in «! ... !»:
        >>

    Code    ||
            f x=!fak(5)!;
            customer name=!getName(42)!;
            tag !getNextAttributeName()!=42;
            ||

    h3 > Python generated Function Calls

    p   >>
        You can generate text with a Python expression, which represents an YML Function Call.
        The resulting YML function is then executed. Also here, embed the Python expression
        in «! ... !»:
        >>

    Code | !getTagName() + " " + getAttrib() + "='" + getValue() + "'"!

    h3 > Using Pointers as values in Python function calls

    p   >>
        Sometimes it is useful to call a generating Python function using information of a
        YML Function Call. For that case, there is the «python» statement in YML. You can
        call there a single Python function using YML Pointers as parameters.
        >>

    p > This is used in the YSLT specification, for example:

    Code    ||
            decl apply(select, *indent=1) alias apply-templates {
                python withIndent(*indent);
                content;
            };
            ||

    h2 id="comments" > Comments //, /* */

    p > Comments are written like in Java or C++:

    Code    ||
            // this is a comment
            something() { // this is a comment after a tag
            /* this is some comment, too */
            ||

    p > After Quoting Operators, comments are not possible. Instead, they're quoted through:

    Code    ||
            // the following line you'll find in the output document
            > this text is being output // and this too
            ||

    div id="bottom" {
        > ¬programming << Using YML 2¬ 
        > ¬#top ^Top^¬ 
        > ¬yslt >> show me YSLT¬ 
        > ¬features.en.yhtml2 (source)¬
    }
}