The css-selectors Reference Manual

Table of Contents

The css-selectors Reference Manual

This is the css-selectors Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:36:44 2021 GMT+0.

1 Introduction

css-selectors: a jquery-style dom query language

CSS-selectors is a query language for finding specific nodes in dom documents and sub trees. CSS-selectors works with:

• cxml dom
• cxml-stp (load :css-selectors-stp)
• cl-html5-parser simple-tree (load :css-selectors-simple-tree)

API

query

 (query
   (or css-selector-string match-fn)
   (or nodes *document*))

Similar to jQuery('css-selector', NodeList or document)

Returns a list of matching nodes.

if the first argument is a css-selector string, compile it (as with compile-css-node-matcher) into a matcher function and call query again with it

if the first argument is a function, it is assumed to take a single node and to test whether or not that node matches the css-selector match function

If the css-selector-string is constantp, it will be compiled at compile time

The second argument is either a dom-node, a list of dom-nodes or the a dom document. It defaults to buildnode:document.

For full examples, please see the test suite, but a basic query call looks like:

(css-selectors:query "a" document)

which will return a list of all "a" tags in the document.

query1

Exactly the same as (first (query ...)), except that it avoids consing up an intermediate list.

node-matches?

 (node-matches? node-node (or match-fn css-selector-string))

if the second argument is a css-selector, compile it (as with compile-css-node-matcher) into a matcher function and call node-matches again with it

if the second argument is a function, it is assumed to take a single node and to test whether or not that node matches the css-selector match function

If the css-selector-string is constantp, it will be compiled at compile time

parse-results

 (parse-results inp)

Parses a css3 selector into an AST representing the selector expression. Probably only useful for debugging or implementing a different compiler.

Uses clppcre and VERY basic flex parser (defined in parse.lisp) to create a lexer. Combines that lexer with a parser generated by cl-yacc and runs the input through the parse.

compile-css-node-matcher

 (compile-css-node-matcher inp)

Turns a parse-tree or css-selector-string into a compiled lambda matcher function this matcher function can be used with query and node-matches?. The matcher function takes two arguments

Pseudo Selectors

Implementing new pseudo selectors

Any function defined in the :pseudo (:css-selectors.pseudo) will be available as a pseudo selector (see pseudo.lisp for examples).

All pseudo selectors should be of the following format: (defun pseudo:MY-NEW-PSEUDO (node &optional sub-sel-function) ...)

If your pseudo selector has no args, then it should signal an error if a sub-selction-function is passed to it and vice-versa

Authors

• Acceleration.net Donate
• Russ Tyndall
• Nathan Bird
• Ryan Davis

;; Copyright (c) 2011 Russ Tyndall , Acceleration.net http://www.acceleration.net
;; All rights reserved.
;;
;; Redistribution and use in source and binary forms, with or without
;; modification, are permitted provided that the following conditions are
;; met:
;;
;;  - Redistributions of source code must retain the above copyright
;;    notice, this list of conditions and the following disclaimer.
;;
;;  - Redistributions in binary form must reproduce the above copyright
;;    notice, this list of conditions and the following disclaimer in the
;;    documentation and/or other materials provided with the distribution.
;;
;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
;; A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
;; LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
;; DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
;; THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
;; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
;; OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 css-selectors

Author

<programmers@acceleration.net>

License

BSD

Description

An implementation of css selectors

Dependencies

• iterate
• yacc
• cl-ppcre
• buildnode
• alexandria
• cxml
• cl-interpol
• symbol-munger

Source

css-selectors.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 css-selectors/src

Parent

css-selectors (system)

Location

src/

Components

• packages.lisp (file)
• node-api.lisp (file)
• parse.lisp (file)
• pseudo.lisp (file)
• compile.lisp (file)
• dom.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 css-selectors.asd

Location

css-selectors.asd

Systems

css-selectors (system)

Packages

net.acceleration.css-selectors.system

4.1.2 css-selectors/src/packages.lisp

Parent

src (module)

Location

src/packages.lisp

Packages

• css-selectors.pseudo
• css-selectors

4.1.3 css-selectors/src/node-api.lisp

Dependency

packages.lisp (file)

Parent

src (module)

Location

src/node-api.lisp

Internal Definitions

• child-elements (generic function)
• child-nodes (generic function)
• document-of (generic function)
• element-p (generic function)
• element-p (method)
• get-attribute (generic function)
• parent-element (generic function)
• parent-element (method)
• parent-elements (generic function)
• parent-elements (method)
• parent-node (generic function)
• previous-sibling (generic function)
• tag-name (generic function)

4.1.4 css-selectors/src/parse.lisp

Dependency

node-api.lisp (file)

Parent

src (module)

Location

src/parse.lisp

Exported Definitions

parse-results (function)

Internal Definitions

• %rule (function)
• %rule-set (function)
• *css3-selector-parser* (special variable)
• +common-white-space-trimbag+ (special variable)
• +css3-lex-productions+ (special variable)
• +end-of-defs+ (special variable)
• +option+ (special variable)
• +option-case-insensitive+ (special variable)
• +return-value+ (special variable)
• all-group-matches-as-string (function)
• arg-list-var-names (function)
• but-first (function)
• but-last (function)
• but-quotes (function)
• dos-safe-read-line (function)
• expand-return-value (function)
• handle-quoted-rules (function)
• is-special? (function)
• keywordize (function)
• lam (macro)
• lex-results (function)
• make-css3-lexer (function)
• read-flex-file (function)
• replace-all (function)
• replace-expansions (function)
• rule (macro)
• rule-set (macro)
• string-upcase? (function)
• symbolize (function)
• til-open (function)
• trim-and-nullify (function)
• trim-whitespace (function)
• uniquify-and-reintern (function)

4.1.5 css-selectors/src/pseudo.lisp

Dependency

parse.lisp (file)

Parent

src (module)

Location

src/pseudo.lisp

Exported Definitions

• empty (function)
• first-child (function)
• has (function)
• is (function)
• last-child (function)
• not (function)
• nth-child (function)
• nth-last-child (function)
• only-child (function)
• root (function)

4.1.6 css-selectors/src/compile.lisp

Dependency

pseudo.lisp (file)

Parent

src (module)

Location

src/compile.lisp

Exported Definitions

• compile-css-node-matcher (function)
• node-matches? (compiler macro)
• node-matches? (function)
• query (compiler macro)
• query (function)
• query1 (compiler macro)
• query1 (function)

Internal Definitions

• %do-query (generic function)
• %node-matches? (function)
• %query (function)
• %query1 (function)
• *ignore-namespaces* (special variable)
• attrib-includes? (function)
• make-and-matcher (function)
• make-attrib-matcher (function)
• make-child-matcher (function)
• make-class-matcher (function)
• make-elt-matcher (function)
• make-hash-matcher (function)
• make-immediate-child-matcher (function)
• make-immediatly-preceded-by-matcher (function)
• make-matcher-aux (function)
• make-node-matcher (function)
• make-nth-pseudo-matcher (function)
• make-or-matcher (function)
• make-preceded-by-matcher (function)
• make-pseudo-matcher (function)

4.1.7 css-selectors/src/dom.lisp

Dependency

compile.lisp (file)

Parent

src (module)

Location

src/dom.lisp

Internal Definitions

• %do-query (method)
• child-elements (method)
• child-nodes (method)
• document-of (method)
• element-p (method)
• get-attribute (method)
• parent-node (method)
• previous-sibling (method)
• tag-name (method)

5 Packages

Packages are listed by definition order.

5.1 net.acceleration.css-selectors.system

Source

css-selectors.asd

Use List

• asdf/interface
• common-lisp

5.2 css-selectors.pseudo

Source

packages.lisp (file)

Nickname

pseudo

Use List

• common-lisp
• iterate
• css-selectors

Exported Definitions

• empty (function)
• first-child (function)
• has (function)
• is (function)
• last-child (function)
• not (function)
• nth-child (function)
• nth-last-child (function)
• only-child (function)
• root (function)

5.3 css-selectors

Source

packages.lisp (file)

Nickname

css

Use List

• iterate
• common-lisp

Used By List

css-selectors.pseudo

Exported Definitions

• compile-css-node-matcher (function)
• node-matches? (compiler macro)
• node-matches? (function)
• parse-results (function)
• query (compiler macro)
• query (function)
• query1 (compiler macro)
• query1 (function)

Internal Definitions

• %do-query (generic function)
• %do-query (method)
• %node-matches? (function)
• %query (function)
• %query1 (function)
• %rule (function)
• %rule-set (function)
• *css3-selector-parser* (special variable)
• *ignore-namespaces* (special variable)
• +common-white-space-trimbag+ (special variable)
• +css3-lex-productions+ (special variable)
• +end-of-defs+ (special variable)
• +option+ (special variable)
• +option-case-insensitive+ (special variable)
• +return-value+ (special variable)
• all-group-matches-as-string (function)
• arg-list-var-names (function)
• attrib-includes? (function)
• but-first (function)
• but-last (function)
• but-quotes (function)
• child-elements (generic function)
• child-elements (method)
• child-nodes (generic function)
• child-nodes (method)
• document-of (generic function)
• document-of (method)
• dos-safe-read-line (function)
• element-p (generic function)
• element-p (method)
• element-p (method)
• expand-return-value (function)
• get-attribute (generic function)
• get-attribute (method)
• handle-quoted-rules (function)
• is-special? (function)
• keywordize (function)
• lam (macro)
• lex-results (function)
• make-and-matcher (function)
• make-attrib-matcher (function)
• make-child-matcher (function)
• make-class-matcher (function)
• make-css3-lexer (function)
• make-elt-matcher (function)
• make-hash-matcher (function)
• make-immediate-child-matcher (function)
• make-immediatly-preceded-by-matcher (function)
• make-matcher-aux (function)
• make-node-matcher (function)
• make-nth-pseudo-matcher (function)
• make-or-matcher (function)
• make-preceded-by-matcher (function)
• make-pseudo-matcher (function)
• parent-element (generic function)
• parent-element (method)
• parent-elements (generic function)
• parent-elements (method)
• parent-node (generic function)
• parent-node (method)
• previous-sibling (generic function)
• previous-sibling (method)
• read-flex-file (function)
• replace-all (function)
• replace-expansions (function)
• rule (macro)
• rule-set (macro)
• string-upcase? (function)
• symbolize (function)
• tag-name (generic function)
• tag-name (method)
• til-open (function)
• trim-and-nullify (function)
• trim-whitespace (function)
• uniquify-and-reintern (function)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Compiler macros

Compiler Macro: node-matches? NODE INP

Package

css-selectors

Source

compile.lisp (file)

Compiler Macro: query INP &optional TREES

Package

css-selectors

Source

compile.lisp (file)

Compiler Macro: query1 INP &optional TREES

Package

css-selectors

Source

compile.lisp (file)

6.1.2 Functions

Function: compile-css-node-matcher INP

Given a string, returns a matcher-function of a single node that will tell you whether or not the node matches

Package

css-selectors

Source

compile.lisp (file)

Function: empty NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: first-child NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: has NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: is NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: last-child NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: node-matches? NODE INP

Given a node and a CSS selector, see if the given node matches that selector

Package

css-selectors

Source

compile.lisp (file)

Function: not NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: nth-child NODE MUL ADD

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: nth-last-child NODE MUL ADD

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: only-child NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

Function: parse-results &optional INP

Mostly used for debugging purposes

Takes a string CSS selector and turns it into an AST

Package

css-selectors

Source

parse.lisp (file)

Function: query INP &optional TREES

Given a css selector, attempt to find the matching nodes in the passed in dom-trees (defaults to the document)

Package

css-selectors

Source

compile.lisp (file)

Function: query1 INP &optional TREES

Given a css selector, attempt to find the first matching node in the passed in dom-trees (defaults to the document)

Package

css-selectors

Source

compile.lisp (file)

Function: root NODE &optional SUB-SEL-FUNCTION

Package

css-selectors.pseudo

Source

pseudo.lisp (file)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *css3-selector-parser*

Package

css-selectors

Source

parse.lisp (file)

Special Variable: *ignore-namespaces*

ignore tag name spaces when matching, for now the parser
doesnt support parsing namespaced tags, so lets ignore tag namespaces

Package

css-selectors

Source

compile.lisp (file)

Special Variable: +common-white-space-trimbag+

Package

css-selectors

Source

parse.lisp (file)

Special Variable: +css3-lex-productions+

Package

css-selectors

Source

parse.lisp (file)

Special Variable: +end-of-defs+

Package

css-selectors

Source

parse.lisp (file)

Special Variable: +option+

Package

css-selectors

Source

parse.lisp (file)

Special Variable: +option-case-insensitive+

Package

css-selectors

Source

parse.lisp (file)

Special Variable: +return-value+

Package

css-selectors

Source

parse.lisp (file)

6.2.2 Macros

Macro: lam ARGS &body BODY

Package

css-selectors

Source

parse.lisp (file)

Macro: rule ARGS &body BODY

Package

css-selectors

Source

parse.lisp (file)

Macro: rule-set NAME &body RULES

Package

css-selectors

Source

parse.lisp (file)

6.2.3 Functions

Function: %node-matches? NODE INP

Package

css-selectors

Source

compile.lisp (file)

Function: %query INP &optional TREES

Package

css-selectors

Source

compile.lisp (file)

Function: %query1 INP &optional TREES

Package

css-selectors

Source

compile.lisp (file)

Function: %rule ARGS BODY

Package

css-selectors

Source

parse.lisp (file)

Function: %rule-set NAME RULES

Package

css-selectors

Source

parse.lisp (file)

Function: all-group-matches-as-string REGEX TARGET

Expects a single matching group

Package

css-selectors

Source

parse.lisp (file)

Function: arg-list-var-names ARGS

Package

css-selectors

Source

parse.lisp (file)

Function: attrib-includes? NODE ATTRIB VALUE

Package

css-selectors

Source

compile.lisp (file)

Function: but-first S

Package

css-selectors

Source

parse.lisp (file)

Function: but-last S

Package

css-selectors

Source

parse.lisp (file)

Function: but-quotes S

Package

css-selectors

Source

parse.lisp (file)

Function: dos-safe-read-line STREAM &optional EOF-ERROR-P EOF-VALUE RECURSIVE-P

readline that can read unix or dos lines

Package

css-selectors

Source

parse.lisp (file)

Function: expand-return-value RTN

Package

css-selectors

Source

parse.lisp (file)

Function: handle-quoted-rules PRODUCTION

quotes in flex productions should be direct string matches

Package

css-selectors

Source

parse.lisp (file)

Function: is-special? S

Package

css-selectors

Source

parse.lisp (file)

Function: keywordize S

Package

css-selectors

Source

parse.lisp (file)

Function: lex-results &optional INP

Package

css-selectors

Source

parse.lisp (file)

Function: make-and-matcher FORMS

Package

css-selectors

Source

compile.lisp (file)

Function: make-attrib-matcher ATTRIB MATCH-TYPE MATCH-TO

attrib-matcher

Package

css-selectors

Source

compile.lisp (file)

Function: make-child-matcher PARENT-MATCHER CHILD-MATCHER

Package

css-selectors

Source

compile.lisp (file)

Function: make-class-matcher CLASS

Package

css-selectors

Source

compile.lisp (file)

Function: make-css3-lexer INP

Package

css-selectors

Source

parse.lisp (file)

Function: make-elt-matcher TAG

Package

css-selectors

Source

compile.lisp (file)

Function: make-hash-matcher ID

Package

css-selectors

Source

compile.lisp (file)

Function: make-immediate-child-matcher PARENT-MATCHER CHILD-MATCHER

Package

css-selectors

Source

compile.lisp (file)

Function: make-immediatly-preceded-by-matcher THIS-MATCHER SIBLING-MATCHER

Package

css-selectors

Source

compile.lisp (file)

Function: make-matcher-aux TREE

Package

css-selectors

Source

compile.lisp (file)

Function: make-node-matcher EXPRESSION

Package

css-selectors

Source

compile.lisp (file)

Function: make-nth-pseudo-matcher PSEUDO MUL ADD

Package

css-selectors

Source

compile.lisp (file)

Function: make-or-matcher FORMS

Package

css-selectors

Source

compile.lisp (file)

Function: make-preceded-by-matcher THIS-MATCHER SIBLING-MATCHER

Package

css-selectors

Source

compile.lisp (file)

Function: make-pseudo-matcher PSEUDO SUBMATCHER

Package

css-selectors

Source

compile.lisp (file)

Function: read-flex-file FILE &aux CI? DEFS DONE-WITH-DEFS?

Package

css-selectors

Source

parse.lisp (file)

Function: replace-all STRING PART REPLACEMENT &key TEST STREAM

Returns a new string in which all the occurences of the part
is replaced with replacement. [FROM http://cl-cookbook.sourceforge.net/strings.html#manip]

Package

css-selectors

Source

parse.lisp (file)

Function: replace-expansions DEFS NEW-REGEX

Package

css-selectors

Source

parse.lisp (file)

Function: string-upcase? S

Package

css-selectors

Source

parse.lisp (file)

Function: symbolize S

Package

css-selectors

Source

parse.lisp (file)

Function: til-open S

Package

css-selectors

Source

parse.lisp (file)

Function: trim-and-nullify S

trims the whitespace from a string returning nil
if trimming produces an empty string or the string ’nil’

Package

css-selectors

Source

parse.lisp (file)

Function: trim-whitespace S

Package

css-selectors

Source

parse.lisp (file)

Function: uniquify-and-reintern X &optional PACKAGE

Package

css-selectors

Source

parse.lisp (file)

6.2.4 Generic functions

Generic Function: %do-query MATCHER NODE &key FIRST?

matches selector inp against the node
if first? is T then return the first matching node

Package

css-selectors

Source

compile.lisp (file)

Methods

Method: %do-query MATCHER (ELT node) &key FIRST?

Source

dom.lisp (file)

Generic Function: child-elements NODE

Returns all child elements of this node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: child-elements (N node)

Source

dom.lisp (file)

Generic Function: child-nodes NODE

Returns all child nodes of this node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: child-nodes (N node)

Source

dom.lisp (file)

Generic Function: document-of NODE

Returns the document of the given node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: document-of (N node)

Source

dom.lisp (file)

Generic Function: element-p NODE

Is this an element

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: element-p (ELT element)

Source

dom.lisp (file)

Method: element-p ELT

Generic Function: get-attribute NODE ATTRIB

retrieves the value of a given attribute of the node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: get-attribute (ELT element) ATTRIB

Source

dom.lisp (file)

Generic Function: parent-element NODE

returns the parent element of this node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: parent-element N

Generic Function: parent-elements NODE

Returns all parent elements of this node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: parent-elements NODE

Generic Function: parent-node NODE

returns the parent node of this node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: parent-node (N node)

Source

dom.lisp (file)

Generic Function: previous-sibling NODE

returns the parent element of this node

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: previous-sibling (N element)

gets the parent dom:element (rather than ever returning the document node)

Source

dom.lisp (file)

Generic Function: tag-name ELT

retrieves the name of the given element

Package

css-selectors

Source

node-api.lisp (file)

Methods

Method: tag-name (ELT element)

Source

dom.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types