1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<reference xml:id="class.commonmark-cql" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The CommonMark\CQL class</title>
<titleabbrev>CommonMark\CQL</titleabbrev>
<partintro>
<!-- {{{ CommonMark\Parser intro -->
<section xml:id="commonmark-cql.intro">
&reftitle.intro;
<para>
CommonMark Query Language is a DSL for describing how to travel through a CommonMark Node tree implemented as a parser and compiler for a small set of instructions, and a virtual machine for executing those instructions.
</para>
<formalpara>
<title>Paths:</title>
<para>
In it's most simplistic form, a CQL query combines the following paths and <literal>/</literal> to describe how to travel through a tree:
<simplelist>
<member>firstChild</member>
<member>lastChild</member>
<member>previous</member>
<member>next</member>
<member>parent</member>
</simplelist>
For example, <literal>/firstChild/lastChild</literal> would travel to the last child node of the first child node.
</para>
</formalpara>
<formalpara>
<title>Loops</title>
<para>
CQL can be instructed to loop, for example through the children of, or siblings to a particular node, by using the path <literal>children</literal>, or <literal>siblings</literal>. For example, <literal>/firstChild/children</literal> will travel to all the children of the first child node.
</para>
</formalpara>
<formalpara>
<title>Subqueries</title>
<para>
CQL can be instructed how to travel by using a subquery like <literal>[/firstChild]</literal>. For example, <literal>/firstChild/children[/firstChild]</literal> will travel to the first child node of all the children of the first child node.
</para>
</formalpara>
<formalpara>
<title>Loop Constraints</title>
<para>
While looping, CQL can be instructed to constrict the travelled path to nodes of particular type. For example <literal>/children(BlockQuote)</literal> will travel to the children of a node where the type is <literal>BlockQuote</literal>. The following types are recognized (case insensitively):
<simplelist>
<member>BlockQuote</member>
<member>List</member>
<member>Item</member>
<member>CodeBlock</member>
<member>HtmlBlock</member>
<member>CustomBlock</member>
<member>Paragraph</member>
<member>Heading</member>
<member>ThematicBreak</member>
<member>Text</member>
<member>SoftBreak</member>
<member>LineBreak</member>
<member>Code</member>
<member>HtmlInline</member>
<member>CustomInline</member>
<member>Emphasis</member>
<member>Strong</member>
<member>Link</member>
<member>Image</member>
</simplelist>
Types may be used as a union, for example <literal>/children(BlockQuote|List)</literal> will travel to the children of a node where the type is <literal>BlockQuote</literal> or <literal>List</literal>. Types, or unions of types, may be also negated. For example <literal>/children(~BlockQuote)</literal> will travel to the children of a node where the type is not <literal>BlockQuote</literal>, and <literal>/children(~BlockQuote|Paragraph)</literal> will travel to the children of a node where the type is not <literal>BlockQuote</literal> or <literal>Paragraph</literal>
</para>
</formalpara>
<formalpara>
<title>Path Constraints</title>
<para>
CQL can be instructed to create a loop to travel to a node of a particular type, at a particular path. For example, <literal>/firstChild(BlockQuote)</literal> will travel to the first child node where the type is <literal>BlockQuote</literal>. Note that like other loops for <literal>children</literal> and <literal>siblings</literal>, this kind of path can only be followed by a subquery.
</para>
</formalpara>
<formalpara>
<title>Implementation Notes</title>
<para>
While CQL has been implemented as part of the PHP CommonMark extension, it stands separately from PHP and does not use PHP's virtual machine or internal representation of values.
</para>
</formalpara>
</section>
<!-- }}} -->
<section xml:id="commonmark-cql.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>CommonMark\CQL</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>CommonMark\CQL</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Constructor;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('commonmark-cql.construct')/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])" />
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.commonmark-cql')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
</classsynopsis>
<!-- }}} -->
</section>
</partintro>
&reference.cmark.commonmark.cql.construct;
&reference.cmark.commonmark.cql.invoke;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
