More package docstrings
Sun Apr 27 10:19:32 PDT 2008 David Lichteblau <david@lichteblau.com>
* More package docstrings
diff -rN -u old-plexippus-xpath/package.lisp new-plexippus-xpath/package.lisp
--- old-plexippus-xpath/package.lisp 2014-07-31 04:34:55.000000000 -0700
+++ new-plexippus-xpath/package.lisp 2014-07-31 04:34:55.000000000 -0700
@@ -90,7 +90,10 @@
(:documentation
"The XPATTERN package implements pattern matching compatible with XSLT 1.0.
- @begin[Using pattern matchers]{section}
+ @begin[Utilities powered by pattern matchers]{section}
+ The following convenience functions and macros use patterns. They
+ are implemented using the lower-level functions listed below.
+
@aboutfun{node-matches-p}
@aboutmacro{pattern-case}
@aboutmacro{pattern-ecase}
@@ -111,7 +114,10 @@
@aboutfun{make-pattern-matcher}
@aboutfun{make-pattern-matcher*}
- To invoke a matcher, use @code{matching-value} or @code{matching-values}:
+ @end{section}
+ @begin[Applying pattern matchers]{section}
+ To invoke a matcher created by @code{make-pattern-matcher}, use
+ @code{matching-value} or @code{matching-values}:
@aboutfun{matching-value}
@aboutfun{matching-values}
@@ -174,22 +180,111 @@
#:*navigator*
#:xpath-error)
- (:documentation
- "Plexippus XPath is an XPath implementation for Common Lisp.
- TBD: document here:
- environments/variables, XPath sexpr-based syntax, representation of XPath
- types (incl. xnums), extensions, samples
+;;; TBD: document here:
+;;; environments/variables, XPath sexpr-based syntax, representation of XPath
+;;; types (incl. xnums), extensions, samples
+
+ (:documentation
+ "Plexippus XPath is an XPath 1.0 implementation for Common Lisp.
@begin[Using XPath]{section}
- TBD
+ Almost all uses of XPath involve the @code{evaluate} function, which
+ can parse, compile, and invoke XPath expressions.
+
+ @aboutfun{evaluate}
+ @aboutmacro{xpath}
@end{section}
@begin[Compiling XPath dynamically]{section}
- TBD
+ @code{compile-xpath} allows the compilation of XPath into a closure
+ ahead of time, so that @code{evaluate} only needs to invoke that closure
+ rather than having to re-compile it first.
+
+ Although @code{evaluate} itself already performs caching of compiled
+ closures, explicit precompilation can aid optimizations if one
+ call site uses multiple XPath expressions.
+
+ Explicit compilation using @code{compile-xpath} is also required when
+ using custom environment classes, since @code{evaluate} compiles
+ expressions using the dynamic environment only.
+
+ @code{parse-xpath} can be used to translate the standard string
+ representation of XPath into a Plexippus-specific sexp representation.
+ Both @code{compile-xpath} and @code{evaluate} accept sexps instead of
+ strings.
+
+ @aboutfun{parse-xpath}
+ @aboutfun{compile-xpath}
+ @end{section}
+ @begin[Type coercion]{section}
+ These correspond to the XPath functions boolean(),
+ string(), and number(). In addition, @code{node-set-value}
+ is provided, which turns nodes into node sets.
+
+ @aboutfun{boolean-value}
+ @aboutfun{string-value}
+ @aboutfun{number-value}
+ @aboutfun{node-set-value}
@end{section}
@begin[The dynamic environment]{section}
- TBD
- @end{section} "))
+ The default enviroment used by @code{evaluate} is the dynamic
+ environment, backed by information bound in dynamic variables.
+ The following macros are used to bind these variables. They have
+ dynamic scope. (The dynamic environment is currently not capable
+ of dynamic declarations for variables, but can be used with extension
+ functions that are declared globally.)
+
+ (The XPATH-SYS defined an @a[xpath-sys.html]{environment protocol}
+ for user-defined environment classes.)
+
+ @aboutmacro{with-namespaces}
+ @aboutmacro{with-variables}
+ @end{section}
+ @begin[The run-time context]{section}
+ Instead of passing a node to @code{evaluate}, user code can construct
+ a full context object.
+
+ The context object specifies values to be returned by position(),
+ current(), and last().
+
+ @aboutclass{context}
+ @aboutfun{make-context}
+ @aboutfun{context-node}
+ @aboutfun{context-starting-node}
+ @aboutfun{context-position}
+ @aboutfun{context-size}
+ @end{section}
+ @begin[Node sets]{section}
+ Node sets are the XPath data type used to represent the results of
+ evaluations that select multiple nodes. As sets, they never contain
+ duplicates.
+
+ In addition to the high-level functions defined here, the XPATH-SYS
+ package defined several @a[xpath-sys.html]{low-level node set functions}.
+ Please also refer to the description there for details on node set order.
+
+ @aboutfun{first-node}
+ @aboutfun{all-nodes}
+ @aboutfun{map-node-set}
+ @aboutfun{map-node-set->list}
+ @aboutmacro{do-node-set}
+ @aboutfun{make-node-set-iterator}
+ @aboutfun{node-set-iterator-end-p}
+ @aboutfun{node-set-iterator-next}
+ @aboutfun{node-set-iterator-current}
+ @aboutfun{node-set-p}
+ @aboutfun{node-set-empty-p}
+ @aboutfun{node-set}
+ @aboutfun{list->node-set}
+ @aboutfun{sort-node-set}
+ @end{section}
+ @begin[Miscellaneous]{section}
+ Other useful functions, variables, and classes:
+
+ @aboutmacro{with-plx-extensions}
+ @aboutvar{*navigator*}
+ @aboutclass{xpath-error}
+ @end{section}"))
(defpackage :xpath-sys
(:import-from :xpath-protocol
@@ -224,4 +319,60 @@
#:define-xpath-function/eager
#:define-xpath-function/single-type)
(:documentation
- "XPATH-SYS package contains API for extending Plexippus XPath."))
+ "The XPATH-SYS package provides an API for extensions to Plexippus XPath.
+
+ @begin[Pipes]{section}
+ Pipes are lazy lists, inspired by their implementation in
+ Norvig's 'Paradigms of Artificial Intelligence Programming'.
+
+ @aboutmacro{make-pipe}
+ @aboutfun{pipe-head}
+ @aboutfun{pipe-tail}
+ @end{section}
+ @begin[Node sets]{section}
+ Node sets are the XPath data type used to represent the results of
+ evaluations that select multiple nodes. As sets, they never contain
+ duplicates. Conceptually, they are unordered, with the most important
+ order defined on them being the document order.
+
+ As a data structure though, node sets are backed by a pipe, and the order
+ of elements in that pipe is well-documented: By default, the pipe of
+ returned node sets is sorted into document order. When unordered
+ results are requested, the order is usually not specified, but in some
+ cases, are already sorted according to the axis being queried, which
+ is usually sorted either in document order,or in reverse document order.
+ See @fun{xpath:evaluate} for the @code{unordered} argument.
+
+ @aboutfun{make-node-set}
+ @aboutfun{pipe-of}
+ @end{section}
+ @begin[Implementing environments]{section}
+ Environments provide compilation-time configuration for XPath.
+ An environment is a CLOS object, which is queried by the compiler using
+ generic functions that users can implement on their own subclasses
+ of @class{xpath::environment}.
+
+ The default environment class implements a `dynamic' environment, backed
+ by information bound in dynamic variables, so that typical uses of XPath
+ work without special environment classes.
+
+ @aboutfun{environment-find-namespace}
+ @aboutfun{environment-find-variable}
+ @aboutfun{environment-find-function}
+ @end{section}
+ @begin[Defining extension functions]{section}
+ XPath defines built-in functions in the empty namespace. Using
+ the extension API, user code can implement XPath functions addressed
+ using other namespaces.
+
+ @aboutmacro{define-extension}
+ @aboutmacro{define-xpath-function/lazy}
+ @aboutmacro{define-xpath-function/eager}
+ @aboutmacro{define-xpath-function/single-type}
+ @aboutfun{find-xpath-function}
+ @end{section}
+ @begin[Miscellaneous functions]{section}
+ Other useful functions:
+
+ @aboutfun{get-node-id}
+ @end{section}"))
diff -rN -u old-plexippus-xpath/plx.lisp new-plexippus-xpath/plx.lisp
--- old-plexippus-xpath/plx.lisp 2014-07-31 04:34:55.000000000 -0700
+++ new-plexippus-xpath/plx.lisp 2014-07-31 04:34:55.000000000 -0700
@@ -34,7 +34,7 @@
(defparameter *plx-uri* "http://common-lisp.net/project/plexippus-xpath/plx")
(defmacro with-plx-extensions (&body body)
- "Binds plx prefix to Plexippus XPath extensions namespace.
+ "@short{Binds plx prefix to Plexippus XPath extensions namespace.}
The following functions are currently available:
diff -rN -u old-plexippus-xpath/types.lisp new-plexippus-xpath/types.lisp
--- old-plexippus-xpath/types.lisp 2014-07-31 04:34:55.000000000 -0700
+++ new-plexippus-xpath/types.lisp 2014-07-31 04:34:55.000000000 -0700
@@ -438,7 +438,9 @@
@short{Generates an unique identifier for the first node @code{node-set}
(or, if a node is specified, for that node).}
- This function is analagous to generate-id() XSLT function."
+ This function is similar to the generate-id() XSLT function, but its
+ results are unique only within its document, whereas XSLT also prepends
+ an ID designating the document."
(cond ((not (node-set-p node-or-node-set))
(concat
(if (xpath-protocol:parent-node node-or-node-set)
Warning: CRC errors found. These are probably harmless but should be repaired.
See 'darcs gzcrcs --help' for more information.