>b's YML 2
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

281 lines
8.8 KiB

5 years ago
5 years ago
5 years ago
8 months ago
5 years ago
  1. include homepage.en.yhtml2
  2. page "The YML Toolchain" {
  3. h1 > The Toolchain
  4. p >>
  5. There are to possibilities to handle YML files: the YML compiler and the YML/YSLT
  6. processor.
  7. >>
  8. h2 id=compiler > The YML compiler
  9. p >>
  10. The YML ¬http://en.wikipedia.org/wiki/Compiler compiler¬ is a small
  11. ¬http://www.python.org Python script¬. It provides the
  12. ¬http://en.wikipedia.org/wiki/Command-line_interface command line¬ front end «yml2c».
  13. As default, it compiles your ¬http://en.wikipedia.org/wiki/Scripting_language script¬
  14. and outputs to ¬http://en.wikipedia.org/wiki/Stdout#Standard_output_.28stdout.29 stdout¬,
  15. that usually is the ¬http://en.wikipedia.org/wiki/Computer_terminal terminal¬.
  16. Your ¬http://en.wikipedia.org/wiki/Shell_(computing) shell¬ provides options to redirect
  17. the output into a ¬http://en.wikipedia.org/wiki/Pipeline_(Unix) pipe¬ or
  18. a ¬http://en.wikipedia.org/wiki/Computer_file file¬.
  19. >>
  20. p > So to use it, just enter «yml2c» followed by the filename of your YML script:
  21. Code | % yml2c myscript.yml2 > myscript.result
  22. p > The «yml2c» command has the following options:
  23. h3 > -h, --help
  24. p > Show a help message and exit.
  25. h3 > -C, --old-syntax
  26. p > Use the syntax of YML 2 version 1.x (compatibility mode).
  27. h3 > -D, --emit-linenumbers
  28. p > Emit line numbers into the resulting XML for debugging purposes.
  29. h3 > -E ENCODING, --encoding ENCODING
  30. p > encoding of input files (default: UTF-8)
  31. h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH
  32. p { "Precede " code > ¬features#ymlpath YML_PATH¬
  33. " by a colon separated " code "INCLUDE_PATH"; " to search for include files." }
  34. h3 > -m, --omit-empty-parm-tags
  35. p >>
  36. Does nothing (only there for compatibility with older versions of «yml2c»).
  37. >>
  38. h3 > -n NORMALIZATION, --normalization=NORMALIZATION
  39. p >>
  40. Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC)
  41. >>
  42. h3 > -o FILE, --output=FILE
  43. p > Don't output to stdout, instead place output in file «FILE».
  44. h3 > -p, --parse-only
  45. p >>
  46. ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬
  47. as text to stdout. The pyAST is the
  48. ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬
  49. of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬.
  50. >>
  51. h3 > -V, --version
  52. p >>
  53. Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of
  54. the YML implementation.
  55. >>
  56. h3 > YML_PATH environment variable
  57. p >>
  58. If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬
  59. list, then the `a href="features#including" code "include";` statement searches these paths.
  60. If «YML_PATH» is not set, the local directory «.» is searched for files.
  61. The system location for «.yml2» and «.ysl2» files is always searched afterwards.
  62. >>
  63. h2 id=processor > The YML/YSLT processor
  64. p >>
  65. If you're processing more complex tasks, say, executing an YSLT script over some
  66. YML files, the YML/YSLT processor will possible fit better to your needs.
  67. >>
  68. p >>
  69. To use it, enter «yml2proc -y» followed by the filename of your YSLT script,
  70. followed by the filenames of your YML input files:
  71. >>
  72. Code | % yml2proc -y myscript.ysl2 inputfile.yml2 > myscript.result
  73. p > The YML/YSLT processor requires the ¬http://codespeak.net/lxml/ lxml Python library¬.
  74. p > The YML/YSLT processor has the following options:
  75. h3 > -h, --help
  76. p > Show a help message and exit.
  77. h3 > -C, --old-syntax
  78. p > Use the syntax of YML 2 version 1.x (compatibility mode).
  79. h3 > -D, --emit-linenumbers
  80. p > Emit line numbers into the resulting XML for debugging purposes.
  81. h3 id=debug > --debug
  82. p >>
  83. switch on debug tracing to stderr; this enables the functionality
  84. of the ¬yslt#debug debug(msg)¬ and ¬yslt#assert assert yml:assert(test, msg)¬ YSLT functions.
  85. >>
  86. h3 > -E ENCODING, --encoding ENCODING
  87. p > encoding of input files (default: UTF-8)
  88. h3 > -I INCLUDE_PATH, --include=INCLUDE_PATH
  89. p { "Precede " code > ¬features#ymlpath YML_PATH¬
  90. " by a colon separated " code "INCLUDE_PATH"; " to search for include files." }
  91. h3 > -m, --omit-empty-parm-tags
  92. p >>
  93. Does nothing (only there for compatibility with older versions of «yml2proc»).
  94. >>
  95. h3 > -M, --empty-input-document
  96. p >>
  97. Use an empty input document for YSLT or XSLT processing
  98. >>
  99. h3 > -n NORMALIZATION, --normalization=NORMALIZATION
  100. p >>
  101. Unicode normalization (none, NFD, NFKD, NFC, NFKC, FCD, default is NFC)
  102. >>
  103. h3 > -o FILE, --output=FILE
  104. p > Don't output to stdout, instead place output in file «FILE».
  105. h3 > -p, --parse-only
  106. p >>
  107. ¬http://fdik.org/pyPEG Parse¬ only, then output ¬http://fdik.org/pyPEG/#pyAST pyAST¬
  108. as text to stdout. The pyAST is the
  109. ¬http://en.wikipedia.org/wiki/Abstract_syntax_tree Abstract Syntax Tree¬
  110. of the parsed script as ¬http://docs.python.org/library/stdtypes.html Python data structure¬.
  111. >>
  112. h3 > -e XPATH, --xpath=XPATH
  113. p > Execute XPath expression XPATH and print result
  114. p >>
  115. If you omit -y YSLTSCRIPT, then the result is printed. If you have an additional
  116. -y YSLTSCRIPT parameter, then your YSLT script is processing the result of the
  117. XPath expression only instead of processing the complete content of your input documents
  118. >>
  119. h3 > -P, --pretty
  120. p > Pretty print output adding whitespace
  121. h3 > -x, --xml
  122. p > Input documents are XML already, don't try to convert them from YML
  123. h3 > -y YSLTSCRIPT, --yslt=YSLTSCRIPT
  124. p > Execute YSLT script YSLTSCRIPT
  125. h3 > -X XSLTSCRIPT, --xslt=XSLTSCRIPT
  126. p > Execute XSLT script XSLTSCRIPT
  127. h3 > -d PARAMS, --paramdict=PARAMS
  128. p >>
  129. Call XSLT or YSLT script with dictionary PARAMS as XPath parameters. PARAMS is a Python
  130. expression which evaluates to a Python dictionary.
  131. >>
  132. p > Sample:
  133. p code > yml2proc -y myscript -d 'dict(a=3, b="element[@name=2]")'
  134. h3 > -s STRINGPARAMS, --stringparamdict=STRINGPARAMS
  135. p >>
  136. Call XSLT or YSLT script with dictionary STRINGPARAMS as string parameters. STRINGPARAMS
  137. is a Python expression which evaluates to a Python dictionary.
  138. >>
  139. p > Sample:
  140. p code > yml2proc -y myscript -s 'dict(forename="Hans", name="Meier")'
  141. h3 > -Y, --xml2yml
  142. p > Convert XML to normalized YML. Equivalent to -xy xml2yml.ysl2
  143. h3 > -V, --version
  144. p >>
  145. Show version and ¬http://en.wikipedia.org/wiki/Copyleft Copyleft¬ information of
  146. the YML implementation and exit.
  147. >>
  148. h3 > YML_PATH environment variable
  149. p >>
  150. If «YML_PATH» is set to a colon separated ¬http://en.wikipedia.org/wiki/Path_(computing) path¬
  151. list, then the `a href="features#including" code "include";` statement searches these paths.
  152. If «YML_PATH» is not set, the local directory «.» is searched for files.
  153. The system location for «.yml2» and «.ysl2» files is always searched afterwards.
  154. >>
  155. h2 id=recommended > Recommended external tools
  156. h3 > XSLT Processor
  157. p >>
  158. If you want to use ¬yslt YSLT¬ with «yml2c» instead of «yml2proc», you additionally need an
  159. ¬http://www.w3.org/TR/xslt XSLT¬ processor.
  160. >>
  161. p > For that case, I recommend the ¬http://xmlsoft.org/XSLT/xsltproc2.html xsltproc tool¬.
  162. p > To process YSLT, just use a pipe with the «xsltproc» command:
  163. Code | % yml2c customer.ysl2 | xsltproc - customer.xml > customer.html
  164. h3 > XML Renicing Tool
  165. p >>
  166. Sometimes, you may want to have more human readable output with «yml2c». So an
  167. ¬http://www.w3.org/XML/ XML¬ renicing tool can be helpful.
  168. >>
  169. p > The ¬http://xmlstar.sourceforge.net/ XMLStarlet¬ command line tool may be of interest.
  170. p > Have a look on its «fo» command.
  171. h3 > Windows tool chain
  172. p >>
  173. See also the tips for a
  174. ¬http://www.auchdieserschwachsinnmussinsinternet.de/2009-03/#s1236859037 Windows tool chain¬
  175. for YML.
  176. >>
  177. h1 id=downloads > Downloads
  178. p > You can here ¬https://gitea.pep.foundation/fdik/yml2 download the newest release of YML¬.
  179. div id=bottom {
  180. a href="yslt" "<< back to YSLT" " "
  181. a href="#top" "^Top^" " "
  182. a href="toolchain.en.yhtml2" "(source)"
  183. }
  184. }