view release on metacpan or  search on metacpan

lib/XML/XSH/Help.pm  view on Meta::CPAN

END

$HELP{'transform'}=$HELP{'xslt'};
$HELP{'xsl'}=$HELP{'xslt'};
$HELP{'xsltproc'}=$HELP{'xslt'};
$HELP{'process'}=$HELP{'xslt'};

$HELP{'documents'}=[<<'END'];
usage:       files
             
aliases:     files docs

description:
	     List open files and their identifiers.

see also:     open close

END

$HELP{'files'}=$HELP{'documents'};
$HELP{'docs'}=$HELP{'documents'};

$HELP{'variables'}=[<<'END'];
usage:       variables
             
aliases:     vars var

description:
	     List all defined variables and their values.

see also:     documents defs

END

$HELP{'vars'}=$HELP{'variables'};
$HELP{'var'}=$HELP{'variables'};

$HELP{'copy'}=[<<'END'];
usage:       copy <xpath> <location> <xpath>
             
aliases:     cp

description:
	     Copies nodes matching the first <xpath> to the destinations
	     determined by the <location> directive relative to the second
	     <xpath>. If more than one node matches the first <xpath> than
	     it is copied to the position relative to the corresponding
	     node matched by the second <xpath> according to the order in
	     which are nodes matched. Thus, the n'th node matching the
	     first <xpath> is copied to the location relative to the n'th
	     node matching the second <xpath>.

	     The possible values for <location> are: after, before, into,
	     replace and cause copying the source nodes after, before, into
	     (as the last child-node). the destination nodes. If replace
	     <location> is used, the source node is copied before the
	     destination node and the destination node is removed.

	     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.

	     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.

	     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.

Example:     Replace living-thing elements in the document b with the
	     coresponding creature elements of the document a.

             xsh> copy a://creature replace b://living-thing

END

$HELP{'cp'}=$HELP{'copy'};

$HELP{'xcopy'}=[<<'END'];
usage:       xcopy <xpath> <location> <xpath>
             
aliases:     xcp

description:
	     xcopy is similar to <copy>, but copies *all* nodes matching
	     the first <xpath> to *all* destinations determined by the
	     <location> directive relative to the second <xpath>. See
	     <copy> for detailed description of `xcopy' arguments.

Example:     Copy all middle-earth creatures within the document a into
	     every world of the document b.

             xsh> xcopy a:/middle-earth/creature into b://world

END

$HELP{'xcp'}=$HELP{'xcopy'};

$HELP{'lcd'}=[<<'END'];
usage:       lcd <expression>
             
aliases:     chdir

description:
	     Changes the filesystem working directory to <expression>, if
	     possible. If <expression> is omitted, changes to the directory
	     specified in HOME environment variable, if set; if not,
	     changes to the directory specified by LOGDIR environment
	     variable.

END

$HELP{'chdir'}=$HELP{'lcd'};

$HELP{'insert'}=[<<'END'];
usage:       insert <node-type> <expression> [namespace <expression>] <location> <xpath>
             
aliases:     add

description:
	     Works just like xadd, except that the new node is attached
	     only the first node matched.

see also:     xinsert move xmove

END

$HELP{'add'}=$HELP{'insert'};

$HELP{'xinsert'}=[<<'END'];
usage:       xinsert <node-type> <expression> [namespace <expression>] <location> <xpath>
             
aliases:     xadd

description:
	     Use the <expression> to create a new node of a given
	     <node-type> in the <location> relative to the given <xpath>.

	     For element nodes, the format of the <expression> should look
	     like "<element-name att-name='attvalue' ...>". The `<' and `>'
	     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.

	     Attribute nodes use the following syntax: "att-name='attvalue'
	     [...]".

	     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.

	     The <location> argument should be one of: `after', `before',
	     `into', `replace', `append' or `prepend'. See documentation of
	     the <location> argument type for more detail.

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

Example:     Append a new Hobbit element to the list of middle-earth
	     creatures and name him Bilbo.

             xsh> xadd element "<creature race='hobbit' manner='good'>" \
                              into /middle-earth/creatures
             xsh> xadd attribute "name='Bilbo'" \
                              into /middle-earth/creatures/creature[@race='hobbit'][last()]

see also:     insert move xmove

END

$HELP{'xadd'}=$HELP{'xinsert'};

$HELP{'node-type'}=[<<'END'];
Node-type argument type

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

Example:
             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>' 
               into //middle-earth/creatures;

END


$HELP{'location'}=[<<'END'];
Location argument type

description:
	     One of: `after', `before', `into', `append', `prepend',
	     `replace'.

	     NOTE: XSH 1.6 introduces two new values for location argument:
	     `append' and `prepend' and slighlty changes behavior of
	     `after' and `before'!

	     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.

	     `after/before' 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).

	     `append/prepend' 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.

	     `into' can also be used to place the source node to the end of
	     an element (in the same way as `append'), 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.

	     `replace' 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.

END


$HELP{'move'}=[<<'END'];
usage:       move <xpath> <location> <xpath>
             
aliases:     mv

description:
	     `move' command acts exactly like <copy>, except that it
	     removes the source nodes after a succesfull copy. Remember
	     that the moved nodes are actually different nodes 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.

	     See <copy> for more details on how the copies of the moved
	     nodes are created.

see also:     copy xmove insert xinsert

END

$HELP{'mv'}=$HELP{'move'};

$HELP{'xmove'}=[<<'END'];
usage:       xmove <xpath> <location> <xpath>
             
aliases:     xmv

description:
	     Like <xcopy>, except that `xmove' removes the source nodes
	     after a succesfull copy. Remember that the moved nodes are
	     actually different nodes 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.

	     See <xcopy> for more details on how the copies of the moved
	     nodes are created.

	     The following example demonstrates how `xcopy' can be used to
	     get rid of HTML `<font>' elements while preserving their
	     content. As an exercise, try to find out why simple `foreach
	     //font { xmove node() replace . }' would not work here.

Example:     Get rid of all <font> tags