[sc34wg3] CTM templates - A proposal

[Lars Heuer]

Hi all,

Steve Pepper has suggested that I should send my CTM template proposal
to this list.
The following proposal was derived from an e-mail to the other CTM
editors, but I tried to make it readable for 3rd parties. :) Feel free
to ask questions / comments etc.

Best regards,
Lars


CTM Template proposal
=====================

Introduction
------------
The idea behind the template syntax: We use *one* template syntax for
all kind of 'templatable' constructs. The syntax seems to be a bit
verbose but it has the advantage that it is very powerful.

The basics are simple text-replacements: When a template is applied;
the content of the template is inserted into the position where the
template is called.
The template content looks exactly like CTM content, in fact it is CTM
content (variables are an exception they may not appear in 'normal'
CTM content.

(Sidenote: Thanks to Robert Barta who has heavily inspired the syntax)

I took the examples from the CTM draft v0.3

Name templates
--------------
See 5.2.7.1 (page 5)

Actually this is *not* something I'd like to call "template" because
it is not used to generate content.
    
    foaf:name isa ctm:name


'country-code' is a name type and all instances of country-code 
are scoped by 'iso639'

    country-code isa ctm:name-tpl
    return """
        country-code $value @iso639;
    """

The 'ctm:name-tpl' is a short cut for:

    country-code isa ctm:name; isa ctm:tpl;
    return """
        country-code $value @iso639;
    """



Occurrence templates
--------------------
See 5.2.7.2 (page 6)

    bio:birthYear isa ctm:tpl
    return """
        bio:birthYear $value ^^xsd:gYear;
    """


    geolang isa ctm:tpl
    return """
        geolang $value @deprecated;
    """


Association templates
---------------------
See 5.2.7.3 (page 6)

    bio:born-in isa ctm:tpl
    return """
        born-in(person $; place $place) @bio
    """


    # Specialization of the previous template (becomes unary)
    
    born-in-paris isa ctm:tpl
    return """
        born-in(person $; place paris) @bio
    """


    killed-by isa ctm:tpl
    return """
        killed-by(http://psi.example.org/victim $
                  perpetrator $perpetrator
                  cause $cause
                  )
    """


Advanced templates
------------------

    works-for isa ctm:tpl
    return """
        $ isa http://psi.example.org/person
        
        works-for(employee  $;
                  org       $org;
                  position  $position
                  )
    """
    
Applying the template:

    fred works-for BigCo dinosaur-operator

The previous statement generates the following Topic Maps constructs:

    fred isa http://psi.example.org/person
    works-for(employee  fred;
              org       BigCo;
              position  dinosaur-operator
             )

Explanation
-----------
The variable '$' is automatically bound to the topic in the focus
(other notations are possible like the more verbose $_right or
ctm:focus or ....). The other variables are bound in their arrangement
(the first variable is bound to the first argument, the second to the
second argument etc.)


Further ideas
-------------
Often the template identifier is equal to the association / occurrence
/ name type. To repeat the same identifier can be an annoying task. It
might be nice to provide a shortcut for it (back reference).

Examples:

# Shortcut $_

    killed-by isa ctm:tpl
    return """
        $_(http://psi.example.org/victim $
                  perpetrator $perpetrator
                  cause $cause
                  )
    """


In all previous examples the role player variable is equal to the role
type but this is no must. Other possibilities: $1, $2


The examples use the verbose """ but one liners with " are possible


Assignment by variable name
---------------------------
While statements like

    fred works-for BigCo dinosaur-operator

are pretty short they may not be very readable without looking at the
template content. And if the template is more complex than just 3
variables the author and reader may be lost.
Solution: Assign variables by name.

Here again, the template:

    works-for isa ctm:tpl
    return """
        $ isa http://psi.example.org/person
        
        works-for(employee  $;
                  org       $org;
                  position  $position
                  )
    """

And here we're using the previous template in a more verbose manner:

    fred works-for $org=BigCo $position=dinosaur-operator

alternative syntax:

    fred works-for $org BigCo $position dinosaur-operator



Alternative syntaxes
--------------------
Some find the "a template is a topic" notation too verbose, so I
provide some alternative syntax proposals:

a) "return" is omitted and the template content is written inside
   brackets:

    killed-by isa ctm:tpl [
        killed-by(http://psi.example.org/victim
                  perpetrator $perpetrator
                  cause $cause
                  )
    ]
    
    
    # Same as above but it uses "$_" for the type
    killed-by isa ctm:tpl [
        $_(http://psi.example.org/victim
                  perpetrator $perpetrator
                  cause $cause
                  )
    ]

b) "return" is omitted *and* isa ctm:tpl is also omitted
    killed-by = [
        $_(http://psi.example.org/victim
                  perpetrator $perpetrator
                  cause $cause
                  )
    ]

c) Same thing as (b) but with curly braces
    killed-by = {
        $_(http://psi.example.org/victim
                  perpetrator $perpetrator
                  cause $cause
                  )
    }

-- 
http://www.semagia.com