vb@0: include homepage.en.yhtml2
vb@0: 
vb@0: page "YSLT – XSLT C style" {
vb@0:     h1 id=intro > YSLT – an introduction
vb@0: 
vb@0:     p   >>
vb@0:         Especially the ¬http://www.w3.org/TR/xslt XSLT¬ programmer can benefit from YML.
vb@0:         Usually many attributes of XSLT are annoying in programming praxis:
vb@0:         >>
vb@0: 
vb@0:     ul {
vb@0:         li  >>
vb@0:             the missing separation of ¬http://en.wikipedia.org/wiki/Indent_style indention¬
vb@0:             of the XSLT program and indention of the output text
vb@0:             >>
vb@0: 
vb@0:         li > the complicated syntax
vb@0: 
vb@0:         li > the lack of good text escaping mechanisms (< and > are not seldom)
vb@0: 
vb@0:         li > ...
vb@0:     }
vb@0: 
vb@0:     p > In short, it's ugly ;-)
vb@0: 
vb@0:     p   >>
vb@0:         Usually the result is, that many programmers are avoiding XSLT as a programming language.
vb@0:         It's a pity, because for processing XML data, it can do much more than “formatting” as
vb@0:         “stylesheets”.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         The idea of YSLT now is to supply a simple language, which programmers want to use, to
vb@0:         make the features of XSLT accessible to a broader base of people.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         YSLT can be used much simpler; it's just a ¬http://fdik.org/yml/index#ylanguages Y Language¬
vb@0:         for XSLT. I'm using it for my blog, here you can ¬http://fdik.org/yblog2.tar.bz2 download YBlog2¬,
vb@0:         a simple blogging software in YSLT.
vb@0:         >>
vb@0: 
vb@0:     p > Here you can find the ¬yslt.yml2 YSLT specification¬.
vb@0: 
vb@0:     h2 id=hello > Hello, World
vb@0: 
vb@0:     p > In YSLT, the hello world program reads like this:
vb@0: 
vb@0:     Code    ||
vb@0:             include yslt.yml2
vb@0:             textstylesheet template "/" | hello, world
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         The `a href="http://fdik.org/yml/features#including" code > include` line includes the
vb@0:         YSLT Y Language declarations. The second line generates an XSLT hello world program.
vb@0:         You can generate it using:
vb@0:         >>
vb@0: 
vb@0:     Code | % yml2c -o hello.xsl hello.ysl2
vb@0: 
vb@0:     p > This results in the following program:
vb@0: 
vb@0:     Code    ||
vb@0:             <xsl:stylesheet xmlns:func="http://exslt.org/functions"
vb@0:             xmlns:dyn="http://exslt.org/dynamic" xmlns:str="http://exslt.org/strings"
vb@0:             xmlns:math="http://exslt.org/math"
vb@0:             xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
vb@0:             extension-element-prefixes="exsl func str dyn set math"
vb@0:             xmlns:set="http://exslt.org/sets" version="1.0"
vb@0:             xmlns:exsl="http://exslt.org/common"><xsl:output method="text"/>
vb@0:             <xsl:variable name="space" select="'                                 '"/>
vb@0:             <xsl:param name="autoindent" select="4"/><xsl:template match="/">
vb@0:             <xsl:param name="_indent" select="0"/><xsl:value-of
vb@0:             select="substring($space, 1, $_indent+0*$autoindent)"/>hello, world
vb@0:             </xsl:template></xsl:stylesheet>
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         You can execute this program with any
vb@0:         ¬http://en.wikipedia.org/wiki/XML_template_engine XSL processor¬, for example the Free Software
vb@0:         ¬http://xmlsoft.org/XSLT/xsltproc2.html xsltproc¬.
vb@0:         >>
vb@0:     
vb@0:     Code    ||
vb@0:             % yml2c -o hello.xsl hello.ysl2
vb@0:             % echo '<empty/>' > empty.xml          
vb@0:             % xsltproc hello.xsl empty.xml 
vb@0:             hello, world
vb@0:             % _
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Or you can just use ¬toolchain#processor yml2proc¬:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             % yml2proc -My hello.ysl2
vb@0:             hello, world
vb@0:             % _
vb@0:             ||
vb@0: 
vb@0:     h2 id=programming > Programming in YSLT
vb@0: 
vb@0:     p   >>
vb@0:         Because YSLT is just a ¬index#ylanguages Y Language¬ for XSLT, you can do anything with YSLT
vb@0:         you can do with XSLT in just nicer syntax ;-) To read what XSLT is all about, I recommend 
vb@0:         ¬http://www.w3.org/TR/xslt the official W3C documentation for XSLT¬.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         So this document is just an beginners guide, if you want to understand XSLT completely,
vb@0:         better read the ¬http://www.w3.org W3C¬ stuff.
vb@0:         >>
vb@0: 
vb@0:     h3 > Programming YSLT means programming with a pure functional language.
vb@0: 
vb@0:     p   >>
vb@0:         Lovers of ¬http://en.wikipedia.org/wiki/Lisp_(programming_language) Lisp¬ or
vb@0:         ¬http://www.haskell.org/ Haskell¬ will not see any problems. But many programmers are used to
vb@0:         have a programming language with a
vb@0:         ¬http://en.wikipedia.org/wiki/Procedural_programming procedural imperative paradigma¬ like
vb@0:         ¬http://java.sun.com Java¬,
vb@0:         ¬http://en.wikipedia.org/wiki/C_(programming_language) C¬/¬http://en.wikipedia.org/wiki/C++ C++¬
vb@0:         or ¬http://www.python.org Python¬. Why should they use a
vb@0:         ¬http://en.wikipedia.org/wiki/Functional_programming functional¬ language?
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         Actually, if a functional language is practical or not, depends of what's to do – “the
vb@0:         right tool for the task”, one could say.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         Because processing XML data means traversing a (document) tree,
vb@0:         ¬http://en.wikipedia.org/wiki/Recursion recursive¬ algorithms are a clear advantage.
vb@0:         And this is the reason, why choosing a functional language is a good choice for that job.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         It's a little bit like with ¬http://en.wikipedia.org/wiki/SQL SQL¬ – for it's job, it's
vb@0:         excellent, but no-one wants to write a complete application in SQL (and also not in one
vb@0:         of the Turing-complete SQL extension languages like
vb@0:         ¬http://www.oracle.com/technology/tech/pl_sql/index.html PL/SQL¬).
vb@0:         >>
vb@0: 
vb@0:     h3 id=htmlgen > Generating HTML out of a DSL
vb@0: 
vb@0:     p   >>
vb@0:         Of course, you can use YSLT as you would use XSLT. Let's say, you have data in XML
vb@0:         documents, and you want to have an excerpt out of this data. This is a common task,
vb@0:         comparable to «SELECT» data out of an SQL database. But we have no database, we have
vb@0:         something like this file customers.yml2:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             decl customer(*id, *name) { id *id, name *name };
vb@0: 
vb@0:             list {
vb@0:                 customer 23, "Kurt Meier";
vb@0:                 customer 42, "Lieschen Schmidt";
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Let's say, we want to output this into an ¬http://en.wikipedia.org/wiki/XHTML XHTML¬ document,
vb@0:         where the list is showed as a table. Then we would do the following:
vb@0:         >>
vb@0: 
vb@0:     p > The XHTML document should be like the following and include the list in the body:
vb@0: 
vb@0:     Code    ||
vb@0:             include yslt.yml2
vb@0: 
vb@0:             stylesheet {
vb@0:                 template "/" html {
vb@0:                     head title "Customer List";
vb@0:                     body apply "list";
vb@0:                 }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         In the example above, stylesheet declares the main program. Then we define a template, which
vb@0:         is executed automatically starting reading the root «'/'» of the document tree of the XML
vb@0:         document we're processing.
vb@0:         >>
vb@0: 
vb@0:     p > Using the XML document as input, we're creating this HTML tree:
vb@0: 
vb@0:     Code    ||
vb@0:             <html>
vb@0:                 <head>
vb@0:                     <title>Customer List</title>
vb@0:                 </head>
vb@0:                 <body>
vb@0: 
vb@0:                 <!-- ... ->
vb@0: 
vb@0:                 </body>
vb@0:             </html>
vb@0:             ||
vb@0: 
vb@0:     p > How do we create the list? Well, let's use a table with customers:
vb@0: 
vb@0:     Code |     template "list" table apply "customer";
vb@0: 
vb@0:     p   >>
vb@0:         What to do per customer? Well, generate a table row with two columns, one for «id» and one
vb@0:         for «name»:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:                 template "customer" tr {
vb@0:                     td value "id";
vb@0:                     td value "name";
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p > That was it. We now can run our small program:
vb@0: 
vb@0:     Code | % yml2proc -y customer.ysl2 -x customer.xml -o customer.html -P
vb@0: 
vb@0:     p > The result looks like this:
vb@0: 
vb@0:     Code    ||
vb@0:             % cat customer.html 
vb@0:             <?xml version="1.0"?>
vb@0:             <html>
vb@0:               <head>
vb@0:                 <title>Customer List</title>
vb@0:               </head>
vb@0:               <body>
vb@0:                 <table>
vb@0:                   <tr>
vb@0:                     <td>23</td>
vb@0:                     <td>Kurt Meier</td>
vb@0:                   </tr>
vb@0:                   <tr>
vb@0:                     <td>42</td>
vb@0:                     <td>Lieschen Schmidt</td>
vb@0:                   </tr>
vb@0:                 </table>
vb@0:               </body>
vb@0:             </html>
vb@0:             % _
vb@0:             ||
vb@0: 
vb@0:     p > Here you can download ¬samples/customer.ysl2 the complete program¬.
vb@0: 
vb@0:     h3 id=codegen > How to generate code with YSLT
vb@0: 
vb@0:     p > Generating code is easy with YSLT, if you follow these steps:
vb@0: 
vb@0:     ol {
vb@0:         li > design the software you want to generate using patterns and write that in a DSL
vb@0:         li > write target code once for each pattern
vb@0:         li > deconstruct a compiler for the target code for each pattern
vb@0:         li > fine tune until the diff is empty
vb@0:     }
vb@0: 
vb@0:     p   >>
vb@0:         Let's test by example. First let's say, we have a pattern of entities we want
vb@0:         to implement as Java beans. The enities in our DSL are:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             decl entity +name;
vb@0:             decl attr +type +name;
vb@0:             decl aggregates +entity;
vb@0: 
vb@0:             structure {
vb@0:                 entity Customer {
vb@0:                     attr String name;
vb@0:                     attr int creditLimit;
vb@0:                     aggregates Order;
vb@0:                 }
vb@0: 
vb@0:                 entity Order {
vb@0:                     attr String no;
vb@0:                     attr String description;
vb@0:                     attr int amount;
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         How to write that in a Java Program? Well, following the second step, we're
vb@0:         writing our target code manually; for this simple sample, let's be naive and
vb@0:         save the following into a file named Customer.java.target:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             import java.util.Vector;
vb@0:             import java.util.Collections;
vb@0:             import base.Entity;
vb@0: 
vb@0:             class Customer extends Entity {
vb@0:                 Customer {
vb@0:                     id = genId();
vb@0:                 }
vb@0: 
vb@0:                 // attribute name
vb@0:                 
vb@0:                 private String name;
vb@0:                 public String getName() {
vb@0:                     return name;   
vb@0:                 }
vb@0:                 public void setName(String value) {
vb@0:                     name = value;
vb@0:                 }
vb@0:  
vb@0:                 // attribute creditLimit
vb@0: 
vb@0:                 private int creditLimit;
vb@0:                 public int getCreditLimit() {
vb@0:                     return creditLimit;   
vb@0:                 }
vb@0:                 public void setCreditLimit(int value) {
vb@0:                     creditLimit = value;
vb@0:                 }
vb@0: 
vb@0:                 // Order aggregation
vb@0: 
vb@0:                 protected Vector orderList = new Vector();
vb@0:                 void addOrder(Order entity) {
vb@0:                     orderList.add(entity);
vb@0:                 }
vb@0:                 void removeOrder(Order entity) {
vb@0:                     orderList.remove(entity);
vb@0:                 }
vb@0:                 Iterator orderIterator() {
vb@0:                     return orderList.iterator();
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         The third step does most of the work. First we cite this code
vb@0:         into gen_entity.ysl2 and create the basic form of an YSLT script:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             include yslt.yml2
vb@0: 
vb@0:             tstylesheet {
vb@0:                 template "/" {
vb@0:                     | import java.util.Vector;
vb@0:                     | import java.util.Collections;
vb@0:                     | import base.Entity;
vb@0:                     | 
vb@0:                     | class Customer extends Entity {
vb@0:                     |     Customer {
vb@0:                     |         id = genId();
vb@0:                     |     }
vb@0:                     | 
vb@0:                     |     // attribute name
vb@0:                     |     
vb@0:                     |     private String name;
vb@0:                     |     public String getName() {
vb@0:                     |         return name;   
vb@0:                     |     }
vb@0:                     |     public void setName(String value) {
vb@0:                     |         name = value;
vb@0:                     |     }
vb@0:                     | 
vb@0:                     |     // attribute creditLimit
vb@0:                     | 
vb@0:                     |     private int creditLimit;
vb@0:                     |     public int getCreditLimit() {
vb@0:                     |         return creditLimit;   
vb@0:                     |     }
vb@0:                     |     public void setCreditLimit(int value) {
vb@0:                     |         creditLimit = value;
vb@0:                     |     }
vb@0:                     | 
vb@0:                     |     // Order aggregation
vb@0:                     | 
vb@0:                     |     protected Vector orderList = new Vector();
vb@0:                     |     void addOrder(Order entity) {
vb@0:                     |         orderList.add(entity);
vb@0:                     |     }
vb@0:                     |     void removeOrder(Order entity) {
vb@0:                     |         orderList.remove(entity);
vb@0:                     |     }
vb@0:                     |     Iterator orderIterator() {
vb@0:                     |         return orderList.iterator();
vb@0:                     |     }
vb@0:                     | }
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Now for the deconstruction. I think, it'll be best, if we
vb@0:         ¬#edocument create a .java file for each entity¬.
vb@0:         So we're moving the whole thing into a template for each entity
vb@0:         creating a file, and we're applying this for each entity using the name of each
vb@0:         Entity as parameter. We're adding some distinction of cases, too.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         When we apply, the indention system of YSLT will add an indention level, so we can
vb@0:         take out rendundant whitespace; for the first apply we don't want this, so we're
vb@0:         giving the number 0 as the indention level.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         In attributes, braces «{…}» let us insert the value of an XPath expression into our
vb@0:         DSL, while inside quoted text the same is done by the ¬#angledouble angle double quotes¬
vb@0:         `] <code>&#xab…&#xbb</code>`:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             include yslt.yml2
vb@0: 
vb@0:             tstylesheet {
vb@0:                 template "/structure" apply "Entity", 0;
vb@0: 
vb@0:                 template "Entity" document "{@name}.java" {
vb@0:                     if "aggregates" {
vb@0:                         | import java.util.Vector;
vb@0:                         | import java.util.Collections;
vb@0:                     }
vb@0: 
vb@0:                     | import base.Entity;
vb@0:                     | 
vb@0:                     | class `] &#xab`@name`] &#xbb` extends Entity {
vb@0:                     |     `] &#xab`@name`] &#xbb` {
vb@0:                     |         id = genId();
vb@0:                     |     }
vb@0:                     | 
vb@0:             [...]
vb@0:                     |         orderList.remove(entity);
vb@0:                     |     }
vb@0:                     |     Iterator orderIterator() {
vb@0:                     |         return orderList.iterator();
vb@0:                     |     }
vb@0:                     | }
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Well, not bad. Now for the pattern of an attribute and an aggregation, respectively.
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             include yslt.yml2
vb@0: 
vb@0:             tstylesheet {
vb@0:                 template "/structure" apply "Entity";
vb@0: 
vb@0:                 template "Entity" document "{@name}.java" {
vb@0:                     if "aggregates" {
vb@0:                         | import java.util.Vector;
vb@0:                         | import java.util.Collections;
vb@0:                     }
vb@0: 
vb@0:                     | import base.Entity;
vb@0:                     | 
vb@0:                     | class `] &#xab`@name`] &#xbb` extends Entity {
vb@0:                     |     `] &#xab`@name`] &#xbb` {
vb@0:                     |         id = genId();
vb@0:                     |     }
vb@0:                     | 
vb@0: 
vb@0:                     apply "attr|aggregates";
vb@0: 
vb@0:                     | }
vb@0:                 }
vb@0: 
vb@0:                 template "attr" {
vb@0:                     |
vb@0:                     | // attribute `] &#xab`@name`] &#xbb`
vb@0:                     |
vb@0:                     | private `] &#xab`@type`] &#xbb` `] &#xab`@name`] &#xbb`;
vb@0:                     | public `] &#xab`@type`] &#xbb` get`] &#xab`@name`] &#xbb`() {
vb@0:                     |     return `] &#xab`@name`] &#xbb`;
vb@0:                     | }
vb@0:                     | public void set`] &#xab`@name`] &#xbb`(`] &#xab`@type`] &#xbb` value) {
vb@0:                     |     `] &#xab`@name`] &#xbb` = value;
vb@0:                     | }
vb@0:                 }
vb@0:                 
vb@0:                 template "aggregates" {
vb@0:                     |
vb@0:                     | // `] &#xab`@entity`] &#xbb` aggregation
vb@0:                     | 
vb@0:                     | protected Vector `] &#xab`@entity`] &#xbb`List = new Vector();
vb@0:                     | void add`] &#xab`@entity`] &#xbb`(`] &#xab`@entity`] &#xbb` entity) {
vb@0:                     |     `] &#xab`@entity`] &#xbb`List.add(entity);
vb@0:                     | }
vb@0:                     | void remove`] &#xab`@entity`] &#xbb`(`] &#xab`@entity`] &#xbb` entity) {
vb@0:                     |     `] &#xab`@entity`] &#xbb`List.remove(entity);
vb@0:                     | }
vb@0:                     | Iterator `] &#xab`@entity`] &#xbb`Iterator() {
vb@0:                     |     return `] &#xab`@entity`] &#xbb`List.iterator();
vb@0:                     | }
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         As you can see, we're deconstructing step by step. This is a good idea to get
vb@0:         into code generation with YSLT, but it remains a good idea even for the advanced
vb@0:         programmer: it keeps a clear view on what's happening.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         In the last step, test it out and make a diff to your target code. You will see
vb@0:         that our example needs some beautifying: in Java, camel case is important and
vb@0:         makes you some work to revert characters to uppercase or lowercase, respectively.
vb@0:         For that work you'll see that ¬http://www.w3.org/TR/xpath/#function-translate XPath's translate() function¬ is a little bit ugly ;-)
vb@0:         So we're defining an ¬features#userop operator¬ for that at the top of the file:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             define operator "“(.*?)”" as call "ucase" with "text", "%1";
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Inside the template, we're defining the ucase function:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:                 function "ucase" {
vb@0:                     param "text";
vb@0: 
vb@0:                     value "translate(substring($text,1,1),'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')";
vb@0:                     value "substring($text, 2)";
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Now we can replace one quoting with another; have a look at the getter and setter 
vb@0:         methods:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             include yslt.yml2
vb@0: 
vb@0:             define operator "“(.*?)”" as call "ucase" with "text", "%1";
vb@0: 
vb@0:             tstylesheet {
vb@0:                 template "/structure" apply "Entity";
vb@0: 
vb@0:             [...]
vb@0: 
vb@0:                 template "attr" {
vb@0:                     |
vb@0:                     | // attribute `] &#xab`@name`] &#xbb`
vb@0:                     |
vb@0:                     | private `] &#xab`@type`] &#xbb` `] &#xab`@name`] &#xbb`;
vb@0:                     | public `] &#xab`@type`] &#xbb` get“@name”() {
vb@0:                     |     return `] &#xab`@name`] &#xbb`;
vb@0:                     | }
vb@0:                     | public void set“@name”(`] &#xab`@type`] &#xbb` value) {
vb@0:                     |     `] &#xab`@name`] &#xbb` = value;
vb@0:                     | }
vb@0:                 }
vb@0: 
vb@0:             [...]
vb@0: 
vb@0:                 function "ucase" {
vb@0:                     param "text";
vb@0: 
vb@0:                     value "translate(substring($text,1,1),'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')";
vb@0:                     value "substring($text, 2)";
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Well, the rest is a pure laborious task ;-) Feel free to complete. And: use diff!
vb@0:         >>
vb@0: 
vb@0:     h3 id=ddlgen > A more advanced example: generating SQL DDL out of an UML diagram
vb@0: 
vb@0:     p   >>
vb@0:         Well, now for something real ;-) This is a very common task: somebody models
vb@0:         with an ¬http://en.wikipedia.org/wiki/Class_diagram UML class diagram¬, and you want
vb@0:         to have SQL ¬http://en.wikipedia.org/wiki/Data_Definition_Language DDL¬, which generates
vb@0:         a matching database structure.
vb@0:         >>
vb@0: 
vb@0:     p > Let's go:
vb@0: 
vb@0:     p   >>
vb@0:         First, lets use a stylesheet, which declares the needed
vb@0:         ¬http://www.w3.org/TR/REC-xml-names/ XMI namespaces¬:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:             include yslt.yml2
vb@0: 
vb@0:             tstylesheet xmlns:uml="http://schema.omg.org/spec/UML/2.1",
vb@0:                         xmlns:xmi="http://schema.omg.org/spec/XMI/2.1" {
vb@0:             ||
vb@0: 
vb@0:     p > Now, search the Model for all content:
vb@0: 
vb@0:     Code |    template "/" apply "xmi:XMI/uml:Model/packagedElement", 0;
vb@0: 
vb@0:     p   >>
vb@0:         We're translating ¬http://en.wikipedia.org/wiki/Package_(UML) UML Packages¬ into
vb@0:         underscore separated prefixes:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:                 template "packagedElement[@xmi:type='uml:Package']" {
vb@0:                     param "name", "''";
vb@0:                     if "$name=''"  apply "packagedElement", 0 { with "name", "@name"; }
vb@0:                     if "$name!=''" apply "packagedElement", 0 { with "name", "concat($name, '_', @name)"; }
vb@0:                 }
vb@0: 
vb@0:             ||
vb@0: 
vb@0:     p > Each Class is represented by a table in the database:
vb@0: 
vb@0:     Code    ||
vb@0:                 template "packagedElement[@xmi:type='uml:Class']" {
vb@0:                     param "name";
vb@0: 
vb@0:                     | CREATE TABLE «$name»_«@name» (
vb@0:                     apply "ownedAttribute";
vb@0:                     | );
vb@0:                 }
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         Finally, for each different data type for an attribute we're outputting different fields
vb@0:         with different types:
vb@0:         >>
vb@0: 
vb@0:     Code    ||
vb@0:                 template "ownedAttribute[@xmi:type='uml:Property' and type/@xmi:type='uml:PrimitiveType']" {
vb@0:                     0> «@name»
vb@0:                     choose {
vb@0:                         when "type/@href='http://schema.omg.org/spec/UML/2.1/uml.xml#String'"
vb@0:                             >  VARCHAR
vb@0: 
vb@0:                         // [...] for other types, extend when clauses
vb@0:                     }
vb@0:                     if "position()!=last()" > ,
vb@0:                     text "\\n";
vb@0:                 }
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     p > Our little sample only supports «VARCHAR», but it is an easy game to play to complete that.
vb@0: 
vb@0:     p   >>
vb@0:         Here you can download the ¬samples/xmi2ddl.ysl2 XMI 2 DDL compiler sample¬. I used
vb@0:         ¬http://bouml.free.fr/ BOUML¬ to create a small ¬samples/demo.xmi UML sample file¬
vb@0:         as ¬http://www.omg.org/spec/XMI/ XMI 2.1¬.
vb@0:         >>
vb@0: 
vb@0:     p > To compile that, use:
vb@0: 
vb@0:     Code    ||
vb@0:             % yml2proc -y xmi2ddl.ysl2 -x demo.xmi 
vb@0:             CREATE TABLE demo_Customer (
vb@0:                 id VARCHAR,
vb@0:                 name VARCHAR
vb@0:             );
vb@0:             % _
vb@0:             ||
vb@0: 
vb@0:     p   >>
vb@0:         In the samples directory you'll find
vb@0:         ¬samples/xmi2ddl.uml2 a prettier solution¬ using ¬samples/uml.yml2 some declares to prettify¬.
vb@0:         >>
vb@0: 
vb@0:     h1 id=features > Features of YSLT
vb@0: 
vb@0:     p   >>
vb@0:         Because YSLT just generates XSLT programs, it will be a good idea to read the
vb@0:         ¬http://www.w3.org/TR/xslt XSLT Documentation¬ as well as the
vb@0:         ¬http://www.w3.org/TR/xpath XPath Documentation¬.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         In the following, you find a ¬#functionlist List of YSLT Functions¬ and a
vb@0:         ¬#operatorlist List of YSLT Operators¬.
vb@0:         >>
vb@0: 
vb@0:     h2 id=functionlist > List of YSLT Functions
vb@0: 
vb@0:     h3 > apply(select, *indent=1)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:apply-templates />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Applying-Template-Rules tag¬. The «*indent» pointer gives
vb@0:         the number of indention levels to add (default: 1) for the Indention System.
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | apply "attr|aggregation", mode=define;
vb@0: 
vb@0:     h3 id=assert > assert(test, msg)
vb@0: 
vb@0:     p   >>
vb@0:         Generates «<xsl:value-of select="yml:assert(test, msg)"». See the ¬#ymlassert yml:assert() XPath extension¬.
vb@0:         This function does not generate anything when not being called by ¬toolchain#processor ysltproc¬
vb@0:         with the --debug switch.
vb@0:         >>
vb@0: 
vb@0:     h3 > attrib(name, namespace)
vb@0: 
vb@0:     p > Generates the «<xsl:attribute />» ¬http://www.w3.org/TR/xslt#creating-attributes tag¬.
vb@0: 
vb@0:     h3 > call(name)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<call-template />» ¬http://www.w3.org/TR/xslt#named-templates tag¬.
vb@0:         Used to call a «function()».
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | call "ucase" with "text", "$name";
vb@0: 
vb@0:     h3 > choose()
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:choose />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Conditional-Processing-with-xsl:choose tag¬.
vb@0:         Use in a «choose() ... when()... otherwise()...» structure.
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code    ||
vb@0:             choose {
vb@0:                 when "$id=1"
vb@0:                     > yes
vb@0:                 when "$id=2"
vb@0:                     > no
vb@0:                 otherwise
vb@0:                     error "invalid id";
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     h3 > comment()
vb@0: 
vb@0:     p > Generates the «<xsl:comment />» ¬http://www.w3.org/TR/xslt#section-Creating-Comments tag¬.
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | comment "this comment will remain in XML";
vb@0: 
vb@0:     h3 > const(name, select)
vb@0: 
vb@0:     p > Generates the «<xsl:variable />» ¬http://www.w3.org/TR/xslt#variables tag¬.
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | const "pi", 3.14;
vb@0: 
vb@0:     h3 > copy(select)
vb@0: 
vb@0:     p > Generates the «<xsl:copy-of />» ¬http://www.w3.org/TR/xslt#copy-of tag¬.
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | copy ".";
vb@0: 
vb@0:     h3 id=debug > debug(msg)
vb@0: 
vb@0:     p   >>
vb@0:         Generates «<xsl:value-of select="yml:debug(msg)"». See the ¬#ymldebug yml:debug() XPath extension¬.
vb@0:         This function does not generate anything when not being called by ¬toolchain#processor ysltproc¬
vb@0:         with the --debug switch.
vb@0:         >>
vb@0: 
vb@0:     h3 > def(name)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the ¬http://www.exslt.org EXSLT¬ «<func:funcion />»
vb@0:         ¬http://www.exslt.org/func/elements/function/ tag¬.
vb@0:         >>
vb@0: 
vb@0:     h3 id=edocument > document(href, method)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the ¬http://www.exslt.org EXSLT¬ «<exsl:document />»
vb@0:         ¬http://www.exslt.org/exsl/elements/document/ tag¬.
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code    ||
vb@0:             template "entity" document "{@name}.java" {
vb@0:                 […]
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     h3 > element(name, namespace)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:element />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Creating-Elements-with-xsl:element tag¬.
vb@0:         >>
vb@0: 
vb@0:     h3 > error()
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:message />» ¬http://www.w3.org/TR/xslt#message tag¬
vb@0:         with attribute «terminate» set to "yes".
vb@0:         >>
vb@0: 
vb@0:     h3 > estylesheet(*output="xml")
vb@0: 
vb@0:     p   >>
vb@0:         Does the same as «stylesheet()», but additionally declares the ¬http://www.exslt.org/ EXSLT¬
vb@0:         functions of the groups «exsl», «func», «str», «dyn», «set» and «math» and declares the
vb@0:         corresponding name spaces.
vb@0:         >>
vb@0: 
vb@0:     h3 > for(select)
vb@0: 
vb@0:     p > Generates the «<xsl:for-each />» ¬http://www.w3.org/TR/xslt#for-each tag¬.
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | for "../structure[@name='hello'" > «@type»
vb@0: 
vb@0:     h3 > foreach(select)
vb@0: 
vb@0:     p > Same as «for()».
vb@0: 
vb@0:     h3 > function(name)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:template />» ¬http://www.w3.org/TR/xslt#named-templates tag¬.
vb@0:         Used by calling with «call()».
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code    ||
vb@0:             function "ucase" {
vb@0:                 param "text";
vb@0: 
vb@0:                 value "translate(substring($text,1,1),'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')";
vb@0:                 value "substring($text, 2)";
vb@0:             }
vb@0:             ||
vb@0: 
vb@0:     h3 > if(test)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:if />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Conditional-Processing-with-xsl:if tag¬.
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | if "position()<last()" > , 
vb@0: 
vb@0:     h3 > import(href)
vb@0: 
vb@0:     p > Generates the «<xsl:import />» ¬http://www.w3.org/TR/xslt#import tag¬.
vb@0: 
vb@0:     h3 > key(name, match, use)
vb@0: 
vb@0:     p > Generates the «<xsl:key />» ¬http://www.w3.org/TR/xslt#key tag¬.
vb@0: 
vb@0:     h3 > message()
vb@0: 
vb@0:     p > Generates the «<xsl:message />» ¬http://www.w3.org/TR/xslt#message tag¬.
vb@0: 
vb@0:     h3 > otherwise()
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:otherwise />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Conditional-Processing-with-xsl:choose tag¬.
vb@0:         Use in a «choose() ... when()... otherwise()...» structure.
vb@0:         >>
vb@0: 
vb@0:     h3 > output(method)
vb@0: 
vb@0:     p > Generates the «<xsl:output />» ¬http://www.w3.org/TR/xslt#output tag¬.
vb@0: 
vb@0:     h3 > param(name, select)
vb@0: 
vb@0:     p > Generates the «<xsl:param />» ¬http://www.w3.org/TR/xslt#variables tag¬.
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | param "x", 42;
vb@0: 
vb@0:     h3 > processing(name)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:processing-instruction />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Creating-Processing-Instructions tag¬.
vb@0:         >>
vb@0: 
vb@0:     h3 > raw()
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:text />» ¬http://www.w3.org/TR/xslt#section-Creating-Text tag¬.
vb@0:         Sets the attribute «disable-output-escaping» to "yes".
vb@0:         >>
vb@0: 
vb@0:     h3 > result(select)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the ¬http://www.exslt.org EXSLT¬ «<func:result />»
vb@0:         ¬http://www.exslt.org/func/elements/result/ tag¬.
vb@0:         >>
vb@0: 
vb@0:     h3 > stylesheet(*output="xml")
vb@0: 
vb@0:     p   >>
vb@0:         Generates the XSLT «<stylesheet />» ¬http://www.w3.org/TR/xslt#stylesheet-element tag¬.
vb@0:         Additionally generates an «<output />» ¬http://www.w3.org/TR/xslt#output tag¬
vb@0:         in the body, with attribute «method» set to the value of the pointer «*output» (default: "xml").
vb@0:         >>
vb@0: 
vb@0:     p > The content you're giving is placed in the body after the «<output />» tag.
vb@0: 
vb@0:     p > The «version» attribute is set to "1.0" and XML namespace «xsl» is correctly defined.
vb@0: 
vb@0:     p   >>
vb@0:         In short: use for a stylesheet, just give the output type as parameter, if you don't want to
vb@0:         to generate XML but HTML ("html") oder plain text ("text").
vb@0:         >>
vb@0: 
vb@0:     p > «stylesheet()» additionally generates tags for the Indention System.
vb@0: 
vb@0:     h3 > template(match)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:template />» ¬http://www.w3.org/TR/xslt#section-Defining-Template-Rules tag¬.
vb@0:         Additionally generates tags for the Indention System.
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code    ||
vb@0:             template "attr", mode=declare
vb@0:                 | attribute `] &#xab@type&#xbb` `] &#xab@name&#xbb`;
vb@0:             ||
vb@0: 
vb@0:     h3 > text()
vb@0: 
vb@0:     p > Generate the «<xsl:text />» ¬http://www.w3.org/TR/xslt#section-Creating-Text tag¬.
vb@0: 
vb@0:     h3 > textstylesheet()
vb@0: 
vb@0:     p > Same as «estylesheet()», but «*output» is now "text", that means the stylesheet outputs plain text.
vb@0: 
vb@0:     h3 > tstylesheet()
vb@0: 
vb@0:     p > Same as «textstylesheet()».
vb@0: 
vb@0:     h3 > value(select)
vb@0: 
vb@0:     p > Generates the «<xsl:value-of />» ¬http://www.w3.org/TR/xslt#value-of tag¬.
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | value "@name";
vb@0: 
vb@0:     h3 > warning()
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:message />» ¬http://www.w3.org/TR/xslt#message tag¬
vb@0:         with attribute «terminate» set to "no".
vb@0:         >>
vb@0: 
vb@0:     h3 > when()
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:when />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Conditional-Processing-with-xsl:choose tag¬.
vb@0:         Use in a «choose() ... when()... otherwise()...» structure.
vb@0:         >>
vb@0: 
vb@0:     h3 > with(name, select)
vb@0: 
vb@0:     p   >>
vb@0:         Generates the «<xsl:with-param />»
vb@0:         ¬http://www.w3.org/TR/xslt#section-Passing-Parameters-to-Templates tag¬.
vb@0:         >>
vb@0: 
vb@0:     p i > Example:
vb@0: 
vb@0:     Code | call "ucase" with "text", "$name";
vb@0: 
vb@0:     h2 id=operatorlist > List of YSLT Text Operators
vb@0: 
vb@0:     h3 id="angledouble" > Operator `] <code>&#xab…&#xbb</code>`
vb@0: 
vb@0:     p > Generate YSLT Function Call «value('…')».
vb@0: 
vb@0:     h2 id=xpathext > Debugging Functions
vb@0: 
vb@0:     p   >>
vb@0:         YML defines two functions in namespace http://fdik.org/yml, which are enabled if the command line
vb@0:         option --debug is given in ¬yslt#processor yml2proc¬.
vb@0:         >>
vb@0: 
vb@0:     h3 id=ymlassert > yml:assert(test, msg)
vb@0: 
vb@0:     p   >>
vb@0:         If XPath expression «test» evaluates to «false()» or to an empty set, XPath expression «msg» is
vb@0:         printed to stderr; the compilation then aborts with an error.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         Better don't use it directly, use the ¬#assert assert() YSLT function¬.
vb@0:         >>
vb@0: 
vb@0:     h3 id=ymldebug > yml:debug(msg)
vb@0: 
vb@0:     p   >>
vb@0:         Prints XPath expression «msg» to stderr.
vb@0:         >>
vb@0: 
vb@0:     p   >>
vb@0:         Better don't use it directly, use the ¬#debug debug() YSLT function¬.
vb@0:         >>
vb@0: 
vb@0:     h2 id=stdlib > Standard Function Library
vb@0: 
vb@0:     p   >>
vb@0:         Additionally, you can «include standardlib.ysl2» in the body of your stylesheet.
vb@0:         Then you'll have these extra functions:
vb@0:         >>
vb@0: 
vb@0:     h3 id=dec2hex > yml:dec2hex(dec, digits=8)
vb@0: 
vb@0:     p   >>
vb@0:         Converts number «dec» into a string with a hexadecimal representation filled up to
vb@0:         «digits» digits. If you're omitting the second parameter, it is set to 8.
vb@0:         >>
vb@0: 
vb@0:     h3 id=hex2dec > yml:hex2dec(hex)
vb@0: 
vb@0:     p   >>
vb@0:         Converts the string «hex» consisting of hexadecimal digits into a number.
vb@0:         >>
vb@0: 
vb@0:     h3 id=lcase > yml:lcase(text)
vb@0: 
vb@0:     p   >>
vb@0:         Converts all uppercase letters of string «text» into lowercase ones.
vb@0:         >>
vb@0: 
vb@0:     h3 id=ucase > yml:ucase(text)
vb@0: 
vb@0:     p   >>
vb@0:         Converts all lowercase letters of string «text» into uppercase ones.
vb@0:         >>
vb@0: 
vb@0:     div id=bottom {
vb@0:         a href="features" "<< back to YML Features" " "
vb@0:         a href="#top" "^Top^" " "
vb@0:         a href="toolchain" "> > explain the Tool Chain" " "
vb@0:         a href="yslt.en.yhtml2" "(source)"
vb@0:     }
vb@0: }
vb@0: