1

include homepage.en.yhtml2

     2

     3

page "The YML Toolchain" {

     4

    h1 > The Toolchain

     5

     6

    p   >>

     7

        There are to possibilities to handle YML files: the YML compiler and the YML/YSLT

     8

        processor.

     9

        >>

    10

    11

    h2 id=compiler > The YML compiler

    12

    13

    p   >>

    14

        The YML ¬http://en.wikipedia.org/wiki/Compiler compiler¬ is a small

    15

        ¬http://www.python.org Python script¬. It provides the

    16

        ¬http://en.wikipedia.org/wiki/Command-line_interface command line¬ front end «yml2c».

    17

        As default, it compiles your ¬http://en.wikipedia.org/wiki/Scripting_language script¬

    18

        and outputs to ¬http://en.wikipedia.org/wiki/Stdout#Standard_output_.28stdout.29 stdout¬,

    19

        that usually is the ¬http://en.wikipedia.org/wiki/Computer_terminal terminal¬.

    20

        Your ¬http://en.wikipedia.org/wiki/Shell_(computing) shell¬ provides options to redirect

    21

        the output into a ¬http://en.wikipedia.org/wiki/Pipeline_(Unix) pipe¬ or

    22

        a ¬http://en.wikipedia.org/wiki/Computer_file file¬.

    23

        >>

    24

    25

    p > So to use it, just enter «yml2c» followed by the filename of your YML script:

    26

    27

    Code | % yml2c myscript.yml2 > myscript.result

    28

    29

    p > The «yml2c» command has the following options:

    30

    31

    h3 > -h, --help

    32

    33

    p > Show a help message and exit.

    34

    35

    h3 > -C, --old-syntax

    36

    37

    p > Use the syntax of YML 2 version 1.x (compatibility mode).

    38

    39

    h3 > -D, --emit-linenumbers

    40

    41

    p > Emit line numbers into the resulting XML for debugging purposes.

    42

    43

    h3 > -E ENCODING, --encoding ENCODING

    44

    45

    p > encoding of input files (default: UTF-8)

    46

    47

    h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH

    48

    49

    p { "Precede " code > ¬features#ymlpath YML_PATH¬

    50

      " by a colon separated " code "INCLUDE_PATH"; " to search for include files." }

    51

    52

    h3 > -m, --omit-empty-parm-tags

    53

    54

    p   >>

    55

        Does nothing (only there for compatibility with older versions of «yml2c»).

    56

        >>

    57

    58

    h3 > -n NORMALIZATION, --normalization=NORMALIZATION

    59

    60

    p   >>

    61

        Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC)

    62

        >>

    63

    64

    h3 > -o FILE, --output=FILE

    65

    66

    p > Don't output to stdout, instead place output in file «FILE».

    67

    68

    h3 > -p, --parse-only

    69

    70

    p   >>

    71

        ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬

    72

        as text to stdout. The pyAST is the

    73

        ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬

    74

        of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬.

    75

        >>

    76

    77

    h3 > -V, --version

    78

    79

    p   >>

    80

        Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of

    81

        the YML implementation.

    82

        >>

    83

    84

    h3 > YML_PATH environment variable

    85

    86

    p   >>

    87

        If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬

    88

        list, then the `a href="features#including" code "include";` statement searches these paths.

    89

        If «YML_PATH» is not set, the local directory «.» is searched for files.

    90

        The system location for «.yml2» and «.ysl2» files is always searched afterwards.

    91

        >>

    92

    93

    h2 id=processor > The YML/YSLT processor

    94

    95

    p   >>

    96

        If you're processing more complex tasks, say, executing an YSLT script over some

    97

        YML files, the YML/YSLT processor will possible fit better to your needs.

    98

        >>

    99

   100

    p   >>

   101

        To use it, enter «yml2proc -y» followed by the filename of your YSLT script,

   102

        followed by the filenames of your YML input files:

   103

        >>

   104

   105

    Code | % yml2proc -y myscript.ysl2 inputfile.yml2 > myscript.result

   106

   107

    p > The YML/YSLT processor requires the ¬http://codespeak.net/lxml/ lxml Python library¬.

   108

   109

    p > The YML/YSLT processor has the following options:

   110

   111

    h3 > -h, --help

   112

   113

    p > Show a help message and exit.

   114

   115

    h3 > -C, --old-syntax

   116

   117

    p > Use the syntax of YML 2 version 1.x (compatibility mode).

   118

   119

    h3 > -D, --emit-linenumbers

   120

   121

    p > Emit line numbers into the resulting XML for debugging purposes.

   122

   123

    h3 id=debug > --debug

   124

   125

    p   >>

   126

        switch on debug tracing to stderr; this enables the functionality

   127

        of the ¬yslt#debug debug(msg)¬ and ¬yslt#assert assert yml:assert(test, msg)¬ YSLT functions.

   128

        >>

   129

   130

    h3 > -E ENCODING, --encoding ENCODING

   131

   132

    p > encoding of input files (default: UTF-8)

   133

   134

    h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH

   135

   136

    p { "Precede " code > ¬features#ymlpath YML_PATH¬

   137

      " by a colon separated " code "INCLUDE_PATH"; " to search for include files." }

   138

   139

    h3 > -m, --omit-empty-parm-tags

   140

   141

    p   >>

   142

        Does nothing (only there for compatibility with older versions of «yml2proc»).

   143

        >>

   144

   145

    h3 > -M, --empty-input-document

   146

   147

    p   >>

   148

        Use an empty input document for YSLT or XSLT processing

   149

        >>

   150

   151

    h3 > -n NORMALIZATION, --normalization=NORMALIZATION

   152

   153

    p   >>

   154

        Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC)

   155

        >>

   156

   157

    h3 > -o FILE, --output=FILE

   158

   159

    p > Don't output to stdout, instead place output in file «FILE».

   160

   161

    h3 > -p, --parse-only

   162

   163

    p   >>

   164

        ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬

   165

        as text to stdout. The pyAST is the

   166

        ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬

   167

        of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬.

   168

        >>

   169

   170

    h3 > -e XPATH, --xpath=XPATH

   171

   172

    p > Execute XPath expression XPATH and print result

   173

   174

    p   >>

   175

        If you omit -y YSLTSCRIPT, then the result is printed. If you have an additional

   176

        -y YSLTSCRIPT parameter, then your YSLT script is processing the result of the

   177

        XPath expression only instead of processing the complete content of your input documents

   178

        >>

   179

   180

    h3 > -P, --pretty

   181

   182

    p > Pretty print output adding whitespace

   183

   184

    h3 > -x, --xml

   185

   186

    p > Input documents are XML already, don't try to convert them from YML

   187

   188

    h3 > -y YSLTSCRIPT, --yslt=YSLTSCRIPT

   189

   190

    p > Execute YSLT script YSLTSCRIPT

   191

   192

    h3 > -X XSLTSCRIPT, --xslt=XSLTSCRIPT

   193

   194

    p > Execute XSLT script XSLTSCRIPT

   195

   196

    h3 > -d PARAMS, --paramdict=PARAMS

   197

   198

    p   >>

   199

        Call XSLT or YSLT script with dictionary PARAMS as XPath parameters. PARAMS is a Python

   200

        expression which evaluates to a Python dictionary.

   201

        >>

   202

   203

    p > Sample:

   204

   205

    p code > yml2proc -y myscript -d 'dict(a=3, b="element[@name=2]")'

   206

   207

    h3 > -s STRINGPARAMS, --stringparamdict=STRINGPARAMS

   208

   209

    p   >>

   210

        Call XSLT or YSLT script with dictionary STRINGPARAMS as string parameters. STRINGPARAMS

   211

        is a Python expression which evaluates to a Python dictionary.

   212

        >>  

   213

   214

    p > Sample:

   215

   216

    p code > yml2proc -y myscript -s 'dict(forename="Hans", name="Meier")'

   217

   218

    h3 > -Y, --xml2yml

   219

   220

    p > Convert XML to normalized YML. Equivalent to -xy xml2yml.ysl2

   221

   222

    h3 > -V, --version

   223

   224

    p   >>

   225

        Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of

   226

        the YML implementation and exit.

   227

        >>

   228

   229

    h3 > YML_PATH environment variable

   230

   231

    p   >>

   232

        If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬

   233

        list, then the `a href="features#including" code "include";` statement searches these paths.

   234

        If «YML_PATH» is not set, the local directory «.» is searched for files.

   235

        The system location for «.yml2» and «.ysl2» files is always searched afterwards.

   236

        >>

   237

   238

    h2 id=recommended > Recommended external tools

   239

   240

    h3 > XSLT Processor

   241

   242

    p   >>

   243

        If you want to use ¬yslt YSLT¬ with «yml2c» instead of «yml2proc», you additionally need an

   244

        ¬http://www.w3.org/TR/xslt XSLT¬ processor.

   245

        >>

   246

   247

    p > For that case, I recommend the ¬http://xmlsoft.org/XSLT/xsltproc2.html xsltproc tool¬.

   248

   249

    p > To process YSLT, just use a pipe with the «xsltproc» command:

   250

   251

    Code | % yml2c customer.ysl2 | xsltproc - customer.xml > customer.html

   252

   253

    h3 > XML Renicing Tool

   254

   255

    p   >>

   256

        Sometimes, you may want to have more human readable output with «yml2c». So an

   257

        ¬http://www.w3.org/XML/ XML¬ renicing tool can be helpful.

   258

        >>

   259

   260

    p > The ¬http://xmlstar.sourceforge.net/ XMLStarlet¬ command line tool may be of interest.

   261

   262

    p > Have a look on its «fo» command.

   263

   264

    h3 > Windows tool chain

   265

   266

    p   >>

   267

        See also the tips for a

   268

        ¬http://www.auchdieserschwachsinnmussinsinternet.de/2009-03/#s1236859037 Windows tool chain¬

   269

        for YML.

   270

        >>

   271

   272

    h1 id=downloads > Downloads

   273

   274

    p > You can here ¬http://fdik.org/yml2.tar.bz2 download the newest release of YML¬.

   275

   276

    h2 > Older versions

   277

   278

    p   >>

   279

        ¬http://fdik.org/yml-2.5.2.tar.bz2 YML 2.5.2¬

   280

        >>

   281

   282

    p   >>

   283

        ¬http://fdik.org/yml-2.5.1.tar.bz2 YML 2.5.1¬

   284

        >>

   285

   286

    p   >>

   287

        ¬http://fdik.org/yml-2.5.0.tar.bz2 YML 2.5.0¬

   288

        >>

   289

   290

    p   >>

   291

        ¬http://fdik.org/yml-2.4.3.tar.bz2 YML 2.4.3¬

   292

        >>

   293

   294

    p   >>

   295

        ¬http://fdik.org/yml-2.3.12.tar.bz2 YML 2.3.12¬

   296

        >>

   297

   298

    p   >>

   299

        ¬http://fdik.org/yml-2.3.11.tar.bz2 YML 2.3.11¬

   300

        >>

   301

   302

    p   >>

   303

        ¬http://fdik.org/yml-2.3.10.tar.bz2 YML 2.3.10¬

   304

        >>

   305

   306

    p   >>

   307

        ¬http://fdik.org/yml-2.3.8.tar.bz2 YML 2.3.8¬

   308

        >>

   309

   310

    p   >>

   311

        ¬http://fdik.org/yml-2.3.7.tar.bz2 YML 2.3.7¬

   312

        >>

   313

   314

    p   >>

   315

        ¬http://fdik.org/yml-2.3.5.tar.bz2 YML 2.3.5¬

   316

        >>

   317

   318

    p   >>

   319

        ¬http://fdik.org/yml-2.2.4.tar.bz2 YML 2.2.4¬

   320

        >>

   321

   322

    p   >>

   323

        ¬http://fdik.org/yml-2.2.3.tar.bz2 YML 2.2.3¬

   324

        >>

   325

   326

    p   >>

   327

        ¬http://fdik.org/yml-2.2.1.tar.bz2 YML 2.2.1¬

   328

        >>

   329

   330

    p   >>

   331

        ¬http://fdik.org/yml-2.2.0.tar.bz2 YML 2.2.0¬

   332

        >>

   333

   334

    p   >>

   335

        ¬http://fdik.org/yml-2.1.17.tar.bz2 YML 2.1.17¬

   336

        >>

   337

   338

    p   >>

   339

        ¬http://fdik.org/yml-2.1.14.tar.bz2 YML 2.1.14¬

   340

        >>

   341

   342

    p   >>

   343

        ¬http://fdik.org/yml-2.1.13.tar.bz2 YML 2.1.13¬

   344

        >>

   345

   346

    p   >>

   347

        ¬http://fdik.org/yml-2.1.12.tar.bz2 YML 2.1.12¬

   348

        >>

   349

   350

    p   >>

   351

        ¬http://fdik.org/yml-2.1.7.tar.bz2 YML 2.1.7¬

   352

        >>

   353

   354

    p   >>

   355

        ¬http://fdik.org/yml-2.1.6.tar.bz2 YML 2.1.6¬

   356

        >>

   357

   358

    p   >>

   359

        ¬http://fdik.org/yml-2.1.5.tar.bz2 YML 2.1.5¬

   360

        >>

   361

   362

    p   >>

   363

        ¬http://fdik.org/yml-2.1.2.tar.bz2 YML 2.1.2¬

   364

        >>

   365

   366

    p   >>

   367

        ¬http://fdik.org/yml-2.0.36.tar.bz2 YML 2.0.36¬

   368

        >>

   369

    p   >>

   370

        ¬http://fdik.org/yml-2.0.35.tar.bz2 YML 2.0.35¬

   371

        >>

   372

   373

    p > ¬http://fdik.org/yml1 To the Homepage of version 1 of YML...¬

   374

   375

    div id=bottom {

   376

        a href="yslt" "<< back to YSLT" " "

   377

        a href="#top" "^Top^" " "

   378

        a href="toolchain.en.yhtml2" "(source)"

   379

    }

   380

}