| author | Volker Birk <vb@pep-project.org> |
| Tue, 15 Dec 2020 11:29:51 +0100 | |
| changeset 68 | 26120af11afd |
| parent 44 | 4e5f42d51cc4 |
| child 76 | 8ee36a9655d7 |
| permissions | -rw-r--r-- |
| 0 | 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. |
|
|
44
4e5f42d51cc4
docs: Include files are always searched at standard location, too.
Hartmut Goebel <h.goebel@crazy-compilers.com>
parents:
0
diff
changeset
|
90 |
The system location for «.yml2» and «.ysl2» files is always searched afterwards. |
| 0 | 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. |
|
|
44
4e5f42d51cc4
docs: Include files are always searched at standard location, too.
Hartmut Goebel <h.goebel@crazy-compilers.com>
parents:
0
diff
changeset
|
235 |
The system location for «.yml2» and «.ysl2» files is always searched afterwards. |
| 0 | 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 |
} |