<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The CommonMark\CQL class</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="commonmark-parser.finish.html">CommonMark\Parser::finish</a></div>
<div class="next" style="text-align: right; float: right;"><a href="commonmark-cql.construct.html">CommonMark\CQL::__construct</a></div>
<div class="up"><a href="book.cmark.html">CommonMark</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.commonmark-cql" class="reference">
<h1 class="title">The CommonMark\CQL class</h1>
<div class="partintro"><p class="verinfo">(cmark >= 1.1.0)</p>
<div class="section" id="commonmark-cql.intro">
<h2 class="title">Introduction</h2>
<p class="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.
</p>
<p class="formalpara">
<h5 class="title">Paths:</h5>
<p class="para">
In it's most simplistic form, a CQL query combines the following paths and <em>/</em> to describe how to travel through a tree:
<ul class="simplelist">
<li class="member">firstChild</li>
<li class="member">lastChild</li>
<li class="member">previous</li>
<li class="member">next</li>
<li class="member">parent</li>
</ul>
For example, <em>/firstChild/lastChild</em> would travel to the last child node of the first child node.
</p>
</p>
<p class="formalpara">
<h5 class="title">Loops</h5>
<p class="para">
CQL can be instructed to loop, for example through the children of, or siblings to a particular node, by using the path <em>children</em>, or <em>siblings</em>. For example, <em>/firstChild/children</em> will travel to all the children of the first child node.
</p>
</p>
<p class="formalpara">
<h5 class="title">Subqueries</h5>
<p class="para">
CQL can be instructed how to travel by using a subquery like <em>[/firstChild]</em>. For example, <em>/firstChild/children[/firstChild]</em> will travel to the first child node of all the children of the first child node.
</p>
</p>
<p class="formalpara">
<h5 class="title">Loop Constraints</h5>
<p class="para">
While looping, CQL can be instructed to constrict the travelled path to nodes of particular type. For example <em>/children(BlockQuote)</em> will travel to the children of a node where the type is <em>BlockQuote</em>. The following types are recognized (case insensitively):
<ul class="simplelist">
<li class="member">BlockQuote</li>
<li class="member">List</li>
<li class="member">Item</li>
<li class="member">CodeBlock</li>
<li class="member">HtmlBlock</li>
<li class="member">CustomBlock</li>
<li class="member">Paragraph</li>
<li class="member">Heading</li>
<li class="member">ThematicBreak</li>
<li class="member">Text</li>
<li class="member">SoftBreak</li>
<li class="member">LineBreak</li>
<li class="member">Code</li>
<li class="member">HtmlInline</li>
<li class="member">CustomInline</li>
<li class="member">Emphasis</li>
<li class="member">Strong</li>
<li class="member">Link</li>
<li class="member">Image</li>
</ul>
Types may be used as a union, for example <em>/children(BlockQuote|List)</em> will travel to the children of a node where the type is <em>BlockQuote</em> or <em>List</em>. Types, or unions of types, may be also negated. For example <em>/children(~BlockQuote)</em> will travel to the children of a node where the type is not <em>BlockQuote</em>, and <em>/children(~BlockQuote|Paragraph)</em> will travel to the children of a node where the type is not <em>BlockQuote</em> or <em>Paragraph</em>
</p>
</p>
<p class="formalpara">
<h5 class="title">Path Constraints</h5>
<p class="para">
CQL can be instructed to create a loop to travel to a node of a particular type, at a particular path. For example, <em>/firstChild(BlockQuote)</em> will travel to the first child node where the type is <em>BlockQuote</em>. Note that like other loops for <em>children</em> and <em>siblings</em>, this kind of path can only be followed by a subquery.
</p>
</p>
<p class="formalpara">
<h5 class="title">Implementation Notes</h5>
<p class="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.
</p>
</p>
</div>
<div class="section" id="commonmark-cql.synopsis">
<h2 class="title">Class synopsis</h2>
<div class="classsynopsis">
<div class="ooclass"></div>
<div class="classsynopsisinfo">
<span class="ooclass">
<strong class="classname">CommonMark\CQL</strong>
</span>
{</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Constructor */</div>
<div class="constructorsynopsis dc-description">
<span class="modifier">public</span> <span class="methodname"><a href="commonmark-cql.construct.html" class="methodname">__construct</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$query</code></span>
)</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="methodname"><a href="commonmark-cql.invoke.html" class="methodname">__invoke</a></span>
( <span class="methodparam"><span class="type"><span class="type \CommonMark\Node">\CommonMark\Node</span></span> <code class="parameter">$root</code></span>
, <span class="methodparam"><span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> <code class="parameter">$handler</code></span>
)</div>
}</div>
</div>
</div>
<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="commonmark-cql.construct.html">CommonMark\CQL::__construct</a> — CQL Construction</li><li><a href="commonmark-cql.invoke.html">CommonMark\CQL::__invoke</a> — CQL Execution</li></ul>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="commonmark-parser.finish.html">CommonMark\Parser::finish</a></div>
<div class="next" style="text-align: right; float: right;"><a href="commonmark-cql.construct.html">CommonMark\CQL::__construct</a></div>
<div class="up"><a href="book.cmark.html">CommonMark</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
