lquery

API Reference

lquery

A library to allow jQuery-like HTML/DOM manipulation.

LQUERY

  • Variable *LQUERY-MASTER-DOCUMENT*
    nil
    The master document used at the beginning of a chain.
  • Macro WITH-MASTER-DOCUMENT ((&optional (doc '*lquery-master-document*)) &body body)
    Surrounds the body in a binding for the *lquery-master-document* to ensure it does not get clobbered.
  • Function MAKE-PROPER-VECTOR (&key (size 0) initial-element initial-contents (fill-pointer t))
    Creates a new proper vector.
  • Function COPY-PROPER-VECTOR (sequence &key (transform #'identity))
    Copies the sequence into a new proper vector.
  • Function ENSURE-PROPER-VECTOR (var)
    Ensure that the variable is a proper vector.
  • Function LOAD-PAGE (file-or-string)
    Load the given file or string into a HTML DOM.
  • Function INITIALIZE (document)
    Sets the *lquery-master-document* variable to the provided document.
  • Function PARSE-HTML (html)
    Build the given string into DOM objects related to the master document.
  • Macro DEFINE-LQUERY-FUNCTION (name (node-name &rest arguments) &body body)
    Defines a new node function. This is the main mechanism by which node manipulations are defined. All lquery functions are automatically created in the lquery-funcs package. NAME --- A symbol naming the lquery function. Automatically interned in the LQUERY-FUNCS package. NODE-NAME --- Symbol bound to the current node. ARGUMENTS --- A lambda-list specifying the arguments for the function. BODY ::= form*
  • Macro DEFINE-LQUERY-LIST-FUNCTION (name (vector-name &rest arguments) &body body)
    Defines a new function that operates on the current node array instead of individual elements. All lquery functions are automatically created in the lquery-funcs package. NAME --- A symbol naming the lquery function. Automatically interned in the LQUERY-FUNCS package. VECTOR-NAME --- Symbol bound to the node vector. ARGUMENTS --- A lambda-list specifying the arguments for the function. BODY ::= form*
  • Macro DEFINE-LQUERY-SUBROUTINE (name (&rest arguments) &body body)
    Defines a shorthand function. The body is a set of lQuery instructions as you'd use in $. NAME --- A symbol naming the subroutine. Automatically interned in the LQUERY-FUNCS package. ARGUMENTS --- A lambda-list specifying the arguments for the function. BODY ::= lquery-form*
  • Macro DEFINE-LQUERY-MACRO (name (previous-form &rest arguments) &body body)
    Define a new lquery local macro. All lquery macros are automatically created in the lquery-macros package. NAME --- A symbol naming the lquery macro. Automatically interned in the LQUERY-MACROS package. PREVIOUS-FORM --- Symbol bound to the so far assembled form, the previous value so to speak. ARGUMENTS --- A lambda-list specifying the arguments for the macro (note that this must be a standard lambda-list). BODY ::= form*
  • Macro $ (&body actions)
    Performs lQuery operations on the current document. Each argument is executed in sequence. The arguments are evaluated according to the defined argument-handlers. By default, the following cases are handled: * STRING Translates to a CLSS:QUERY on the current elements. * FUNCTION Translates to a function call with the list of nodes as argument. * SYMBOL Delegates to the value handlers. * LIST Lists are transformed according to their first element, which must be a symbol. If the symbol's name corresponds to a function found in the LQUERY-MACROS package, The form is assembled according to that function. Otherwise if it corresponds to an LQUERY-FUNCS function, it is expanded into a call to that function. If the symbol cannot be found in either package, it is put back in place, but the call itself is assembled like so: (FUNCTION PREVIOUS-RESULT ARGUMENT*) Values are handled at runtime according to the defined variable-handlers. By default, the following cases are handled at run time: * STRING Performs a CLSS:QUERY on the current elements. * DOM:NODE Replaces the current set of nodes with just this node. * FUNCTION Calls the given function with the current set of nodes as argument. * LIST Lists are transformed into a proper vector. * ARRAY Arrays are transformed into a proper vector. * VECTOR Vectors that are not adjustable are transformed into a proper vector. * T Any other value simply replaces the current list of nodes.
  • Macro $1 (&body actions)
    This is the same as $, except it automatically uses NODE at the end and thus only returns the first result, if any.
  • Macro DEFINE-ARGUMENT-HANDLER (type (argument-name operator-name) &body body)
    Defines a new argument handler that decides what to do with a certain type of argument at compile-time. TYPE --- A type or EQL specifier. ARGUMENT-NAME --- Symbol bound to the argument. OPERATOR-NAME --- Symbol bound to the object being operated on. BODY ::= form*
  • Macro DEFINE-VALUE-HANDLER (type (variable-name operator-name) &body body)
    Defines a new symbol handler that decides what to do with a certain type of symbol at run-time (variable type). TYPE --- A type or EQL specifier. VARIABLE-NAME --- Symbol bound to the argument. OPERATOR-NAME --- Symbol bound to the object being operated on. BODY ::= form*

Also exports

  • COMMON-LISP:EVAL
  • COMMON-LISP:INLINE

LQUERY-FUNCS

  • Function ADD (working-nodes selector-or-nodes)
    Add elements to the set of matched elements.
  • Function ADD-CLASS (node &rest classes)
    Adds the specified class(es) to the set of matched elements. The following types are handled for each class to add: NULL --- No class is added. STRING --- The string is added as a class. SYMBOL --- The symbol name, downcased, is added as a class. LIST --- Add all classes in the list. Each item must be one of the above types.
  • Function AFTER (nodes html-or-nodes)
    Insert content (in html-string or node-list form) after each element.
  • Function ANCESTOR (working-nodes)
    Find the common ancestor of all elements.
  • Function APPEND (nodes html-or-nodes)
    Insert content (in html-string or node-list form) to the end of each element.
  • Function APPEND-TO (working-nodes selector-or-nodes)
    Insert every element to the end of the target(s).
  • Function ATTR (node &rest pairs)
    Retrieve or set attributes on a node. The value on a node is turned into a string using PRINC-TO-STRING. If a value is NIL, the associated attribute is removed.
  • Function BEFORE (nodes html-or-nodes)
    Insert content (in html-string or node-list form) before each element.
  • Function CHILDREN (nodes &optional selector)
    Get the children of each element, optionally filtered by a selector.
  • Function CHILD-INDEX (node)
    Returns the index of the element within its parent, also counting text nodes. See index() otherwise.
  • Function CLONE (node)
    Create a deep copy of the set of matched elements.
  • Function CLOSEST (node selector)
    For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree. If no matching element can be found the root is entered instead.
  • Function CONTAINS (nodes string)
    Select all elements that contain the specified text.
  • Function CONTENTS (nodes)
    Get the children of each element, including text and comment nodes.
  • Function CSS (node &rest pairs)
    Retrieve or set css style attributes on a node.
  • Function DATA (node &rest pairs)
    Retrieve or set data attributes on a node. This is a convenience method and uses attr in the back.
  • Function DEEPEST (node)
    Returns the innermost (left-bound) child element.
  • Function DETACH (nodes &optional selector)
    Removes the node (optionally filtered by the selector) from the document. Alias for remove()
  • Function EACH (nodes fun &key replace)
    Execute the specified function on each element until NIL is returned or all elements have been processed. The original set of elements is returned if replace is NIL.
  • Function EMPTY (node)
    Remove all child nodes from the set of matched elements.
  • Function EMPTY-P (node)
    Check if the node contains no children and/or only empty (whitespace) text nodes. If it is empty, T is returned, otherwise NIL.
  • Function EQ (working-nodes index)
    Reduce the set of matched elements to the one at the specified index
  • Function EVEN (working-nodes)
    Selects even elements, 1-indexed
  • Function FILTER (nodes selector-or-function)
    Reduce the set of matched elements to those that match the selector or pass the function's test.
  • Function FIND (nodes selector-or-function &key (test-self common-lisp:nil))
    Get the descendants of each element filtered by selector or function.
  • Function FIRST (working-nodes)
    Reduce the set of matched elements to the first in the set.
  • Function GT (working-nodes index)
    Select all elements at a greater than index(0) within the matched set.
  • Function HAS (nodes selector-or-nodes)
    Reduce the set of matched elements to those that have a descendant that matches the selector or element.
  • Function HAS-CLASS (working-nodes class)
    Determine whether any of the matched elements are assigned to the given class.
  • Function HIDE (working-nodes)
    Hide the matched elements (short for (css "display" "none")).
  • Function HTML (node &optional new-content)
    Get the HTML contents of the elements or set the HTML contents of every matched element. The new content can be either a plump node, root, pathname, or string. If it is none of those, it is treated as a string via PRINC-TO-STRING
  • Function HTML-FILE (working-nodes pathname)
    Read an HTML file and insert its contents into each element.
  • Function INDEX (node)
    Find the index of the node within its parent.
  • Function INITIALIZE (working-nodes document)
    Re-initializes lQuery with a new page.
  • Function INSERT-AFTER (working-nodes selector-or-nodes)
    Insert every element after the target.
  • Function INSERT-BEFORE (working-nodes selector-or-nodes)
    Insert every element before the target.
  • Function IS (working-nodes selector-or-nodes)
    Check the current elements against a selector or list of elements and return true if at least one of them matches.
  • Function IS-EMPTY (node)
    Check if the node contains no children and/or only empty (whitespace) text nodes. If it is empty, T is returned, otherwise NIL. Alias of EMPTY-P
  • Function LAST (working-nodes)
    Reduce the set of matched elements to the final one in the set.
  • Function LENGTH (working-nodes)
    Returns the number of elements in the list.
  • Function LT (working-nodes index)
    Select all elements at an index less than the index within the matched set.
  • Function MAP (working-nodes function)
    Pass each element through a function (which has to accept one argument, the node), returning the list of all results.
  • Function MAP-APPLY (working-nodes function)
    Pass each element through a function by apply, returning the vector of all results. This is commonly useful in combination with COMBINE.
  • Function NEXT (nodes &optional selector)
    Get the immediately following sibling of each element (if there is one). If a selector is provided, the sibling is only included if it matches.
  • Function NEXT-ALL (nodes &optional selector)
    Get all following siblings of each element. If a selector is provided, the sibling is only included if it matches.
  • Function NEXT-UNTIL (nodes selector-or-nodes)
    Get all following silings of each element up to (excluding) the element matched by the selector or node list.
  • Function NODE (working-nodes &optional (n 0))
    Return the specified node (default first) directly, without encompassing it into a vector if it exists. Otherwise return NIL.
  • Function NOT (working-nodes selector-or-nodes)
    Remove matching elements from the working elements.
  • Function NOT-EMPTY (node)
    Check if the node contains no children and/or only empty (whitespace) text nodes. If the node is effectively empty NIL is returned, otherwise T
  • Function ODD (working-nodes)
    Select all odd elements from the current set, 1-indexed.
  • Function PARENT (nodes &optional selector)
    Get the parent of each element, optionally filtered by a selector.
  • Function PARENTS (nodes &optional selector)
    Get the ancestors of each element, optionally filtered by a selector. Closest parent first.
  • Function PARENTS-UNTIL (nodes selector-or-nodes)
    Get the ancestors of each element, up to (excluding) the element matched by the selector or node list. Closest parent first
  • Function PREPEND (nodes html-or-nodes)
    Insert content, specified by the parameter, to the beginning of each element.
  • Function PREPEND-TO (working-nodes selector-or-nodes)
    Insert every element to the beginning of the target(s).
  • Function PREV (nodes &optional selector)
    Get the immediately preceding sibling of each element (if there is one). If a selector is provided, the sibling is only included if it matches.
  • Function PREV-ALL (nodes &optional selector)
    Get all preceeding siblings of each element. If a selector is provided, the sibling is only included if it matches.
  • Function PREV-UNTIL (nodes selector-or-nodes)
    Get all preceeding silings of each element down to (excluding) the element matched by the selector or node list.
  • Function REMOVE (node &optional selector)
    Remove the set of matched elements from the DOM.
  • Function REMOVE-ATTR (node &rest attributes)
    Remove attributes from each element.
  • Function REMOVE-CLASS (node &rest classes)
    Remove classes from each element. Each class in the list can be of the following types: NULL --- Nothing is done. STRING --- Matching classes by string= are removed. SYMBOL --- Matching classes against the symbol name by string-equal are removed. LIST --- Add all classes in the list. Each item must be one of the above types.
  • Function REMOVE-DATA (node &rest data)
    Remove data attributes from each element. This is a convenience method and uses remove-attr in the back.
  • Function RENDER-TEXT (node)
    Return the "rendered" representation of the text inside the node and its children. In effect the text is gathered from the component and all of its children, but transforming the text in such a way that: - All ASCII white space (Space, Tab, CR, LF) is converted into spaces. - There are no consecutive spaces. - There are no spaces at the beginning or end.
  • Function REPLACE-ALL (working-nodes selector-or-nodes)
    Replace each in the set of matched elements with the current nodes.
  • Function REPLACE-WITH (working-nodes html-or-nodes)
    Replace each element with the provided new content and return the set of elements that was removed.
  • Function ROOT (working-nodes)
    Returns to the root. Essentially traverses up the tree of the first element in the set until the root is reached.
  • Function SHOW (working-nodes)
    Display the matched elements (short for (css :display 'block'))
  • Function SIBLINGS (nodes &optional selector)
    Get the siblings of each element, optionally filtered by a selector.
  • Function SIZE (working-nodes)
    Return the number of elements in the list.
  • Function SLICE (working-nodes start &optional end)
    Reduce the set of matched elements to a subset specified by a range of indices
  • Function SPLICE (node)
    Splice the element's contents in place of itself.
  • Function TEXT (node &optional (text common-lisp:nil t-s-p))
    Get the combined text contents of each element, including their descendants. If text is set, all text nodes are removed and a new text node is appended to the end of the node. If text is NIL, all direct text nodes are removed from the node. If text is not a string, it is transformed into one by PRINC-TO-STRING.
  • Function TOGGLE-CLASS (node &rest classes)
    Add or remove one or more classes from each element, depending on their presence within the element.
  • Function UNWRAP (node)
    Remove the parents of the set of matched elements from the DOM, inserting the parents children in place of it.
  • Function VAL (node &optional (value common-lisp:nil v-p))
    Get the current values or set the value of every matched element.
  • Function WRAP (nodes html-or-nodes)
    Wrap an HTML structure around each element. Note that always the first node of the structure to wrap is chosen.
  • Function WRAP-ALL (working-nodes html-or-nodes)
    Wrap an HTML structure around all elements and put it in place of the first element, removing all other elements from their position.
  • Function WRAP-INNER (nodes html-or-nodes)
    Wrap an HTML structure around the contents of each element.
  • Function WRITE-TO-FILE (working-nodes file &key (if-does-not-exist :create) (if-exists :supersede))
    Write the serialized node to the file. Note that always only the first element is written.
  • Function SERIALIZE (node &optional (stream common-lisp:nil) (format :default))
    Serialize the node into a string. Allows two optional arguments: STREAM --- NIL to return a string, or a stream to output to. FORMAT --- One of :DEFAULT, :HTML, :XML to designate the way in which to invoke Plump's serializer.

LQUERY-MACROS

  • Function FUNCTION (nodes name)
    Macro to allow #'foo to be used in lquery chains.
  • Function EVAL (nodes form)
    Evaluates the form at compile-time and puts its resulting value in place.
  • Function INLINE (nodes form)
    Treats the form as if the evaluated value was put literally in place. See DETERMINE-VALUE.
  • Function COMBINE (nodes &rest calls)
    COMBINES multiple lquery function calls into one by gathering them into a list for each element. ($ (combine (text) (attr :a))) would be equivalent to ($ (map #'(lambda (node) (list (lquery-funcs:text node) (lquery-funcs:attr node :a))))) This construct is especially useful in combination with MAP-APPLY.
  • Function INITIALIZE (nodes &rest init-calls)
    See lquery function INITIALIZE. This is merely a performance macro to avoid the unnecessary default allocation of a vector.

lquery-test

A library to allow jQuery-like HTML/DOM manipulation. Unit tests package.

LQUERY-TEST

  • Function RUN