1

include homepage.en.yhtml2

     2

     3

page "YSLT – XSLT C style" {

     4

    h1 id=intro > YSLT – an introduction

     5

     6

    p   >>

     7

        Especially the ¬http://www.w3.org/TR/xslt XSLT¬ programmer can benefit from YML.

     8

        Usually many attributes of XSLT are annoying in programming praxis:

     9

        >>

    10

    11

    ul {

    12

        li  >>

    13

            the missing separation of ¬http://en.wikipedia.org/wiki/Indent_style indention¬

    14

            of the XSLT program and indention of the output text

    15

            >>

    16

    17

        li > the complicated syntax

    18

    19

        li > the lack of good text escaping mechanisms (< and > are not seldom)

    20

    21

        li > ...

    22

    }

    23

    24

    p > In short, it's ugly ;-)

    25

    26

    p   >>

    27

        Usually the result is, that many programmers are avoiding XSLT as a programming language.

    28

        It's a pity, because for processing XML data, it can do much more than “formatting” as

    29

        “stylesheets”.

    30

        >>

    31

    32

    p   >>

    33

        The idea of YSLT now is to supply a simple language, which programmers want to use, to

    34

        make the features of XSLT accessible to a broader base of people.

    35

        >>

    36

    37

    p   >>

    38

        YSLT can be used much simpler; it's just a ¬http://fdik.org/yml/index#ylanguages Y Language¬

    39

        for XSLT. I'm using it for my blog, here you can ¬http://fdik.org/yblog2.tar.bz2 download YBlog2¬,

    40

        a simple blogging software in YSLT.

    41

        >>

    42

    43

    p > Here you can find the ¬yslt.yml2 YSLT specification¬.

    44

    45

    h2 id=hello > Hello, World

    46

    47

    p > In YSLT, the hello world program reads like this:

    48

    49

    Code    ||

    50

            include yslt.yml2

    51

            textstylesheet template "/" | hello, world

    52

            ||

    53

    54

    p   >>

    55

        The `a href="http://fdik.org/yml/features#including" code > include` line includes the

    56

        YSLT Y Language declarations. The second line generates an XSLT hello world program.

    57

        You can generate it using:

    58

        >>

    59

    60

    Code | % yml2c -o hello.xsl hello.ysl2

    61

    62

    p > This results in the following program:

    63

    64

    Code    ||

    65

            <xsl:stylesheet xmlns:func="http://exslt.org/functions"

    66

            xmlns:dyn="http://exslt.org/dynamic" xmlns:str="http://exslt.org/strings"

    67

            xmlns:math="http://exslt.org/math"

    68

            xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

    69

            extension-element-prefixes="exsl func str dyn set math"

    70

            xmlns:set="http://exslt.org/sets" version="1.0"

    71

            xmlns:exsl="http://exslt.org/common"><xsl:output method="text"/>

    72

            <xsl:variable name="space" select="'                                 '"/>

    73

            <xsl:param name="autoindent" select="4"/><xsl:template match="/">

    74

            <xsl:param name="_indent" select="0"/><xsl:value-of

    75

            select="substring($space, 1, $_indent+0*$autoindent)"/>hello, world

    76

            </xsl:template></xsl:stylesheet>

    77

            ||

    78

    79

    p   >>

    80

        You can execute this program with any

    81

        ¬http://en.wikipedia.org/wiki/XML_template_engine XSL processor¬, for example the Free Software

    82

        ¬http://xmlsoft.org/XSLT/xsltproc2.html xsltproc¬.

    83

        >>

    84

    85

    Code    ||

    86

            % yml2c -o hello.xsl hello.ysl2

    87

            % echo '<empty/>' > empty.xml          

    88

            % xsltproc hello.xsl empty.xml 

    89

            hello, world

    90

            % _

    91

            ||

    92

    93

    p   >>

    94

        Or you can just use ¬toolchain#processor yml2proc¬:

    95

        >>

    96

    97

    Code    ||

    98

            % yml2proc -My hello.ysl2

    99

            hello, world

   100

            % _

   101

            ||

   102

   103

    h2 id=programming > Programming in YSLT

   104

   105

    p   >>

   106

        Because YSLT is just a ¬index#ylanguages Y Language¬ for XSLT, you can do anything with YSLT

   107

        you can do with XSLT in just nicer syntax ;-) To read what XSLT is all about, I recommend 

   108

        ¬http://www.w3.org/TR/xslt the official W3C documentation for XSLT¬.

   109

        >>

   110

   111

    p   >>

   112

        So this document is just an beginners guide, if you want to understand XSLT completely,

   113

        better read the ¬http://www.w3.org W3C¬ stuff.

   114

        >>

   115

   116

    h3 > Programming YSLT means programming with a pure functional language.

   117

   118

    p   >>

   119

        Lovers of ¬http://en.wikipedia.org/wiki/Lisp_(programming_language) Lisp¬ or

   120

        ¬http://www.haskell.org/ Haskell¬ will not see any problems. But many programmers are used to

   121

        have a programming language with a

   122

        ¬http://en.wikipedia.org/wiki/Procedural_programming procedural imperative paradigma¬ like

   123

        ¬http://java.sun.com Java¬,

   124

        ¬http://en.wikipedia.org/wiki/C_(programming_language) C¬/¬http://en.wikipedia.org/wiki/C++ C++¬

   125

        or ¬http://www.python.org Python¬. Why should they use a

   126

        ¬http://en.wikipedia.org/wiki/Functional_programming functional¬ language?

   127

        >>

   128

   129

    p   >>

   130

        Actually, if a functional language is practical or not, depends of what's to do – “the

   131

        right tool for the task”, one could say.

   132

        >>

   133

   134

    p   >>

   135

        Because processing XML data means traversing a (document) tree,

   136

        ¬http://en.wikipedia.org/wiki/Recursion recursive¬ algorithms are a clear advantage.

   137

        And this is the reason, why choosing a functional language is a good choice for that job.

   138

        >>

   139

   140

    p   >>

   141

        It's a little bit like with ¬http://en.wikipedia.org/wiki/SQL SQL¬ – for it's job, it's

   142

        excellent, but no-one wants to write a complete application in SQL (and also not in one

   143

        of the Turing-complete SQL extension languages like

   144

        ¬http://www.oracle.com/technology/tech/pl_sql/index.html PL/SQL¬).

   145

        >>

   146

   147

    h3 id=htmlgen > Generating HTML out of a DSL

   148

   149

    p   >>

   150

        Of course, you can use YSLT as you would use XSLT. Let's say, you have data in XML

   151

        documents, and you want to have an excerpt out of this data. This is a common task,

   152

        comparable to «SELECT» data out of an SQL database. But we have no database, we have

   153

        something like this file customers.yml2:

   154

        >>

   155

   156

    Code    ||

   157

            decl customer(*id, *name) { id *id, name *name };

   158

   159

            list {

   160

                customer 23, "Kurt Meier";

   161

                customer 42, "Lieschen Schmidt";

   162

            }

   163

            ||

   164

   165

    p   >>

   166

        Let's say, we want to output this into an ¬http://en.wikipedia.org/wiki/XHTML XHTML¬ document,

   167

        where the list is showed as a table. Then we would do the following:

   168

        >>

   169

   170

    p > The XHTML document should be like the following and include the list in the body:

   171

   172

    Code    ||

   173

            include yslt.yml2

   174

   175

            stylesheet {

   176

                template "/" html {

   177

                    head title "Customer List";

   178

                    body apply "list";

   179

                }

   180

            ||

   181

   182

    p   >>

   183

        In the example above, stylesheet declares the main program. Then we define a template, which

   184

        is executed automatically starting reading the root «'/'» of the document tree of the XML

   185

        document we're processing.

   186

        >>

   187

   188

    p > Using the XML document as input, we're creating this HTML tree:

   189

   190

    Code    ||

   191

            <html>

   192

                <head>

   193

                    <title>Customer List</title>

   194

                </head>

   195

                <body>

   196

   197

                <!-- ... ->

   198

   199

                </body>

   200

            </html>

   201

            ||

   202

   203

    p > How do we create the list? Well, let's use a table with customers:

   204

   205

    Code |     template "list" table apply "customer";

   206

   207

    p   >>

   208

        What to do per customer? Well, generate a table row with two columns, one for «id» and one

   209

        for «name»:

   210

        >>

   211

   212

    Code    ||

   213

                template "customer" tr {

   214

                    td value "id";

   215

                    td value "name";

   216

                }

   217

            }

   218

            ||

   219

   220

    p > That was it. We now can run our small program:

   221

   222

    Code | % yml2proc -y customer.ysl2 -x customer.xml -o customer.html -P

   223

   224

    p > The result looks like this:

   225

   226

    Code    ||

   227

            % cat customer.html 

   228

            <?xml version="1.0"?>

   229

            <html>

   230

              <head>

   231

                <title>Customer List</title>

   232

              </head>

   233

              <body>

   234

                <table>

   235

                  <tr>

   236

                    <td>23</td>

   237

                    <td>Kurt Meier</td>

   238

                  </tr>

   239

                  <tr>

   240

                    <td>42</td>

   241

                    <td>Lieschen Schmidt</td>

   242

                  </tr>

   243

                </table>

   244

              </body>

   245

            </html>

   246

            % _

   247

            ||

   248

   249

    p > Here you can download ¬samples/customer.ysl2 the complete program¬.

   250

   251

    h3 id=codegen > How to generate code with YSLT

   252

   253

    p > Generating code is easy with YSLT, if you follow these steps:

   254

   255

    ol {

   256

        li > design the software you want to generate using patterns and write that in a DSL

   257

        li > write target code once for each pattern

   258

        li > deconstruct a compiler for the target code for each pattern

   259

        li > fine tune until the diff is empty

   260

    }

   261

   262

    p   >>

   263

        Let's test by example. First let's say, we have a pattern of entities we want

   264

        to implement as Java beans. The enities in our DSL are:

   265

        >>

   266

   267

    Code    ||

   268

            decl entity +name;

   269

            decl attr +type +name;

   270

            decl aggregates +entity;

   271

   272

            structure {

   273

                entity Customer {

   274

                    attr String name;

   275

                    attr int creditLimit;

   276

                    aggregates Order;

   277

                }

   278

   279

                entity Order {

   280

                    attr String no;

   281

                    attr String description;

   282

                    attr int amount;

   283

                }

   284

            }

   285

            ||

   286

   287

    p   >>

   288

        How to write that in a Java Program? Well, following the second step, we're

   289

        writing our target code manually; for this simple sample, let's be naive and

   290

        save the following into a file named Customer.java.target:

   291

        >>

   292

   293

    Code    ||

   294

            import java.util.Vector;

   295

            import java.util.Collections;

   296

            import base.Entity;

   297

   298

            class Customer extends Entity {

   299

                Customer {

   300

                    id = genId();

   301

                }

   302

   303

                // attribute name

   304

   305

                private String name;

   306

                public String getName() {

   307

                    return name;   

   308

                }

   309

                public void setName(String value) {

   310

                    name = value;

   311

                }

   312

   313

                // attribute creditLimit

   314

   315

                private int creditLimit;

   316

                public int getCreditLimit() {

   317

                    return creditLimit;   

   318

                }

   319

                public void setCreditLimit(int value) {

   320

                    creditLimit = value;

   321

                }

   322

   323

                // Order aggregation

   324

   325

                protected Vector orderList = new Vector();

   326

                void addOrder(Order entity) {

   327

                    orderList.add(entity);

   328

                }

   329

                void removeOrder(Order entity) {

   330

                    orderList.remove(entity);

   331

                }

   332

                Iterator orderIterator() {

   333

                    return orderList.iterator();

   334

                }

   335

            }

   336

            ||

   337

   338

    p   >>

   339

        The third step does most of the work. First we cite this code

   340

        into gen_entity.ysl2 and create the basic form of an YSLT script:

   341

        >>

   342

   343

    Code    ||

   344

            include yslt.yml2

   345

   346

            tstylesheet {

   347

                template "/" {

   348

                    | import java.util.Vector;

   349

                    | import java.util.Collections;

   350

                    | import base.Entity;

   351

                    | 

   352

                    | class Customer extends Entity {

   353

                    |     Customer {

   354

                    |         id = genId();

   355

                    |     }

   356

                    | 

   357

                    |     // attribute name

   358

                    |     

   359

                    |     private String name;

   360

                    |     public String getName() {

   361

                    |         return name;   

   362

                    |     }

   363

                    |     public void setName(String value) {

   364

                    |         name = value;

   365

                    |     }

   366

                    | 

   367

                    |     // attribute creditLimit

   368

                    | 

   369

                    |     private int creditLimit;

   370

                    |     public int getCreditLimit() {

   371

                    |         return creditLimit;   

   372

                    |     }

   373

                    |     public void setCreditLimit(int value) {

   374

                    |         creditLimit = value;

   375

                    |     }

   376

                    | 

   377

                    |     // Order aggregation

   378

                    | 

   379

                    |     protected Vector orderList = new Vector();

   380

                    |     void addOrder(Order entity) {

   381

                    |         orderList.add(entity);

   382

                    |     }

   383

                    |     void removeOrder(Order entity) {

   384

                    |         orderList.remove(entity);

   385

                    |     }

   386

                    |     Iterator orderIterator() {

   387

                    |         return orderList.iterator();

   388

                    |     }

   389

                    | }

   390

                }

   391

            }

   392

            ||

   393

   394

    p   >>

   395

        Now for the deconstruction. I think, it'll be best, if we

   396

        ¬#edocument create a .java file for each entity¬.

   397

        So we're moving the whole thing into a template for each entity

   398

        creating a file, and we're applying this for each entity using the name of each

   399

        Entity as parameter. We're adding some distinction of cases, too.

   400

        >>

   401

   402

    p   >>

   403

        When we apply, the indention system of YSLT will add an indention level, so we can

   404

        take out rendundant whitespace; for the first apply we don't want this, so we're

   405

        giving the number 0 as the indention level.

   406

        >>

   407

   408

    p   >>

   409

        In attributes, braces «{…}» let us insert the value of an XPath expression into our

   410

        DSL, while inside quoted text the same is done by the ¬#angledouble angle double quotes¬

   411

        `] <code>&#xab…&#xbb</code>`:

   412

        >>

   413

   414

    Code    ||

   415

            include yslt.yml2

   416

   417

            tstylesheet {

   418

                template "/structure" apply "Entity", 0;

   419

   420

                template "Entity" document "{@name}.java" {

   421

                    if "aggregates" {

   422

                        | import java.util.Vector;

   423

                        | import java.util.Collections;

   424

                    }

   425

   426

                    | import base.Entity;

   427

                    | 

   428

                    | class `] &#xab`@name`] &#xbb` extends Entity {

   429

                    |     `] &#xab`@name`] &#xbb` {

   430

                    |         id = genId();

   431

                    |     }

   432

                    | 

   433

            [...]

   434

                    |         orderList.remove(entity);

   435

                    |     }

   436

                    |     Iterator orderIterator() {

   437

                    |         return orderList.iterator();

   438

                    |     }

   439

                    | }

   440

                }

   441

            }

   442

            ||

   443

   444

    p   >>

   445

        Well, not bad. Now for the pattern of an attribute and an aggregation, respectively.

   446

        >>

   447

   448

    Code    ||

   449

            include yslt.yml2

   450

   451

            tstylesheet {

   452

                template "/structure" apply "Entity";

   453

   454

                template "Entity" document "{@name}.java" {

   455

                    if "aggregates" {

   456

                        | import java.util.Vector;

   457

                        | import java.util.Collections;

   458

                    }

   459

   460

                    | import base.Entity;

   461

                    | 

   462

                    | class `] &#xab`@name`] &#xbb` extends Entity {

   463

                    |     `] &#xab`@name`] &#xbb` {

   464

                    |         id = genId();

   465

                    |     }

   466

                    | 

   467

   468

                    apply "attr|aggregates";

   469

   470

                    | }

   471

                }

   472

   473

                template "attr" {

   474

                    |

   475

                    | // attribute `] &#xab`@name`] &#xbb`

   476

                    |

   477

                    | private `] &#xab`@type`] &#xbb` `] &#xab`@name`] &#xbb`;

   478

                    | public `] &#xab`@type`] &#xbb` get`] &#xab`@name`] &#xbb`() {

   479

                    |     return `] &#xab`@name`] &#xbb`;

   480

                    | }

   481

                    | public void set`] &#xab`@name`] &#xbb`(`] &#xab`@type`] &#xbb` value) {

   482

                    |     `] &#xab`@name`] &#xbb` = value;

   483

                    | }

   484

                }

   485

   486

                template "aggregates" {

   487

                    |

   488

                    | // `] &#xab`@entity`] &#xbb` aggregation

   489

                    | 

   490

                    | protected Vector `] &#xab`@entity`] &#xbb`List = new Vector();

   491

                    | void add`] &#xab`@entity`] &#xbb`(`] &#xab`@entity`] &#xbb` entity) {

   492

                    |     `] &#xab`@entity`] &#xbb`List.add(entity);

   493

                    | }

   494

                    | void remove`] &#xab`@entity`] &#xbb`(`] &#xab`@entity`] &#xbb` entity) {

   495

                    |     `] &#xab`@entity`] &#xbb`List.remove(entity);

   496

                    | }

   497

                    | Iterator `] &#xab`@entity`] &#xbb`Iterator() {

   498

                    |     return `] &#xab`@entity`] &#xbb`List.iterator();

   499

                    | }

   500

                }

   501

            }

   502

            ||

   503

   504

    p   >>

   505

        As you can see, we're deconstructing step by step. This is a good idea to get

   506

        into code generation with YSLT, but it remains a good idea even for the advanced

   507

        programmer: it keeps a clear view on what's happening.

   508

        >>

   509

   510

    p   >>

   511

        In the last step, test it out and make a diff to your target code. You will see

   512

        that our example needs some beautifying: in Java, camel case is important and

   513

        makes you some work to revert characters to uppercase or lowercase, respectively.

   514

        For that work you'll see that ¬http://www.w3.org/TR/xpath/#function-translate XPath's translate() function¬ is a little bit ugly ;-)

   515

        So we're defining an ¬features#userop operator¬ for that at the top of the file:

   516

        >>

   517

   518

    Code    ||

   519

            define operator "“(.*?)”" as call "ucase" with "text", "%1";

   520

            ||

   521

   522

    p   >>

   523

        Inside the template, we're defining the ucase function:

   524

        >>

   525

   526

    Code    ||

   527

                function "ucase" {

   528

                    param "text";

   529

   530

                    value "translate(substring($text,1,1),'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')";