1

include homepage.en.yhtml2

     2

     3

page "The Features" {

     4

    h2 id=text > Text

     5

     6

    p   >>

     7

        To output text nodes (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax character data¬),

     8

        write literals. There are integer literals, floating point literals and text literals.

     9

        >>

    10

    11

    p   >>

    12

        Literals are written

    13

        ¬http://docs.python.org/reference/lexical_analysis.html#id7 like in Python¬,

    14

        that means, text literals are in single or double quotes, or multiline

    15

        in triple double quotes:

    16

        >>

    17

    18

    Code    ||

    19

            "text" 'also text' """some more text"""

    20

            42 "an integer and" 42.23 "a floating point literal"

    21

            ||

    22

    23

    p   >>

    24

        Literals are being output by the ¬#textfunction text function¬.

    25

        >>

    26

    27

    h2 id=functioncalls > Function Calls

    28

    29

    p   >>

    30

        The main idea of YML scripts is calling functions which then generate

    31

        XML tags (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax Markup¬).

    32

        Functions are generating single tags, lists or trees of tags.

    33

        >>

    34

    35

    p   >>

    36

        To call a function, write the name of the function, followed by a comma separated list

    37

        of function parameters (C like syntax) or just «attribute=value» pairs. Unlike C, you don't

    38

        need to insert the parameter list into parentheses. A simple function call can be terminated

    39

        by a semicolon «;» or by a period «.»

    40

        >>

    41

    42

    p   >>

    43

        It does not matter, if you're calling your function using parentheses or brackets or without.

    44

        So these statements are equal:

    45

        >>

    46

    47

    Code    ||

    48

            foo "hello, world";

    49

            foo "hello, world".

    50

            foo("hello, world");

    51

            foo["hello, world"];

    52

            ||

    53

    54

    h3 id=subtree > Subtrees

    55

    56

    p   >>

    57

        If you omit the tailing semicolon, you're creating a Subtree; YML Subtrees can also be

    58

        opened and closed with braces:

    59

        >>

    60

    61

    Code    ||

    62

            foo {

    63

                bar {

    64

                    something;

    65

                }

    66

            }

    67

            ||

    68

    69

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

    70

    71

    Code    ||

    72

            foo

    73

                bar;

    74

            ||

    75

    76

    h3 id=named > Named Parameters

    77

    78

    p   >>

    79

        To generate ¬http://www.w3.org/TR/2008/REC-xml-20081126/#attdecls attributes¬ by calling

    80

        a function, you can use Named Parameters.

    81

        >>

    82

    83

    p   >>

    84

        For that case, assign literals or symbols to attribute names like the following.

    85

        The name of the parameter then will be used as the name of the generated attribute.

    86

        An example:

    87

        >>

    88

    89

    Code    ||

    90

            div id=sample {

    91

                "this is a " a href="#sample" "link sample"

    92

            }

    93

            ||

    94

    95

    p > This generates:

    96

    97

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

    98

    99

    h3 > Unnamed Parameters

   100

   101

    p   >>

   102

        Unnamed Parameters prepare values for predefined attributes. The following example is

   103

        equivalent to the sample above:

   104

        >>

   105

   106

    Code    ||

   107

            decl a(href);

   108

            decl div(id);

   109

   110

            div "sample" {

   111

                "this is a " a "#sample" "link sample"

   112

            }

   113

            ||

   114

   115

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

   116

   117

    h3 > Calling with &

   118

   119

    p   >>

   120

        Especially if you have a ¬#defaultbody default body¬ for your function, calling with

   121

        a leading «&» can be sensible: then the tag itself is omitted and only the body is being output:

   122

        >>

   123

   124

    Code    ||

   125

            decl something { tag1; tag2; };

   126

   127

            list {

   128

                &something;

   129

            }

   130

            ||

   131

   132

    p > results in:

   133

   134

    Code    ||

   135

            <list>

   136

              <tag1/>

   137

              <tag2/>

   138

            </list>

   139

            ||

   140

   141

    p   >>

   142

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

   143

        >>

   144

   145

    h3 id=funclist > Function Lists

   146

   147

    p   >>

   148

        Function Lists are a feature of YML to simulate a more C like syntax. Let's have some

   149

        examples. You can have a list of functions whereever you can have a function. Function

   150

        Lists are comma separated:

   151

        >>

   152

   153

    Code    ||

   154

            x i, j, k

   155

            ||

   156

   157

    p > compiles to:

   158

   159

    Code    ||

   160

            <x>

   161

              <i/>

   162

              <j/>

   163

              <k/>

   164

            </x>

   165

            ||

   166

   167

    h3 id=paramlists > Parameter Lists

   168

   169

    p   >>

   170

        A sample together with ¬#descending Descending Attributes¬:

   171

        >>

   172

   173

    Code    ||

   174

            decl Interface @name;

   175

            decl attr @type @name;

   176

            decl func @type @name;

   177

   178

            Interface Icecream {

   179

                attr color flavour;

   180

                attr long number;

   181

                func int getPrice();

   182

                func void addFlavour(in color flavour, in long number);

   183

            }

   184

            ||

   185

   186

    p > compiles to:

   187

   188

    Code    ||

   189

            <Interface name="Icecream">

   190

              <attr type="color" name="flavour"/>

   191

              <attr type="long" name="number"/>

   192

              <func type="int" name="getPrice"/>

   193

              <func type="void" name="addFlavour">

   194

                <parm>

   195

                  <in/>

   196

                  <color/>

   197

                  <flavour/>

   198

                </parm>

   199

                <parm>

   200

                  <in/>

   201

                  <long/>

   202

                  <number/>

   203

                </parm>

   204

              </func>

   205

            </Interface>

   206

            ||

   207

   208

    p   >>

   209

        Note the «parm» tags – they're generated by default, if you write a Parameter List

   210

        behind a Function Call. That differs from calling the function with parameters –

   211

        ¬#functioncalls calling¬ means using ¬#text text¬ values.

   212

        >>

   213

   214

    p   >>

   215

        The «parm» tags are emitted, because the «_parm» function is called each time

   216

        such a parameter will be emitted.

   217

        >>

   218

   219

    p   >>

   220

        If you want to have the «_parm» function doing other things, just ¬#decl declare¬

   221

        it in another way.

   222

        >>

   223

   224

    h3 id=generics > Generic Declarations

   225

   226

    p   >>

   227

        Using Generic Declarations is just like using ¬#paramlists Parameter Lists¬ – use angle brackets

   228

        instead of parentheses. For Generic Declarations, the «_generic» function is called each

   229

        time such a Generic Declaration will be emitted, generating «generic» tags as the default:

   230

        >>

   231

   232

    Code | max<int>(x, y)

   233

   234

    p > compiles to:

   235

   236

    Code    ||

   237

            <max>

   238

              <generic>

   239

                <int/>

   240

              </generic>

   241

              <parm>

   242

                <x/>

   243

              </parm>

   244

              <parm>

   245

                <y/>

   246

              </parm>

   247

            </max>

   248

            ||

   249

   250

    h3 id=contentfc > The «content» function

   251

   252

    p   >>

   253

        The «content;» Function Call has a special meaning (only in a ¬#defaultbody default body¬):

   254

        it does not generate a tag, but instead

   255

        the tags of a supplied body in a call will be inserted at each place where the «content;»

   256

        function call is existing in the ¬#defaultbody default body¬.

   257

        >>

   258

   259

    h3 id=textfunction > The «text» function

   260

   261

    p   >>

   262

        There is a special YML function named «text». Usually, it's just ¬#alias aliased¬ to «-» (and 

   263

        therefore outputting nothing). The «text» function is called each time a text literal will be

   264

        output.

   265

        >>

   266

   267

    p   >>

   268

        If you ¬#decl declare¬ the «text» function, you can overload that behaviour. For example,

   269

        ¬yslt YSLT¬ is declaring «text» like this:

   270

        >>

   271

   272

    Code    ||

   273

            decl text alias xsl:text;

   274

   275

            "test"

   276

            ||

   277

   278

    p > generates:

   279

   280

    Code | <xsl:text>test</xsl:text>

   281

   282

    p   >>

   283

        The «text» function is not called, if you give text as a value for an attribute:

   284

        >>

   285

   286

    Code    ||

   287

            decl text alias xsl:text;

   288

   289

            a "test"

   290

            ||

   291

   292

    p > generates:

   293

   294

    Code | <a>test</a>

   295

   296

    p   >>

   297

        But it is called using the quoting operators:

   298

        >>

   299

   300

    Code    ||

   301

            decl text alias xsl:text;

   302

   303

            a > test

   304

            ||

   305

   306

    p > generates:

   307

   308

    Code | <a><xsl:text>test</xsl:text></a>

   309

   310

    h3 id=declfunction > The «decl», «define» and «operator» functions

   311

   312

    p   >>

   313

        The «decl», «define» and «operator» functions are not defined, so they cannot be used

   314

        accidentally by having a syntax error i.e. in a «decl» statement. If you want to use such

   315

        a function, i.e. «decl()», you have to ¬#decl declare it explicitely¬:

   316

        >>

   317

   318

    Code    ||

   319

            decl decl;

   320

            decl();

   321

            ||

   322

   323

    p > will result in:

   324

   325

    Code | <decl/>

   326

   327

    h2 id=decl > Declaring Functions: decl

   328

   329

    p   >>

   330

        As default, each Function Call generates one XML tag, which has the same name. To be exact,

   331

        the XML tag has dashes in it's name where the YML function has underscores.

   332

        >>

   333

   334

    p   >>

   335

        To define, how tags and attributes look like, which are created by a Function Call, you

   336

        can use the «decl» statement.

   337

        >>

   338

   339

    h3 > Trivial Declarations

   340

   341

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

   342

   343

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

   344

   345

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

   346

   347

    p   >>

   348

        Because trivial declarations are done automatically, if you're using a function for the

   349

        first time, you usually don't need to declare this way.

   350

        >>

   351

   352

    h3 > Specifying Unnamed Parameters

   353

   354

    p   >>

   355

        To specifiy Unnamed Parameters, give the parameter list comma separated in parentheses

   356

        or provide one or more brackets with parameter lists in them:

   357

        >>

   358

   359

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

   360

   361

    p   >>

   362

        If you're using the corresponding functions a() and img() together with an unnamed parameter

   363

        in a call, then these attributes are used for applying the values, respectively:

   364

        >>

   365

   366

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

   367

   368

    p > These Function Calls generate:

   369

   370

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

   371

   372

    h3 id=defaultattr > Giving Default Values for parameters

   373

   374

    p   >>

   375

        To give default values for generating XML attributes, assign a literal to each named parameter

   376

        in the declaration parentheses or brackets. Two examples, which do the same:

   377

        >>

   378

   379

    Code

   380

        ||

   381

        decl img(src, alt="picture");

   382

        decl img[src][alt="picture"];

   383

        ||

   384

   385

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

   386

   387

    p   >>

   388

        Sometimes tags are used in different ways to do different things. For this case, you can

   389

        use aliasing. Aliasing means, the YML function name and the XML tag name differ. For example:

   390

        >>

   391

   392

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

   393

   394

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

   395

   396

    p   >>

   397

        The alias name «-» has a special meaning: it omits the tag in the output. That is especially

   398

        sensible if you have a ¬#defaultbody default body¬. Then an alias to «-» has the same meaning

   399

        as starting the function call with the «&» character: only the body is emitted.

   400

        >>

   401

   402

    h3 id=descending > Specifying Descending Attributes

   403

   404

    p   >>

   405

        Maybe you want to write something like this:

   406

        >>

   407

   408

    Code    ||

   409

            Module ERP {

   410

                Interface Customer {

   411

                    // ...

   412

                }

   413

            }

   414

            ||

   415

   416

    p > Without any extras, this compiles to:

   417

   418

    Code    ||

   419

            <Module>

   420

                <ERP>

   421

                    <Interface>

   422

                        <Customer />

   423

                    </Interface>

   424

                </ERP>

   425

            </Module>

   426

            ||

   427

   428

    p   >>

   429

        For this case, it would be practical, if «ERP» would not be interpreted as extra tag

   430

        but as value for an attribute «name». This you can achive with Descending Attributes:

   431

        >>

   432

   433

    Code | decl Module @name, Interface @name;

   434

   435

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

   436

   437

    Code    ||

   438

            <Module name="ERP">

   439

                <Interface name="Customer" />

   440

            </Module>

   441

            ||

   442

   443

    p   >>

   444

        Descending attributes can also be used this way:

   445

        >>

   446

   447

    Code    ||

   448

            decl module +name;

   449

            decl element +name;

   450

   451

            module Some {

   452

                element {

   453

                    one;

   454

                    two;

   455

                    three;

   456

                }

   457

                element {

   458

                    four; five; six

   459

                }

   460

            }

   461

            ||

   462

   463

    p   >>

   464

        The above generates:

   465

        >>

   466

   467

    Code    ||

   468

            <?xml version='1.0' encoding='UTF-8'?>

   469

            <module name="Some">

   470

              <element name="one"/>

   471

              <element name="two"/>

   472

              <element name="three"/>

   473

              <element name="four"/>

   474

              <element name="five"/>

   475

              <element name="six"/>

   476

            </module>

   477

            ||

   478

   479

    h3 id=descending_pointer > Specifying Descending Pointers

   480

   481

    p   >>

   482

        Like with descending attributes, you can use descending ¬#pointer pointers¬. Instead of preceding the

   483

        name of an attribute with a «+» sign (like with ¬#descending descending attributes¬), precede it with an asterisk «*».

   484

        >>

   485

   486

    p   >>

   487

        Like with ¬#pointer pointers¬ in general, it's a good idea to combine that with a ¬#defaultbody default body¬:

   488

        >>

   489

   490

    Code    ||

   491

            decl f *p { some tags with *p };

   492

   493

            f value;

   494

            ||

   495

   496

    p   >>

   497

        This generates:

   498

        >>

   499

   500

    Code    ||

   501

            <?xml version='1.0' encoding='UTF-8'?>

   502

            <f>

   503

              <some>

   504

                <tags>

   505

                  <with>value</with>

   506

                </tags>

   507

              </some>

   508

            </f>

   509

            ||

   510

   511

    h3 id=defaultbody > Supplying a Default Body

   512

   513

    p   >>

   514

        Additionally, you can supply a Default Body for each tag. For that case, add a YML function

   515

        block in braces to your declaration:

   516

        >>

   517

   518

    Code    ||

   519

            decl pageContent alias body {

   520

                a name=top;

   521

                include heading.en.yhtml2;

   522

                div id=entries

   523

                content;

   524

            };

   525

            ||

   526

   527

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

   528

   529