leptris 1.9.201.1-arm-linux → 1.9.201.2-arm-linux

data/vendor-src/libleptris/cli/man/leptris-parse.1.adoc

@@ -0,0 +1,213 @@
+= leptris-parse(1)
+:doctype: manpage
+:man manual: Leptris Manual
+:man source: Leptris 0.1.0
+:man version: 0.1.0
+
+== NAME
+leptris-parse - parse and validate XML documents
+
+== SYNOPSIS
+*leptris parse* [_OPTIONS_] _FILE_
+
+== DESCRIPTION
+Parse and validate XML documents. The *parse* command reads an XML file, 
+validates its structure according to the XML 1.0 specification, and optionally 
+outputs the parsed document in various formats.
+
+This command is useful for:
+
+* Validating XML document syntax
+* Converting XML to different formats (JSON, text tree)
+* Checking well-formedness of XML files
+* Pretty-printing XML with validation
+
+== OPTIONS
+
+*--validate*::
+    Enable validation (not yet implemented). Future feature for DTD/Schema validation.
+
+*--recover*::
+    Enable error recovery mode (not yet implemented). Future feature for parsing 
+    malformed XML.
+
+*--noout*::
+    Suppress output. Only validate the document and report errors. Useful for 
+    checking XML validity without generating output. Exit code indicates success 
+    or failure.
+
+*--format* _FORMAT_::
+    Output format. Valid values:
+    * *xml* - Standard XML output (default)
+    * *json* - JSON representation of the document tree
+    * *text* - Human-readable text tree structure
+
+*-h, --help*::
+    Show help message for the parse command.
+
+== ARGUMENTS
+
+_FILE_::
+    Path to the XML file to parse. Use *-* to read from standard input.
+
+== OUTPUT FORMATS
+
+=== XML Format (default)
+Outputs the parsed XML in standard XML format with proper formatting.
+
+=== JSON Format
+Outputs a JSON representation of the document tree structure:
+
+[source,json]
+----
+{
+  "root": {
+    "name": "book",
+    "attributes": {"id": "1"},
+    "children": [...]
+  }
+}
+----
+
+=== Text Format
+Outputs a human-readable tree structure:
+
+----
+root
+  └─ book (id="1")
+     ├─ title
+     │  └─ "The C Programming Language"
+     └─ author
+        └─ "Kernighan and Ritchie"
+----
+
+== EXAMPLES
+
+=== Validate an XML file
+[source,bash]
+----
+leptris parse document.xml
+----
+
+Parses and validates `document.xml`. If successful, outputs the parsed XML.
+
+=== Validate without output
+[source,bash]
+----
+leptris parse --noout document.xml
+----
+
+Validates the XML file but suppresses output. Check exit code: 0 for success, 
+1 for parse errors.
+
+=== Parse with JSON output
+[source,bash]
+----
+leptris parse --format json library.xml
+----
+
+Parses the XML and outputs a JSON representation of the document tree.
+
+=== Parse with text tree output
+[source,bash]
+----
+leptris parse --format text library.xml
+----
+
+Outputs a human-readable tree structure showing the document hierarchy.
+
+=== Parse from stdin
+[source,bash]
+----
+cat document.xml | leptris parse -
+----
+
+Reads XML from standard input and parses it.
+
+=== Validate multiple files in a script
+[source,bash]
+----
+for file in *.xml; do
+    if leptris parse --noout "$file"; then
+        echo "✓ $file is valid"
+    else
+        echo "✗ $file has errors"
+    fi
+done
+----
+
+=== Check if file is well-formed
+[source,bash]
+----
+if leptris parse --noout document.xml 2>/dev/null; then
+    echo "Document is well-formed"
+fi
+----
+
+== EXIT STATUS
+
+*0*::
+    Success - XML is well-formed and valid
+
+*1*::
+    Parse error - XML is malformed or has syntax errors
+
+*3*::
+    I/O error - cannot read input file
+
+*4*::
+    Invalid arguments - incorrect options or missing file argument
+
+== ERROR HANDLING
+
+When parsing fails, *leptris parse* provides detailed error messages including:
+
+* Line and column numbers where the error occurred
+* Description of the syntax error
+* Context snippet showing the problematic area
+
+Example error output:
+----
+Error: Parse error at line 5, column 12
+  Unclosed tag 'book'
+  <book>
+      <title>Example
+  ----------^
+----
+
+== SEE ALSO
+
+*leptris*(1), *leptris-xpath*(1), *leptris-format*(1), *libleptris*(5)
+
+== STANDARDS
+
+Implements XML 1.0 (Fifth Edition) specification.
+
+== NOTES
+
+=== Future Features
+
+The *--validate* and *--recover* options are reserved for future implementation:
+
+* *--validate* will support DTD and XML Schema validation
+* *--recover* will attempt to parse malformed XML with error recovery
+
+=== Comparison with xmllint
+
+[cols="2,2",options="header"]
+|===
+|xmllint |leptris parse
+
+|`xmllint file.xml`
+|`leptris parse file.xml`
+
+|`xmllint --noout file.xml`
+|`leptris parse --noout file.xml`
+
+|`xmllint --format file.xml`
+|`leptris format file.xml`
+|===
+
+== COPYRIGHT
+
+Copyright (c) 2024 Ribose Inc. Licensed under the MIT License.

data/vendor-src/libleptris/cli/man/leptris-xpath.1.adoc

@@ -0,0 +1,479 @@
+= leptris-xpath(1)
+:doctype: manpage
+:man manual: Leptris Manual
+:man source: Leptris 0.1.0
+:man version: 0.1.0
+
+== NAME
+leptris-xpath - execute XPath queries against XML documents
+
+== SYNOPSIS
+*leptris xpath* [_OPTIONS_] _FILE_ _EXPRESSION_
+
+== DESCRIPTION
+Execute XPath 1.0 queries against XML documents. The *xpath* command evaluates 
+an XPath expression and returns results in various formats. Supports all XPath 
+1.0 features including node-sets, predicates, functions, and operators.
+
+This command provides complete XPath 1.0 implementation with:
+
+* All 13 XPath axes
+* All 27 standard XPath functions
+* All 15 operators (logical, comparison, arithmetic, union)
+* Complete predicate support (position and boolean)
+* Namespace-aware queries
+* Multiple output formats (XML, JSON, text)
+
+== OPTIONS
+
+*--count*::
+    Output only the count of matching nodes. Returns a number instead of the 
+    full node-set. Useful for quick statistics.
+
+*--boolean*::
+    Output boolean result only. Returns "true" or "false" based on whether the 
+    expression matches any nodes or evaluates to true.
+
+*--nsfile* _FILE_::
+    Namespace bindings file (not yet implemented). Future feature for specifying 
+    namespace prefix mappings.
+
+*--format* _FORMAT_::
+    Output format. Valid values:
+    * *xml* - XML output for node-sets (default)
+    * *json* - JSON representation
+    * *text* - Human-readable text
+
+*-h, --help*::
+    Show help message for the xpath command.
+
+== ARGUMENTS
+
+_FILE_::
+    Path to the XML file to query. Use *-* to read from standard input.
+
+_EXPRESSION_::
+    XPath 1.0 expression to evaluate. Must be quoted if it contains spaces 
+    or special shell characters.
+
+== XPATH 1.0 OVERVIEW
+
+=== Axes (13 Total)
+
+XPath axes define the direction of traversal from the context node:
+
+*child*::
+    Direct children of the context node. Example: `child::book`
+
+*descendant*::
+    All descendants (children, grandchildren, etc.). Example: `descendant::title`
+
+*descendant-or-self*::
+    Context node plus all descendants. Example: `descendant-or-self::*`
+
+*parent*::
+    Parent of the context node. Example: `parent::library`
+
+*ancestor*::
+    All ancestors (parent, grandparent, etc.). Example: `ancestor::*`
+
+*ancestor-or-self*::
+    Context node plus all ancestors. Example: `ancestor-or-self::book`
+
+*self*::
+    The context node itself. Example: `self::book`
+
+*following*::
+    All nodes after the context node in document order. Example: `following::book`
+
+*following-sibling*::
+    Following siblings of the context node. Example: `following-sibling::chapter`
+
+*preceding*::
+    All nodes before the context node in document order. Example: `preceding::title`
+
+*preceding-sibling*::
+    Preceding siblings of the context node. Example: `preceding-sibling::chapter`
+
+*attribute*::
+    Attributes of the context node. Example: `attribute::id` or `@id`
+
+*namespace*::
+    Namespace nodes of the context node. Example: `namespace::*`
+
+=== Functions (27 Total)
+
+==== Node-set Functions (7)
+
+*last()*::
+    Returns the context size (number of nodes in context). Example: `//book[last()]`
+
+*position()*::
+    Returns the context position (1-based index). Example: `//book[position() = 1]`
+
+*count(node-set)*::
+    Returns count of nodes in node-set. Example: `count(//book)`
+
+*id(string)*::
+    Returns nodes with matching ID attribute. Example: `id('book1')`
+
+*local-name(node-set?)*::
+    Returns local name of first node. Example: `local-name(//book[1])`
+
+*namespace-uri(node-set?)*::
+    Returns namespace URI of first node. Example: `namespace-uri(//ns:book[1])`
+
+*name(node-set?)*::
+    Returns qualified name of first node. Example: `name(//book[1])`
+
+==== String Functions (10)
+
+*string(object?)*::
+    Converts object to string. Example: `string(//title)`
+
+*concat(string, string, string*)*::
+    Concatenates strings. Example: `concat('Hello', ' ', 'World')`
+
+*starts-with(string, string)*::
+    Tests if first string starts with second. Example: `starts-with(title, 'The')`
+
+*contains(string, string)*::
+    Tests if first string contains second. Example: `contains(title, 'XML')`
+
+*substring-before(string, string)*::
+    Returns substring before first occurrence. Example: `substring-before('a-b', '-')`
+
+*substring-after(string, string)*::
+    Returns substring after first occurrence. Example: `substring-after('a-b', '-')`
+
+*substring(string, number, number?)*::
+    Returns substring from position. Example: `substring('hello', 2, 3)`
+
+*string-length(string?)*::
+    Returns string length. Example: `string-length(title)`
+
+*normalize-space(string?)*::
+    Normalizes whitespace. Example: `normalize-space('  hello  ')`
+
+*translate(string, string, string)*::
+    Translates characters. Example: `translate('abc', 'abc', 'xyz')`
+
+==== Boolean Functions (5)
+
+*boolean(object)*::
+    Converts object to boolean. Example: `boolean(//book)`
+
+*not(boolean)*::
+    Logical NOT. Example: `not(@deleted)`
+
+*true()*::
+    Returns true. Example: `//book[true()]`
+
+*false()*::
+    Returns false. Example: `//book[false()]`
+
+*lang(string)*::
+    Tests node language. Example: `//book[lang('en')]`
+
+==== Number Functions (5)
+
+*number(object?)*::
+    Converts object to number. Example: `number(@price)`
+
+*sum(node-set)*::
+    Sums numeric values. Example: `sum(//book/@price)`
+
+*floor(number)*::
+    Rounds down. Example: `floor(3.7)`
+
+*ceiling(number)*::
+    Rounds up. Example: `ceiling(3.2)`
+
+*round(number)*::
+    Rounds to nearest integer. Example: `round(3.5)`
+
+=== Operators (15 Total)
+
+*Logical*:: `or`, `and`
+*Equality*:: `=`, `!=`
+*Relational*:: `<`, `<=`, `>`, `>=`
+*Arithmetic*:: `+`, `-`, `*`, `div`, `mod`
+*Union*:: `|`
+
+== EXAMPLES
+
+=== Basic Path Queries
+
+==== Find all book elements
+[source,bash]
+----
+leptris xpath library.xml "//book"
+----
+
+==== Find all titles
+[source,bash]
+----
+leptris xpath library.xml "//book/title"
+----
+
+==== Absolute path from root
+[source,bash]
+----
+leptris xpath document.xml "/root/section/item"
+----
+
+=== Predicate Queries
+
+==== First book
+[source,bash]
+----
+leptris xpath library.xml "//book[1]"
+----
+
+==== Last book
+[source,bash]
+----
+leptris xpath library.xml "//book[last()]"
+----
+
+==== Books with price attribute
+[source,bash]
+----
+leptris xpath library.xml "//book[@price]"
+----
+
+==== Books with specific price
+[source,bash]
+----
+leptris xpath library.xml "//book[@price='29.99']"
+----
+
+==== Books with price greater than 30
+[source,bash]
+----
+leptris xpath library.xml "//book[@price > 30]"
+----
+
+==== Multiple predicates
+[source,bash]
+----
+leptris xpath library.xml "//book[@category='fiction'][1]"
+----
+
+Selects the first book that has category="fiction".
+
+=== Function Queries
+
+==== Count books
+[source,bash]
+----
+leptris xpath library.xml "count(//book)"
+----
+Or with --count option:
+[source,bash]
+----
+leptris xpath --count library.xml "//book"
+----
+
+==== String concatenation
+[source,bash]
+----
+leptris xpath library.xml "concat(//book[1]/author, ': ', //book[1]/title)"
+----
+
+==== Check if title starts with "The"
+[source,bash]
+----
+leptris xpath library.xml "//book[starts-with(title, 'The')]"
+----
+
+==== Books with titles containing "XML"
+[source,bash]
+----
+leptris xpath library.xml "//book[contains(title, 'XML')]"
+----
+
+==== Sum all book prices
+[source,bash]
+----
+leptris xpath library.xml "sum(//book/@price)"
+----
+
+==== Get string length of first title
+[source,bash]
+----
+leptris xpath library.xml "string-length(//book[1]/title)"
+----
+
+=== Namespace-Aware Queries
+
+==== Query with namespace prefix
+[source,bash]
+----
+leptris xpath document.xml "//ns:book/ns:title"
+----
+
+Automatically detects namespace declarations in the document.
+
+==== Query all elements regardless of namespace
+[source,bash]
+----
+leptris xpath document.xml "//*[local-name()='book']"
+----
+
+=== Axis Queries
+
+==== Get parent element
+[source,bash]
+----
+leptris xpath library.xml "//title/parent::book"
+----
+
+==== Get following siblings
+[source,bash]
+----
+leptris xpath library.xml "//book[1]/following-sibling::book"
+----
+
+==== Get all descendants
+[source,bash]
+----
+leptris xpath library.xml "//library/descendant::title"
+----
+
+=== Boolean Queries
+
+==== Check if fiction books exist
+[source,bash]
+----
+leptris xpath --boolean library.xml "//book[@category='fiction']"
+----
+
+Returns "true" or "false".
+
+==== Test with logical operators
+[source,bash]
+----
+leptris xpath --boolean library.xml "//book[@price > 20 and @price < 40]"
+----
+
+=== Output Format Examples
+
+==== JSON output
+[source,bash]
+----
+leptris xpath --format json library.xml "//book"
+----
+
+==== Text output
+[source,bash]
+----
+leptris xpath --format text library.xml "//book/title"
+----
+
+=== From Standard Input
+
+[source,bash]
+----
+cat library.xml | leptris xpath - "//book/title"
+----
+
+=== Advanced Queries
+
+==== Union of multiple paths
+[source,bash]
+----
+leptris xpath library.xml "//book/title | //book/author"
+----
+
+==== Complex predicate with functions
+[source,bash]
+----
+leptris xpath library.xml "//book[string-length(title) > 20]"
+----
+
+==== Nested predicates
+[source,bash]
+----
+leptris xpath library.xml "//book[author[contains(., 'Smith')]]"
+----
+
+== EXIT STATUS
+
+*0*::
+    Success - expression evaluated successfully
+
+*2*::
+    XPath error - invalid expression or evaluation failed
+
+*3*::
+    I/O error - cannot read input file
+
+*4*::
+    Invalid arguments - incorrect options or missing arguments
+
+== RESULT TYPES
+
+XPath expressions return one of four result types:
+
+*Node-set*::
+    Collection of nodes. Default output shows all matching nodes.
+
+*String*::
+    Text value. Output as plain text.
+
+*Number*::
+    Numeric value. Output as decimal number.
+
+*Boolean*::
+    True or false. Output as "true" or "false".
+
+The *--count* and *--boolean* options control how non-node-set results are displayed.
+
+== SEE ALSO
+
+*leptris*(1), *leptris-parse*(1), *libleptris*(5)
+
+XPath 1.0 Specification: https://www.w3.org/TR/xpath-10/
+
+== STANDARDS
+
+Implements complete XPath 1.0 specification from W3C.
+
+== NOTES
+
+=== Namespace Handling
+
+Leptris automatically detects namespace declarations in the XML document and makes 
+them available for XPath queries. Namespace prefixes used in the XPath expression 
+must match those used in the document.
+
+Future versions will support custom namespace prefix mappings via the *--nsfile* option.
+
+=== Performance
+
+XPath queries are evaluated in a single pass with minimal memory overhead. 
+Node-sets maintain document order automatically.
+
+=== Comparison with xmllint
+
+[cols="2,2",options="header"]
+|===
+|xmllint |leptris xpath
+
+|`xmllint --xpath '//book' file.xml`
+|`leptris xpath file.xml '//book'`
+
+|`xmllint --xpath 'count(//book)' file.xml`
+|`leptris xpath --count file.xml '//book'`
+
+|Not available
+|`leptris xpath --boolean file.xml '//book'`
+
+|Not available
+|`leptris xpath --format json file.xml '//book'`
+|===
+
+== COPYRIGHT
+
+Copyright (c) 2024 Ribose Inc. Licensed under the MIT License.