>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.

1098 lines
31 KiB

5 years ago
5 years ago
5 years ago
5 years ago
  1. include homepage.en.yhtml2
  2. page "The Features" {
  3. h2 id=text > Text
  4. p >>
  5. To output text nodes (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax character data¬),
  6. write literals. There are integer literals, floating point literals and text literals.
  7. >>
  8. p >>
  9. Literals are written
  10. ¬http://docs.python.org/reference/lexical_analysis.html#id7 like in Python¬,
  11. that means, text literals are in single or double quotes, or multiline
  12. in triple double quotes:
  13. >>
  14. Code ||
  15. "text" 'also text' """some more text"""
  16. 42 "an integer and" 42.23 "a floating point literal"
  17. ||
  18. p >>
  19. Literals are being output by the ¬#textfunction text function¬.
  20. >>
  21. h2 id=functioncalls > Function Calls
  22. p >>
  23. The main idea of YML scripts is calling functions which then generate
  24. XML tags (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax Markup¬).
  25. Functions are generating single tags, lists or trees of tags.
  26. >>
  27. p >>
  28. To call a function, write the name of the function, followed by a comma separated list
  29. of function parameters (C like syntax) or just «attribute=value» pairs. Unlike C, you don't
  30. need to insert the parameter list into parentheses. A simple function call can be terminated
  31. by a semicolon «;» or by a period «.»
  32. >>
  33. p >>
  34. It does not matter, if you're calling your function using parentheses or brackets or without.
  35. So these statements are equal:
  36. >>
  37. Code ||
  38. foo "hello, world";
  39. foo "hello, world".
  40. foo("hello, world");
  41. foo["hello, world"];
  42. ||
  43. h3 id=subtree > Subtrees
  44. p >>
  45. If you omit the tailing semicolon, you're creating a Subtree; YML Subtrees can also be
  46. opened and closed with braces:
  47. >>
  48. Code ||
  49. foo {
  50. bar {
  51. something;
  52. }
  53. }
  54. ||
  55. p > If a Subtree only consists of one single subelement, then you may omit the braces:
  56. Code ||
  57. foo
  58. bar;
  59. ||
  60. h3 id=named > Named Parameters
  61. p >>
  62. To generate ¬http://www.w3.org/TR/2008/REC-xml-20081126/#attdecls attributes¬ by calling
  63. a function, you can use Named Parameters.
  64. >>
  65. p >>
  66. For that case, assign literals or symbols to attribute names like the following.
  67. The name of the parameter then will be used as the name of the generated attribute.
  68. An example:
  69. >>
  70. Code ||
  71. div id=sample {
  72. "this is a " a href="#sample" "link sample"
  73. }
  74. ||
  75. p > This generates:
  76. Code | <div id="sample">this is a <a href="#sample">link sample</a></div>
  77. h3 > Unnamed Parameters
  78. p >>
  79. Unnamed Parameters prepare values for predefined attributes. The following example is
  80. equivalent to the sample above:
  81. >>
  82. Code ||
  83. decl a(href);
  84. decl div(id);
  85. div "sample" {
  86. "this is a " a "#sample" "link sample"
  87. }
  88. ||
  89. p > If no predefined attribute can be allocated, the value of the parameter is added to the body.
  90. h3 > Calling with &
  91. p >>
  92. Especially if you have a ¬#defaultbody default body¬ for your function, calling with
  93. a leading «&» can be sensible: then the tag itself is omitted and only the body is being output:
  94. >>
  95. Code ||
  96. decl something { tag1; tag2; };
  97. list {
  98. &something;
  99. }
  100. ||
  101. p > results in:
  102. Code ||
  103. <list>
  104. <tag1/>
  105. <tag2/>
  106. </list>
  107. ||
  108. p >>
  109. This has the same result as ¬#alias aliasing¬ «something» to «-».
  110. >>
  111. h3 id=funclist > Function Lists
  112. p >>
  113. Function Lists are a feature of YML to simulate a more C like syntax. Let's have some
  114. examples. You can have a list of functions whereever you can have a function. Function
  115. Lists are comma separated:
  116. >>
  117. Code ||
  118. x i, j, k
  119. ||
  120. p > compiles to:
  121. Code ||
  122. <x>
  123. <i/>
  124. <j/>
  125. <k/>
  126. </x>
  127. ||
  128. h3 id=paramlists > Parameter Lists
  129. p >>
  130. A sample together with ¬#descending Descending Attributes¬:
  131. >>
  132. Code ||
  133. decl Interface @name;
  134. decl attr @type @name;
  135. decl func @type @name;
  136. Interface Icecream {
  137. attr color flavour;
  138. attr long number;
  139. func int getPrice();
  140. func void addFlavour(in color flavour, in long number);
  141. }
  142. ||
  143. p > compiles to:
  144. Code ||
  145. <Interface name="Icecream">
  146. <attr type="color" name="flavour"/>
  147. <attr type="long" name="number"/>
  148. <func type="int" name="getPrice"/>
  149. <func type="void" name="addFlavour">
  150. <parm>
  151. <in/>
  152. <color/>
  153. <flavour/>
  154. </parm>
  155. <parm>
  156. <in/>
  157. <long/>
  158. <number/>
  159. </parm>
  160. </func>
  161. </Interface>
  162. ||
  163. p >>
  164. Note the «parm» tags – they're generated by default, if you write a Parameter List
  165. behind a Function Call. That differs from calling the function with parameters –
  166. ¬#functioncalls calling¬ means using ¬#text text¬ values.
  167. >>
  168. p >>
  169. The «parm» tags are emitted, because the «_parm» function is called each time
  170. such a parameter will be emitted.
  171. >>
  172. p >>
  173. If you want to have the «_parm» function doing other things, just ¬#decl declare¬
  174. it in another way.
  175. >>
  176. h3 id=generics > Generic Declarations
  177. p >>
  178. Using Generic Declarations is just like using ¬#paramlists Parameter Lists¬ – use angle brackets
  179. instead of parentheses. For Generic Declarations, the «_generic» function is called each
  180. time such a Generic Declaration will be emitted, generating «generic» tags as the default:
  181. >>
  182. Code | max<int>(x, y)
  183. p > compiles to:
  184. Code ||
  185. <max>
  186. <generic>
  187. <int/>
  188. </generic>
  189. <parm>
  190. <x/>
  191. </parm>
  192. <parm>
  193. <y/>
  194. </parm>
  195. </max>
  196. ||
  197. h3 id=contentfc > The «content» function
  198. p >>
  199. The «content;» Function Call has a special meaning (only in a ¬#defaultbody default body¬):
  200. it does not generate a tag, but instead
  201. the tags of a supplied body in a call will be inserted at each place where the «content;»
  202. function call is existing in the ¬#defaultbody default body¬.
  203. >>
  204. h3 id=textfunction > The «text» function
  205. p >>
  206. There is a special YML function named «text». Usually, it's just ¬#alias aliased¬ to «-» (and
  207. therefore outputting nothing). The «text» function is called each time a text literal will be
  208. output.
  209. >>
  210. p >>
  211. If you ¬#decl declare¬ the «text» function, you can overload that behaviour. For example,
  212. ¬yslt YSLT¬ is declaring «text» like this:
  213. >>
  214. Code ||
  215. decl text alias xsl:text;
  216. "test"
  217. ||
  218. p > generates:
  219. Code | <xsl:text>test</xsl:text>
  220. p >>
  221. The «text» function is not called, if you give text as a value for an attribute:
  222. >>
  223. Code ||
  224. decl text alias xsl:text;
  225. a "test"
  226. ||
  227. p > generates:
  228. Code | <a>test</a>
  229. p >>
  230. But it is called using the quoting operators:
  231. >>
  232. Code ||
  233. decl text alias xsl:text;
  234. a > test
  235. ||
  236. p > generates:
  237. Code | <a><xsl:text>test</xsl:text></a>
  238. h3 id=declfunction > The «decl», «define» and «operator» functions
  239. p >>
  240. The «decl», «define» and «operator» functions are not defined, so they cannot be used
  241. accidentally by having a syntax error i.e. in a «decl» statement. If you want to use such
  242. a function, i.e. «decl()», you have to ¬#decl declare it explicitely¬:
  243. >>
  244. Code ||
  245. decl decl;
  246. decl();
  247. ||
  248. p > will result in:
  249. Code | <decl/>
  250. h2 id=decl > Declaring Functions: decl
  251. p >>
  252. As default, each Function Call generates one XML tag, which has the same name. To be exact,
  253. the XML tag has dashes in it's name where the YML function has underscores.
  254. >>
  255. p >>
  256. To define, how tags and attributes look like, which are created by a Function Call, you
  257. can use the «decl» statement.
  258. >>
  259. h3 > Trivial Declarations
  260. p > In a trivial declaration, you're just declaring the Function Name and so the XML tag name:
  261. Code | decl html, head, title, body, p, a;
  262. p > As seen in the example, multiple declarations can be done in a comma separated list.
  263. p >>
  264. Because trivial declarations are done automatically, if you're using a function for the
  265. first time, you usually don't need to declare this way.
  266. >>
  267. h3 > Specifying Unnamed Parameters
  268. p >>
  269. To specifiy Unnamed Parameters, give the parameter list comma separated in parentheses
  270. or provide one or more brackets with parameter lists in them:
  271. >>
  272. Code | decl a(href), img[src];
  273. p >>
  274. If you're using the corresponding functions a() and img() together with an unnamed parameter
  275. in a call, then these attributes are used for applying the values, respectively:
  276. >>
  277. Code | a "http://www.ccc.de" "The Club Homepage" img "logo.png";
  278. p > These Function Calls generate:
  279. Code | <a href="http://www.ccc.de">The Club Homepage</a><img src="logo.png"/>
  280. h3 id=defaultattr > Giving Default Values for parameters
  281. p >>
  282. To give default values for generating XML attributes, assign a literal to each named parameter
  283. in the declaration parentheses or brackets. Two examples, which do the same:
  284. >>
  285. Code
  286. ||
  287. decl img(src, alt="picture");
  288. decl img[src][alt="picture"];
  289. ||
  290. h3 id=alias > Aliasing: using different YML functions for the same XML tag for different tasks
  291. p >>
  292. Sometimes tags are used in different ways to do different things. For this case, you can
  293. use aliasing. Aliasing means, the YML function name and the XML tag name differ. For example:
  294. >>
  295. Code | decl a(href), target(name) alias a;
  296. p > Both defined YML functions then generate «<a />» tags – but the Unnamed Parameter differs.
  297. p >>
  298. The alias name «-» has a special meaning: it omits the tag in the output. That is especially
  299. sensible if you have a ¬#defaultbody default body¬. Then an alias to «-» has the same meaning
  300. as starting the function call with the «&» character: only the body is emitted.
  301. >>
  302. h3 id=descending > Specifying Descending Attributes
  303. p >>
  304. Maybe you want to write something like this:
  305. >>
  306. Code ||
  307. Module ERP {
  308. Interface Customer {
  309. // ...
  310. }
  311. }
  312. ||
  313. p > Without any extras, this compiles to:
  314. Code ||
  315. <Module>
  316. <ERP>
  317. <Interface>
  318. <Customer />
  319. </Interface>
  320. </ERP>
  321. </Module>
  322. ||
  323. p >>
  324. For this case, it would be practical, if «ERP» would not be interpreted as extra tag
  325. but as value for an attribute «name». This you can achive with Descending Attributes:
  326. >>
  327. Code | decl Module @name, Interface @name;
  328. p > With this declaration, the code sample above is compiling to:
  329. Code ||
  330. <Module name="ERP">
  331. <Interface name="Customer" />
  332. </Module>
  333. ||
  334. p >>
  335. Descending attributes can also be used this way:
  336. >>
  337. Code ||
  338. decl module +name;
  339. decl element +name;
  340. module Some {
  341. element {
  342. one;
  343. two;
  344. three;
  345. }
  346. element {
  347. four; five; six
  348. }
  349. }
  350. ||
  351. p >>
  352. The above generates:
  353. >>
  354. Code ||
  355. <?xml version='1.0' encoding='UTF-8'?>
  356. <module name="Some">
  357. <element name="one"/>
  358. <element name="two"/>
  359. <element name="three"/>
  360. <element name="four"/>
  361. <element name="five"/>
  362. <element name="six"/>
  363. </module>
  364. ||
  365. h3 id=descending_pointer > Specifying Descending Pointers
  366. p >>
  367. Like with descending attributes, you can use descending ¬#pointer pointers¬. Instead of preceding the
  368. name of an attribute with a «+» sign (like with ¬#descending descending attributes¬), precede it with an asterisk «*».
  369. >>
  370. p >>
  371. Like with ¬#pointer pointers¬ in general, it's a good idea to combine that with a ¬#defaultbody default body¬:
  372. >>
  373. Code ||
  374. decl f *p { some tags with *p };
  375. f value;
  376. ||
  377. p >>
  378. This generates:
  379. >>
  380. Code ||
  381. <?xml version='1.0' encoding='UTF-8'?>
  382. <f>
  383. <some>
  384. <tags>
  385. <with>value</with>
  386. </tags>
  387. </some>
  388. </f>
  389. ||
  390. h3 id=defaultbody > Supplying a Default Body
  391. p >>
  392. Additionally, you can supply a Default Body for each tag. For that case, add a YML function
  393. block in braces to your declaration:
  394. >>
  395. Code ||
  396. decl pageContent alias body {
  397. a name=top;
  398. include heading.en.yhtml2;
  399. div id=entries
  400. content;
  401. };
  402. ||
  403. p > The sample above is used for generating this homepage, for example.
  404. p > See the ¬#contentfc content function¬.
  405. h3 id=inheritance > Inheritance
  406. p >>
  407. Declarations can ¬http://en.wikipedia.org/wiki/Inheritance_(computer_science) inherit¬
  408. information from previous declarations. For that case, there is the
  409. possibility to use an «is» clause to give a function name to inherit from.
  410. >>
  411. p > The following is an example from the YSLT specification:
  412. Code ||
  413. decl stylesheet(version="1.0", xmlns:xsl="http://www.w3.org/1999/XSL/Transform");
  414. decl estylesheet is stylesheet (
  415. xmlns:exsl='http://exslt.org/common',
  416. xmlns:math='http://exslt.org/math',
  417. xmlns:func='http://exslt.org/functions',
  418. xmlns:str='http://exslt.org/strings',
  419. xmlns:dyn='http://exslt.org/dynamic',
  420. xmlns:set='http://exslt.org/sets',
  421. extension-element-prefixes='exsl func str dyn set math'
  422. );
  423. decl textstylesheet is estylesheet {
  424. output "text";
  425. const "space", !"'" + " " * 200 + "'"!;
  426. param "autoindent", 4;
  427. content;
  428. }, tstylesheet is textstylesheet;
  429. ||
  430. p >>
  431. Here «estylesheet» inherits the tag name and the Default Values from «stylesheet»,
  432. while «textstylesheet» inherits all from «estylesheet» again. «estylesheet» then adds
  433. a Default Body, and «tstylesheet» does exactly the same as «textstylesheet».
  434. >>
  435. p > All of these YML functions output «stylesheet» XML tags, but with different defaults.
  436. h3 id=shapes > Shapes
  437. p >>
  438. Shapes are comparable to ¬#inheritance inheritance¬. Declaring a shape inherits
  439. every property beside the name.
  440. >>
  441. Code ||
  442. decl coords(x=0, y=0);
  443. decl point <coords> (name);
  444. point "origin";
  445. ||
  446. p > compiles to:
  447. Code | <point y="0" x="0" name="origin"/>
  448. p >>
  449. It's possible to have more than one shape, too. Multiple shapes
  450. are patching each other in the sequence they're listed:
  451. >>
  452. Code ||
  453. decl coords(x=0, y=0);
  454. decl named +name;
  455. decl point <coords, named>;
  456. point origin;
  457. ||
  458. p > compiles to:
  459. Code | <point y="0" x="0" name="origin" />
  460. h3 > Namespaces
  461. p >>
  462. ¬http://www.w3.org/TR/xml-names/ XML namespaces¬ can be used just by providing an
  463. «alias» clause. Additionally, they can be used by an «in» clause; these two lines
  464. are equivalent:
  465. >>
  466. Code ||
  467. decl apply(select) alias xsl:apply-templates;
  468. in xsl decl apply(select) alias apply-templates;
  469. ||
  470. p > «in» clauses also can be used with a block of declarations in braces:
  471. Code ||
  472. in xsl {
  473. decl template(match);
  474. decl apply(select) alias apply-templates;
  475. decl function(name) alias template;
  476. decl call(name) alias call-template;
  477. }
  478. ||
  479. h3 id=pointer > Pointers
  480. p >>
  481. In some situations, it is good to have information in a Function Call, which then
  482. changes the way XML tags are generated. For this case, there are Pointers.
  483. >>
  484. p >>
  485. The name should not mislead you; I took it because I chose the «*» symbol to declare them,
  486. and that is the meaning of this symbol in the programming language C. The concept behind
  487. is very easy.
  488. >>
  489. p >>
  490. For example, it could be a good idea to generate a small HTML document containing some
  491. content. For this case, the title of the page is a good case for using pointers:
  492. >>
  493. Code ||
  494. decl page(*title) alias html {
  495. head {
  496. title *title;
  497. }
  498. body {
  499. h1 *title;
  500. content;
  501. }
  502. };
  503. ||
  504. p >>
  505. In the example above, calling «page('My Page') { p 'hello, world'; }» will result in
  506. this XML output:
  507. >>
  508. Code ||
  509. <html>
  510. <head>
  511. <title>My Page</title>
  512. </head>
  513. <body>
  514. <h1>My Page</h1>
  515. <p>hello, world</p>
  516. </body>
  517. </html>
  518. ||
  519. p >>
  520. Pointers can be referenced in any place in the Default Body of a «decl» statement, also for
  521. generating extra tags. Then the value for a Pointer will be the tag name.
  522. >>
  523. p >>
  524. Additionally, you can insert the value of a pointer as text by calling it with two leading
  525. asterisks, i.e. if the pointer is defined as «*x», you can insert its value as text using: «**x».
  526. >>
  527. h4 id=pwt > Pointers without tags
  528. p >>
  529. To give a literal a name, you can define pointers to literals.
  530. >>
  531. Code ||
  532. define *answer = 42;
  533. something *answer;
  534. ||
  535. p > will compile to:
  536. Code | <something>42</something>
  537. p >>
  538. The «define» keyword as well as the asterisk «*» can be omitted. So this is
  539. equivalent to the statements above:
  540. >>
  541. Code ||
  542. answer = 42;
  543. something *answer;
  544. ||
  545. h4 > The pointer *_debug_trace
  546. p >>
  547. If you're calling ¬toolchain#processor yml2proc¬ with ¬toolchain#debug --debug¬, then this pointer is filled
  548. with tracing info text, otherwise it's an empty string.
  549. >>
  550. h3 id=macros, "Macros";
  551. p >>
  552. Macros are a way to generate values for attributes with variable content. Macros can be set
  553. like any other parameters; they're used for a text search & replace in the values of attributes
  554. when attributes are generated.
  555. >>
  556. p >>
  557. Parameters, which represent macros, are determined with a preceding «%» sign. They're
  558. accounted for before any other parameter is accounted for in a function call, even if
  559. they were defined after other parameters.
  560. >>
  561. p > An example:
  562. Code ||
  563. decl foo(%macro, myAttr="something %macro for testing");
  564. testing
  565. foo "nice";
  566. ||
  567. p > This generates:
  568. Code ||
  569. <testing>
  570. <foo myAttr="something nice for testing"/>
  571. </testing>
  572. ||
  573. h3 id=nullfunction > The Null Function
  574. p >>
  575. The function with the name «_» (underscore) is called Null Function. If you define this
  576. function, then you're switching off the default behaviour, that trivial declares are done
  577. automatically.
  578. >>
  579. p >>
  580. Instead, unknown functions now call the Null Function. This can be very sensible together
  581. with ¬#descending Descending Attributes¬:
  582. >>
  583. Code ||
  584. decl _ +type +name alias func;
  585. decl interface +name;
  586. interface Testcase {
  587. void f(in string input);
  588. long getOptions();
  589. }
  590. ||
  591. p > compiles to:
  592. Code ||
  593. <interface name="Testcase">
  594. <func type="void" name="f">
  595. <parm>
  596. <in/>
  597. <string/>
  598. <input/>
  599. </parm>
  600. </func>
  601. <func type="long" name="getOptions"/>
  602. </interface>
  603. ||
  604. h2 id=quoting > Quoting Operators
  605. p > Five different quoting operators implement different functionality:
  606. h3 id=quote > Quote >
  607. p > The «>» operator quotes into text nodes, doing XML escaping of text. An example:
  608. Code | > this text will be put into a text node and these angle brackets <> will be quoted
  609. p > Additionally, it can be used to implement an indention system, see ¬yslt YSLT¬ below.
  610. p >>
  611. Then an integer literal can be the first part of the operator; it gives the indention
  612. level. For example:
  613. >>
  614. Code ||
  615. 0> this text is indented to the actual level and then output,
  616. > followed by this text.\\n
  617. 1> this text is indented one indention level\\n
  618. 2> two levels\\n
  619. 1> one level again\\n
  620. ||
  621. p >>
  622. Quote text is being output by the ¬#textfunction «text» function¬.
  623. >>
  624. h3 id=blockquote > Block Quote >>
  625. p {
  626. > To include more lines of text into a single quoted area, use double «>>». The lines
  627. > are concatenated together then. An example:
  628. }
  629. Code ||
  630. p >>
  631. This generates a text paragraph for HTML. All this text, which you can find in
  632. these lines, is being concatenated together to one single text node, and then put
  633. into the body of the <p> ... </p> tag.
  634. >>
  635. ||
  636. p >>
  637. Block quote text is being output by the ¬#textfunction «text» function¬.
  638. >>
  639. h3 > Line Quote |
  640. p > The «|» operator does the same as the «>» operator, adding a newline character to the text node.
  641. p > Additionally, it can be used to implement an indention system, see ¬yslt YSLT¬ below.
  642. p > Then it's used together with additional «>» symbols showing the grade of indention:
  643. Code ||
  644. | not indented
  645. |> single indent
  646. |>> double indent
  647. (...)
  648. ||
  649. p >>
  650. Line quote text is being output by the ¬#textfunction «text» function¬.
  651. >>
  652. h3 > Block Line Quote ||
  653. p >>
  654. The «||» operator opens and closes a block of lines, which then are handled like if each of
  655. them would be preceeded with a Line Operator «|».
  656. >>
  657. p > Sample:
  658. Code {
  659. | ||
  660. ||
  661. this is code being quoted through
  662. this is the second line
  663. ||
  664. | ||
  665. }
  666. p > is equivalent to:
  667. Code {
  668. ||
  669. | this is code being quoted through
  670. | this is the second line
  671. ||
  672. }
  673. p >>
  674. Block line quote text is being output by the ¬#textfunction «text» function¬.
  675. >>
  676. h3 > Inserting Commands
  677. p >>
  678. Just like with a ¬http://en.wikipedia.org/wiki/Shell_(computing)#Unix_shells Unix shell¬,
  679. you can insert statements into text by using backticks:
  680. >>
  681. Code ] | Click `a href="http://fdik.org/yml/" "this link"`, please!
  682. p {
  683. >>
  684. Being in a Block Line Quote «||», you additionally can use the Line Command operator
  685. (two backquotes,
  686. >>
  687. ] ``).
  688. }
  689. p > This is very interesting to have in YSLT, for example:
  690. Code {
  691. | ||
  692. | some code
  693. ] ``
  694. > apply "myTemplate";\n
  695. | some other code
  696. | ||
  697. }
  698. h3 id=userop > User defined in-text Operators
  699. p > You can define short cuts for inserting commands into text by defining operators.
  700. p >>
  701. Therefore, you need a ¬http://en.wikipedia.org/wiki/Regular_expression regular expression¬
  702. for matching text and YML text for replacing with. Here an example, how this is used by YSLT:
  703. >>
  704. Code ] define operator "«(.*?)»" as value "%1";
  705. p > The RegEx have ¬http://docs.python.org/library/re.html Python syntax¬.
  706. p >>
  707. In this example all matches to the RegEx will be replaced by the YML text in the «as» clause.
  708. The text of the first group in the RegEx will replace the «%1» in the resulting YML text. You
  709. can do that for more than one group – just use «%2» for the second group, «%3» for the third
  710. one and so on.
  711. >>
  712. p > The «define» keyword can be omitted.
  713. h3 id=quotethrough > Quote Through ]
  714. p >>
  715. The ¬http://en.wikipedia.org/wiki/Apple_II_series Apple ][¬ prompt operator just quotes
  716. through directly into XML what it gets.
  717. >>
  718. p >>
  719. If the first character of a command is a «<», then quote through is applied
  720. automatically.
  721. >>
  722. p > This is the preferred way to output XML tags directly in YML:
  723. Code ||
  724. <output me="directly" />
  725. ] <!--
  726. ] add some comment, which then appears in XML
  727. ] -->
  728. ||
  729. h2 id=including > Including YML files
  730. p >>
  731. You can include a second YML script file into an existing YML script file
  732. at any place using one of the following:
  733. >>
  734. Code ||
  735. include something.yml2
  736. include "something else.yml2"
  737. include 'anything addionally.yml2'
  738. ||
  739. a name="ymlpath";
  740. p >>
  741. If you're not starting the filename with '.' or '/' as in the example above, then
  742. if the «YML_PATH» environment variable is set to a colon separated list of directories,
  743. these directories are being searched for the given filename. Otherwise, the local
  744. directory is searched.
  745. The system location for «.yml2» and «.ysl2» files is always searched afterwards.
  746. >>
  747. p >>
  748. Filename ¬http://en.wikipedia.org/wiki/Glob_(programming) globbing¬ using «*» and «?»
  749. placeholders is supported to include more than one file at a time:
  750. >>
  751. Code | include part*.yml2
  752. p >>
  753. Filename globbing also can be used reverted; that means, the files are included in reverse
  754. order:
  755. >>
  756. Code | include reverse part*.yml2
  757. p > If there are the files part1.yml2, part2.yml2 and part3.yml2, part3.yml2 is included first now.
  758. p > To include plain text as text nodes, you can use:
  759. Code | include text some.txt
  760. p > To include ready made XML, use:
  761. Code | include xml some.xml
  762. p > If there is a file mask or a filename in a pointer you can include indirectly:
  763. Code ||
  764. declare files = "*.yml2"
  765. include from *files
  766. ||
  767. h2 id=python > Escaping into Python – the Escape Operator !
  768. p > You can insert a Python command at any place by using the «!» operator:
  769. Code | !class X(str): pass
  770. h3 > Python script Operator !!
  771. p > You can use the double «!!» to include more than one line of Python code:
  772. Code ||
  773. !!
  774. def fak(n):
  775. if n == 0:
  776. return 1
  777. else:
  778. return n * fak(n - 1)
  779. def getName(id):
  780. return SQL("select name from customers where id='"+str(id)+"';")[0]
  781. !!
  782. ||
  783. h3 > Python generated parameters in Function Calls
  784. p >>
  785. You may use Python expressions to generate names and/or values in Function Calls.
  786. To do so, embed the Python expression in «! ... !»:
  787. >>
  788. Code ||
  789. f x=!fak(5)!;
  790. customer name=!getName(42)!;
  791. tag !getNextAttributeName()!=42;
  792. ||
  793. h3 > Python generated Function Calls
  794. p >>
  795. You can generate text with a Python expression, which represents an YML Function Call.
  796. The resulting YML function is then executed. Also here, embed the Python expression
  797. in «! ... !»:
  798. >>
  799. Code | !getTagName() + " " + getAttrib() + "='" + getValue() + "'"!
  800. h3 > Using Pointers as values in Python function calls
  801. p >>
  802. Sometimes it is useful to call a generating Python function using information of a
  803. YML Function Call. For that case, there is the «python» statement in YML. You can
  804. call there a single Python function using YML Pointers as parameters.
  805. >>
  806. p > This is used in the YSLT specification, for example:
  807. Code ||
  808. decl apply(select, *indent=1) alias apply-templates {
  809. python withIndent(*indent);
  810. content;
  811. };
  812. ||
  813. h2 id=comments > Comments //, /* */
  814. p > Comments are written like in Java or C++:
  815. Code ||
  816. // this is a comment
  817. something() { // this is a comment after a tag
  818. /* this is some comment, too */
  819. ||
  820. p > After Quoting Operators, comments are not possible. Instead, they're quoted through:
  821. Code ||
  822. // the following line you'll find in the output document
  823. > this text is being output // and this too
  824. ||
  825. div id=bottom {
  826. > ¬programming << Using YML 2¬
  827. > ¬#top ^Top^¬
  828. > ¬yslt >> show me YSLT¬
  829. > ¬features.en.yhtml2 (source)¬
  830. }
  831. }