25. Genereren van tekst met Brocade

25.1. Inleiding

Brocade moet op verschillende terreinen tekst genereren vanuit de toepassing.

Het meest voor de hand liggende voorbeeld is ongetwijfeld het genereren van HTML pagina’s.

Deze tekst stelt een template systeem voor die deze opdracht moet vereenvoudigen.

25.2. Een template systeem en een template

Een template is een karakterrij die op voorhand wordt opgesteld. Behalve tekst bevat de template ook instructies die aangeven hoe de karakterrij moet worden gebruikt.

Het gebruik van de template gebeurt meestal later en zelfs op diverse tijdstippen. Om het reele gebruik van de template zo efficient mogelijk te maken, wordt deze eerst geanalyseerd en in een gecompileerde vorm opgeslagen.

25.2.1. Placeholders en namespaces

De belangrijkste faciliteit van een template systeem is het concept van placeholders. Dit zijn goed identificeerbare karakterrijen in de bron (de template) die dan later, in de toepassing, vervangen worden door de echte waarden.

De mapping van placeholder naar effectieve waarde moet rigoureus gebeuren: de context waar de placeholders moeten worden gezocht moet ondubbelzinnig vast liggen. Daartoe wordt het concept van namespaces gebruikt: het zijn abstracties van de context.

25.2.2. Template instructies

Deze geven aan hoe de template moet worden gebruikt:

  • identificatie van de place holders
  • looping constructies
  • branching constructies

25.3. Brocade template systeem

Laten we dit afkorten tot BTS.

BTS heeft de volgende karakteristieken:

  • BTS laat pre-compilatie toe: een efficiente voorstelling van een template kan worden opgeslagen. Bij de toepassing van de template bevat deze pre-gecompileerde vorm samen met de placeholders alles wat nodig is om de uiteindelijk string te genereren.

  • De toepassing van de template gebeurt in de M omgeving

  • Voor het invullen van de placeholders staan er 2 namespaces ter beschikking. De eerste namespace heet de screen namespace en wordt gekarakteriseerd door de M variabele UDbts = “screen”. De tweede namespace heet de format namespace en wordt gekarakteriseerd door de M variabele UDbts = “format”. In de screen namespace staan alle M variabelen waarvan de eerste letter ‘U’, ‘R’ of ‘F’ is, ter beschikking. In de format namespace wordt deze verzameling uitgebreid met alle placeholders waarvan de naam begint met een kleine letter ([a-z]) en die kunnen worden gevonden in de subscripts van de M array UAph.

  • Er zijn 6 speciale karakters: \\, @, {, }, |, $ die worden gebruikt om de templates aan te sturen

    \\: escape karakter. Indien een speciaal karakter wordt voorafgegaan door \\, dan verliest het karakter zijn speciaal statuut: het wordt behandeld ale een gewoon karakter.

    @: leidt een template activiteit in.

    {, } en | worden gebruikt in het behandelen van blokken tekst.

    $: leidt een placeholder in.

25.4. Placeholders in BTS

Bij de aanvang van de template is de namespace steeds screen. Met andere woorden UDbts="screen".

De BTS instructie @formats verandert de namespace naar format. Bij het beëindigen van deze instructie verandert de namespace terug naar screen.

Met de volgende basisregels kan men steeds het begin en einde van een placeholder afleiden:

  • Een placeholder wordt steeds ingeleid door een $
  • Er kan nooit een } in een placeholder staan.
  • Een placeholder voldoet aan de M notatie voor een variabele (eventueel met subscripts).
  • De scope van een placeholder is steeds statisch: What you see is what you get! Macro’s worden pas opgelost nadat de vorm van de placeholder is bepaald.

Voorbeelden van placeholders:

  • $UDses placeholder voor UDses
  • $FDdata(“pk”) placeholder voor FDdata(“pk”)
  • $FDdata(UDses,”pk”,1) placeholder voor FDdata(UDses,”pk”,1)
  • $FDdata(UDses,”My “”quote”“”) placeholder voor FDdata(UDses,”My “”quote”“”)
  • {$FDdata}(“pk”) placeholder voor FDdata
  • <a href=”$url”>link</a> placeholder voor url in format mode

25.5. Tekstblokken in BTS

Een tekstblok is een stuk van een template dat wordt ingeleid door een { en eindigt met een corresponderende }.

Een tekstblok heeft de volgende eigenschappen:

  • Tekstblokken kunnen worden genest.

  • Tekstblokken kunnen zich uitstrekken over verschillende lijnen

  • Tekstblokken kunnen worden voorzien van argumenten. Argumenten staan steeds op het einde van een tekstblok en beginnen met de eerste |. Het stuk voor de eerste | heet het tekstveld. Een argument begint steeds met | gevolgd door eventuele whitespace, een keyword, eventuele whitespace, een = teken, eventuele whitespace en een argument dat wordt geinterpreteerd in functie van het keyword.

    De toegelaten keywords zijn:

    • wspace: waarde is een M voorwaarde. Indien true, dan wordt de eventuele whitespace voor de eerste | behouden
    • enc: mogelijke waarden: js, url, py, xml, utf8, hex, HEX (zie macro m4_encode())
    • def: indien het tekstveld leeg is, dan wordt het tekstveld vervangen door deze waarde.
    • mod: date | num (verwerk het tekstveld volgende deze modificatie)
    • arg: eventuele extra argumenten voor mod (moet volgen op mod)
    • when: indien de volgende M voorwaarde false is, wordt het tekstveld niet getoond
    • unless: indien de volgende M voorwaarde true is, wordt het tekstveld niet getoond