XML-XSH
view release on metacpan or search on metacpan
src/xsh_grammar.xml view on Meta::CPAN
</see-also>
</documentation>
</rule>
<rule id="var_command" type="command" name="variables" inline="yes">
<aliases>
<alias name="vars"/>
<alias name="var"/>
</aliases>
<production>
<selfref/>
<action>[\&XML::XSH::Functions::variables]</action>
</production>
<documentation sections="Information">
<usage>variables</usage>
<shortdesc>display a list of defined variables</shortdesc>
<description>
<para>List all defined variables and their values.</para>
</description>
<see-also>
<ruleref ref="files_command"/>
<ruleref ref="list_defs_command"/>
</see-also>
</documentation>
</rule>
<rule id="copy_command" type="command" name="copy" inline="yes">
<aliases>
<alias name="cp"/>
</aliases>
<production>
<selfref/>
<directive type="commit"/>
<ruleref ref="xpath"/>
<ruleref ref="loc"/>
<ruleref ref="xpath"/>
<action>[\&XML::XSH::Functions::copy,@item[3,5,4]]</action>
</production>
<documentation sections="Manipulation">
<usage>copy <xref linkend="xpath"/> <xref linkend="loc"/> <xref linkend="xpath"/></usage>
<shortdesc>copy nodes (in the one-to-one mode)</shortdesc>
<description>
<para>
Copies nodes matching the first <xref linkend="xpath"/> to
the destinations determined by the <xref linkend="loc"/> directive relative to the second <xref linkend="xpath"/>. If more than one node matches the first
<xref linkend="xpath"/> than it is copied to the position
relative to the corresponding node matched by the second
<xref linkend="xpath"/> according to the order in which are
nodes matched. Thus, the n'th node matching the first <xref linkend="xpath"/> is copied to the location relative to the
n'th node matching the second <xref linkend="xpath"/>.
</para>
<para>The
possible values for <xref linkend="loc"/> are: after,
before, into, replace and cause copying the source nodes
after, before, into (as the last child-node). the
destination nodes. If replace <xref linkend="loc"/> is
used, the source node is copied before the destination node
and the destination node is removed.
</para>
<para>
Some kind of type conversion is used when the types of the
source and destination nodes are not equal. Thus, text,
cdata, comment or processing instruction node data prepend,
append or replace value of a destination attribute when
copied before,after/into or instead (replace) an attribute,
and vice versa.
</para>
<para>
Attributes may be copied after, before or into some other
attribute to append, prepend or replace the destination
attribute value. They may also replace the destination
attribute completely (both its name and value).
To copy an attribute from one element to another,
simply copy the attribute node into the destination element.
</para>
<para>
Elements may be copied into other elements (which results in
appending the child-list of the destination element), or
before, after or instead (replace) other nodes of any type
except attributes.
</para>
<example>
<title>Replace living-thing elements in the document b with
the coresponding creature elements of the document a.</title>
<code>xsh> <userinput>copy a://creature replace b://living-thing</userinput></code>
</example>
</description>
</documentation>
</rule>
<rule id="xcopy_command" type="command" name="xcopy" inline="yes">
<aliases>
<alias name="xcp"/>
</aliases>
<production>
<selfref/>
<directive type="commit"/>
<ruleref ref="xpath"/>
<ruleref ref="loc"/>
<ruleref ref="xpath"/>
<action>[\&XML::XSH::Functions::copy,@item[3,5,4],1]</action>
</production>
<documentation sections="Manipulation">
<usage>xcopy <xref linkend="xpath"/> <xref linkend="loc"/> <xref linkend="xpath"/></usage>
<shortdesc>copy nodes (in the all-to-every mode)</shortdesc>
<description>
<para>
xcopy is similar to <xref linkend="copy_command"/>, but copies *all* nodes matching
the first <xref linkend="xpath"/> to *all* destinations determined by the
<xref linkend="loc"/> directive relative to the
second <xref linkend="xpath"/>. See <xref
linkend="copy_command"/>
for detailed description of <literal>xcopy</literal> arguments.
</para>
<example>
<title>Copy all middle-earth creatures within the document a
into every world of the document b.</title>
<code>xsh> <userinput>xcopy a:/middle-earth/creature into b://world</userinput></code>
</example>
</description>
</documentation>
</rule>
<rule id="cd_command" type="command" name="lcd" inline="yes">
<aliases>
src/xsh_grammar.xml view on Meta::CPAN
</production>
<documentation sections="Manipulation">
<usage>insert <xref linkend="nodetype"/> <xref
linkend="expression"/> [namespace <xref
linkend="expression"/>] <xref linkend="loc"/> <xref linkend="xpath"/>
</usage>
<shortdesc>create a node in on a given target location</shortdesc>
<description>
<para>
Works just like xadd, except that the new node is attached
only the first node matched.
</para>
</description>
<see-also>
<ruleref ref="xinsert_command"/>
<ruleref ref="move_command"/>
<ruleref ref="xmove_command"/>
</see-also>
</documentation>
</rule>
<rule id="xinsert_command" type="command" name="xinsert" inline="yes">
<aliases>
<alias name="xadd"/>
</aliases>
<production>
<selfref/>
<directive type="commit"/>
<ruleref ref="nodetype"/>
<ruleref ref="expression"/>
<ruleref ref="namespace" rep="?"/>
<ruleref ref="loc"/>
<ruleref ref="xpath"/>
<action>[\&XML::XSH::Functions::insert,@item[3,4,7,6],$item[5][0],1]</action>
</production>
<documentation sections="Manipulation">
<usage>xinsert <xref linkend="nodetype"/> <xref
linkend="expression"/> [namespace <xref
linkend="expression"/>] <xref linkend="loc"/> <xref linkend="xpath"/>
</usage>
<shortdesc>create nodes on all target locations</shortdesc>
<description>
<para>
Use the <xref linkend="expression"/> to create a new node of a given
<xref linkend="nodetype"/> in the <xref linkend="loc"/> relative to the given
<xref linkend="xpath"/>.
</para>
<para>
For element nodes, the format of the <xref linkend="expression"/> should look like
"<element-name att-name='attvalue' ...>". The
<literal><</literal> and <literal>></literal>
characters are optional. If no attributes are used, the
expression may simply consist the element name. Note,
that in the first case, the quotes are required since
the expression contains spaces.
</para>
<para>
Attribute nodes use the following syntax:
"att-name='attvalue' [...]".
</para>
<para>
For the other types of nodes (text, cdata, comments) the
expression should contain the node's literal content. Again,
it is necessary to quote all whitespace and special
characters as in any expression argument.
</para>
<para>
The <xref linkend="loc"/> argument should be one of:
<literal>after</literal>, <literal>before</literal>,
<literal>into</literal>,
<literal>replace</literal>, <literal>append</literal>
or <literal>prepend</literal>. See documentation
of the <xref linkend="loc"/> argument type for more detail.
</para>
<para>
The namespace <xref linkend="expression"/> is only valid for
elements and attributes and must evaluate to the namespace
URI. In that case, the element or attribute name must have a
prefix. The created node is associated with a given
namespace.
</para>
<example>
<title>Append a new Hobbit element to the list of
middle-earth creatures and name him Bilbo.</title>
<code>
xsh> <userinput>xadd element "<creature race='hobbit' manner='good'>" \
<tab/>into /middle-earth/creatures</userinput>
xsh> <userinput>xadd attribute "name='Bilbo'" \
<tab/>into /middle-earth/creatures/creature[@race='hobbit'][last()]</userinput>
</code>
</example>
</description>
<see-also>
<ruleref ref="insert_command"/>
<ruleref ref="move_command"/>
<ruleref ref="xmove_command"/>
</see-also>
</documentation>
</rule>
<rule id="nodetype" name="node-type" type="argtype">
<production>
<regexp>element|attribute|attributes|text|cdata|pi|comment|chunk|entity_reference</regexp>
</production>
<documentation sections="Argtypes Manipulation">
<title>Node-type argument type</title>
<shortdesc>node type specification (such as element, attribute, etc.)</shortdesc>
<description>
<para>
One of: element, attribute, text, cdata, comment, chunk
and (EXPERIMENTALLY!) entity_reference. A
chunk is a character string which forms a well-balanced
peace of XML.
</para>
<example>
<code>
add element hobbit into //middle-earth/creatures;
add attribute 'name="Bilbo"' into //middle-earth/creatures/hobbit[last()];
add chunk '<hobbit name="Frodo">A small guy from <place>Shire</place>.</hobbit>'
<tab/>into //middle-earth/creatures;
</code>
</example>
</description>
</documentation>
</rule>
<rule id="namespace">
<production>
<regexp>namespace\s</regexp>
<ruleref ref="expression"/>
<action>$item[2]</action>
</production>
</rule>
<rule id="loc" type="argtype" name="location">
<production><regexp>after\s</regexp>
<action>"after"</action>
</production>
<production><regexp>before\s</regexp>
<action>"before"</action>
</production>
<production><regexp>(in)?to\s</regexp>
<action>"into"</action>
</production>
<production><regexp>(append(ing)?|as\s+(a\s+)child(\s+of)?)\s</regexp>
<action>"append"</action>
</production>
<production><regexp>(prepend(ing)?|(as\s+)(the\s+)first(\s+child(\s+of)?)?)\s</regexp>
<action>"prepend"</action>
</production>
<production><regexp>(replace|instead( of)?)\s</regexp>
<action>"replace"</action>
</production>
<documentation sections="Argtypes Manipulation">
<title>Location argument type</title>
<shortdesc>relative destination specification (such as after, before, etc.)</shortdesc>
<description>
<para>One of:
<literal>after</literal>,
<literal>before</literal>,
<literal>into</literal>,
<literal>append</literal>,
<literal>prepend</literal>,
<literal>replace</literal>.
</para>
<para>
NOTE: XSH 1.6 introduces two new values for location
argument:
<literal>append</literal> and <literal>prepend</literal>
and slighlty changes behavior of
<literal>after</literal> and <literal>before</literal>!
</para>
<para>
This argument is required by all commands that insert
nodes to a document in some way to a destination described
by an XPath expression. The meaning of the values listed
above is supposed be obvious in most cases, however the
exact semantics for location argument values depends on
types of both the source node and the target node.
</para>
<para>
<literal>after/before</literal> place the node right
after/before the destination node, except for when the
destination node is a document node or one of the source
nodes is an attribute: If the destination node is a
document node, the source node is attached to the
end/beginning of the document (remember: there is no
"after/before a document"). If both the source and
destination nodes are attributes, then the source node is
simply attached to the element containing the destination
node (remember: there is no order on attribute nodes). If
the destination node is an attribute but the source node
is of a different type, then the textual content of the
source node is appended to the value of the destination
attribute (i.e. in this case after/before act just as
append/prepend).
</para>
<para>
<literal>append/prepend</literal> appends/prepends the
source node to the destination node. If the destination
node can contain other nodes (i.e. it is an element or a
document node) then the entire source node is attached to
it. In case of other destination node types, the textual
content of the source node is appended/prepended to the
content of the destination node.
</para>
<para>
<literal>into</literal> can also be used to place
the source node to the end of an element (in the same way
as <literal>append</literal>), to attach an attribute
to an element, or, if the destination node is a text node,
cdata section, processing-instruction, attribute or comment,
to replace its textual content with the textual content of
the source node.
</para>
<para>
<literal>replace</literal> replaces the entire destination
node with the source node except for the case when the
destination node is an attribute and the source node is
not. In such a case only the value of the destination
attribute is replaced with the textual content of the
source node. Note also that document node can never be
replaced.
</para>
</description>
</documentation>
</rule>
<rule id="move_command" type="command" name="move" inline="yes">
<aliases>
<alias name="mv"/>
</aliases>
<production>
<selfref/>
<directive type="commit"/>
<ruleref ref="xpath"/>
<ruleref ref="loc"/>
<ruleref ref="xpath"/>
<action>[\&XML::XSH::Functions::move,@item[3,5,4]]</action>
</production>
<documentation sections="Manipulation">
<usage>move <xref linkend="xpath"/> <xref linkend="loc"/> <xref linkend="xpath"/></usage>
<shortdesc>move nodes (in the one-to-one mode)</shortdesc>
<description>
<para><literal>move</literal> command acts exactly like
<xref linkend="copy_command"/>, except that it
<emphasis>removes</emphasis> the source nodes after a
succesfull copy. Remember that the moved nodes are
actually <emphasis>different nodes</emphasis> from the
original ones (which may not be obvious when moving
nodes within a single document into locations that do
not require type conversion). So, after the move, the
original nodes do not exist neither in the document
itself nor any nodelist variable.
</para>
<para>
See <xref linkend="copy_command"/> for more details on how
the copies of the moved nodes are created.
</para>
</description>
<see-also>
<ruleref ref="copy_command"/>
<ruleref ref="xmove_command"/>
<ruleref ref="insert_command"/>
<ruleref ref="xinsert_command"/>
</see-also>
</documentation>
</rule>
<rule id="xmove_command" type="command" name="xmove" inline="yes">
<aliases>
<alias name="xmv"/>
</aliases>
<production>
( run in 1.248 second using v1.01-cache-2.11-cpan-39bf76dae61 )