The clss Reference Manual

Table of Contents

The clss Reference Manual

This is the clss Reference Manual, version 0.3.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:39:55 2021 GMT+0.

1 Introduction

About CLSS

CLSS is a DOM traversal engine based on CSS selectors. It makes use of the Plump-DOM and is used by lQuery.

How To

Load CLSS through Quicklisp or ASDF:

(ql:quickload :clss)

Using a standard CSS selector you can retrieve a vector of nodes from the DOM:

(clss:select "img" (plump:parse "<div><p>A beautiful image: <img src="//example.com/image.png" alt="image" /></p></div>"))

CLSS implements Level 3 selectors and offers most of the features from the spec. Some things were left out as they make no sense outside a CSS context. As Plump supports XML as well as HTML, it also includes special handling for a few nodes that are not elements and are thus not reachable by standard CSS selectors. In order to solve this problem, CLSS adds an extra operator, the ^ caret. The caret is followed by a Plump-DOM class-name and will then match any elements that conform to a typep test against it.

(clss:select "^CDATA" (plump:parse "<foo><![CDATA[bar]]></foo>"))

CSS selectors in themselves also don't support XML namespaces due to the ambiguity arising with pseudo-selectors. CLSS solves this by interpreting a double colon as a name. Thus, a tag with the name of foo:bar is selected by foo::bar.

CLSS attempts to be a fast engine and various parts of it have been tuned for this purpose, which limits the extensibility of CLSS a bit. However, it is still possible to f.e. programmatically construct a selector.

Extending CLSS

Using define-pseudo-selector you can add your own extensions to CLSS:

(clss:define-pseudo-selector outside-link (node)
  (let ((href (plump:attribute node "href")))
    (and href (cl-ppcre:scan "^(http|https)://" href))))

(clss:select "a:outside-link" (plump:parse "<foo><a href=\"/baloney\"/><a href=\"http://example.com\"/></foo>"))

2 Systems

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

2.1 clss

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://shinmera.github.io/CLSS/

Source Control

(:git "https://github.com/shinmera/clss.git")

Bug Tracker

https://github.com/Shinmera/CLSS/issues

License

zlib

Description

A DOM tree searching engine based on CSS selectors.

Version

0.3.1

Dependencies

• array-utils
• plump

Source

clss.asd (file)

Components

• package.lisp (file)
• selector.lisp (file)
• parser.lisp (file)
• engine.lisp (file)
• pseudo-selectors.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 clss.asd

Location

clss.asd

Systems

clss (system)

3.1.2 clss/package.lisp

Parent

clss (system)

Location

package.lisp

Packages

clss

3.1.3 clss/selector.lisp

Dependency

package.lisp (file)

Parent

clss (system)

Location

selector.lisp

Exported Definitions

• make-any-constraint (function)
• make-attribute-constraint (function)
• make-class-constraint (function)
• make-clss-matcher (function)
• make-id-constraint (function)
• make-pseudo-constraint (function)
• make-selector (function)
• make-tag-constraint (function)
• make-type-constraint (function)

Internal Definitions

make-group (function)

3.1.4 clss/parser.lisp

Dependency

selector.lisp (file)

Parent

clss (system)

Location

parser.lisp

Exported Definitions

parse-selector (function)

Internal Definitions

• *valid-combinators* (special variable)
• ensure-selector (function)
• read-any-constraint (function)
• read-attribute-comparator (function)
• read-attribute-constraint (function)
• read-attribute-value (function)
• read-class-constraint (function)
• read-combinator (function)
• read-constraint (function)
• read-group (function)
• read-id-constraint (function)
• read-matcher (function)
• read-name (function)
• read-pseudo-args (function)
• read-pseudo-constraint (function)
• read-selector (function)
• read-tag-constraint (function)
• read-type-constraint (function)

3.1.5 clss/engine.lisp

Dependency

parser.lisp (file)

Parent

clss (system)

Location

engine.lisp

Exported Definitions

• define-pseudo-selector (macro)
• match-constraint (function)
• match-group (function)
• match-group-backwards (function)
• match-matcher (function)
• match-selector (function)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• node-matches-p (compiler macro)
• node-matches-p (function)
• pseudo-selector (function)
• (setf pseudo-selector) (function)
• pseudo-selector-not-available (condition)
• remove-pseudo-selector (function)
• select (compiler macro)
• select (function)
• selector (method)
• (setf selector) (method)
• selector-malformed (condition)
• undefined-pseudo-selector (condition)

Internal Definitions

• *pseudo-selectors* (special variable)
• complete-match-pair (condition)
• find-substring (function)
• match-pair-breadth (function)
• match-pair-depth (function)
• value (method)
• (setf value) (method)

3.1.6 clss/pseudo-selectors.lisp

Dependency

engine.lisp (file)

Parent

clss (system)

Location

pseudo-selectors.lisp

Internal Definitions

match-nth (function)

4 Packages

Packages are listed by definition order.

4.1 clss

Source

package.lisp (file)

Nickname

org.shirakumo.clss

Use List

• plump
• common-lisp

Exported Definitions

• define-pseudo-selector (macro)
• make-any-constraint (function)
• make-attribute-constraint (function)
• make-class-constraint (function)
• make-clss-matcher (function)
• make-id-constraint (function)
• make-pseudo-constraint (function)
• make-selector (function)
• make-tag-constraint (function)
• make-type-constraint (function)
• match-constraint (function)
• match-group (function)
• match-group-backwards (function)
• match-matcher (function)
• match-selector (function)
• name (generic function)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• node-matches-p (compiler macro)
• node-matches-p (function)
• parse-selector (function)
• pseudo-selector (function)
• (setf pseudo-selector) (function)
• pseudo-selector-not-available (condition)
• remove-pseudo-selector (function)
• select (compiler macro)
• select (function)
• selector (generic function)
• selector (method)
• (setf selector) (method)
• (setf selector) (generic function)
• selector-malformed (condition)
• undefined-pseudo-selector (condition)

Internal Definitions

• *pseudo-selectors* (special variable)
• *valid-combinators* (special variable)
• complete-match-pair (condition)
• ensure-selector (function)
• find-substring (function)
• make-group (function)
• match-nth (function)
• match-pair-breadth (function)
• match-pair-depth (function)
• read-any-constraint (function)
• read-attribute-comparator (function)
• read-attribute-constraint (function)
• read-attribute-value (function)
• read-class-constraint (function)
• read-combinator (function)
• read-constraint (function)
• read-group (function)
• read-id-constraint (function)
• read-matcher (function)
• read-name (function)
• read-pseudo-args (function)
• read-pseudo-constraint (function)
• read-selector (function)
• read-tag-constraint (function)
• read-type-constraint (function)
• value (generic function)
• value (method)
• (setf value) (method)
• (setf value) (generic function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: define-pseudo-selector NAME (NODENAME &rest ARGS-LAMBDA) &body BODY

Define a new pseudo-selector of NAME.

NAME — A symbol or string naming the selector (case insensitive always). NODENAME — A variable symbol the matched node is bound to.
ARGS-LAMBDA — A lambda-list of the expected arguments for the pseudo-selector. Note that keyword arguments make no sense in this context. BODY ::= form*

Package

clss

Source

engine.lisp (file)

5.1.2 Compiler macros

Compiler Macro: node-matches-p SELECTOR ROOT-NODE

Package

clss

Source

engine.lisp (file)

Compiler Macro: select SELECTOR ROOT-NODE &optional SEARCH-TYPE

Package

clss

Source

engine.lisp (file)

5.1.3 Functions

Function: make-any-constraint ()

Package

clss

Source

selector.lisp (file)

Function: make-attribute-constraint ATTRIBUTE &optional VALUE COMPARATOR

Package

clss

Source

selector.lisp (file)

Function: make-class-constraint CLASS

Package

clss

Source

selector.lisp (file)

Function: make-clss-matcher &rest CONSTRAINTS

Package

clss

Source

selector.lisp (file)

Function: make-id-constraint ID

Package

clss

Source

selector.lisp (file)

Function: make-pseudo-constraint FUNCTION &rest ARGS

Package

clss

Source

selector.lisp (file)

Function: make-selector &rest GROUPS

Package

clss

Source

selector.lisp (file)

Function: make-tag-constraint TAG

Package

clss

Source

selector.lisp (file)

Function: make-type-constraint NAME

Package

clss

Source

selector.lisp (file)

Function: match-constraint CONSTRAINT NODE

Attempts to match the CONSTRAINT form against the node. Returns NIL if it fails to do so, unspecified otherwise.

Package

clss

Source

engine.lisp (file)

Function: match-group GROUP ROOT-NODE &optional SEARCH-TYPE

Match a matcher group against the root-node and possibly all its children. Returns an array of mached nodes.

Package

clss

Source

engine.lisp (file)

Function: match-group-backwards GROUP NODE

Package

clss

Source

engine.lisp (file)

Function: match-matcher MATCHER NODE

Attempts to match a matcher against a node. Returns T if all constraints match, NIL otherwise.

Package

clss

Source

engine.lisp (file)

Function: match-selector SELECTOR ROOT-NODE SEARCH-TYPE

Match a selector against the root-node and possibly all its children. Returns an array of matched nodes.

Package

clss

Source

engine.lisp (file)

Function: node-matches-p SELECTOR NODE

Tests whether the node matches the selector.

SELECTOR — A CSS-selector string or a compiled selector list. NODE — The node to test.

Package

clss

Source

engine.lisp (file)

Function: parse-selector STRING

Parse a selector string into its "compiled" list form.

Package

clss

Source

parser.lisp (file)

Function: pseudo-selector NAME

Returns the pseudo-selector function associated with NAME, if any.

Package

clss

Source

engine.lisp (file)

Writer

(setf pseudo-selector) (function)

Function: (setf pseudo-selector) FUNCTION NAME

Sets FUNCTION as the pseudo-selector for NAME.

Package

clss

Source

engine.lisp (file)

Reader

pseudo-selector (function)

Function: remove-pseudo-selector NAME

Removes the pseudo-selector associated with NAME.

Package

clss

Source

engine.lisp (file)

Function: select SELECTOR ROOT-NODE &optional SEARCH-TYPE

Match the given selector against the root-node and possibly all its children.
Returns an array of matched nodes.

SELECTOR — A CSS-selector string or a compiled selector list.
ROOT-NODE — A single node, list or vector of nodes to start matching from. SEARCH-TYPE — Select the search algorithm, options are ":depth-first" and ":breadth-first".

Package

clss

Source

engine.lisp (file)

5.1.4 Generic functions

Generic Function: name CONDITION

Generic Function: (setf name) NEW-VALUE CONDITION

Package

clss

Methods

Method: name (CONDITION undefined-pseudo-selector)

Method: (setf name) NEW-VALUE (CONDITION undefined-pseudo-selector)

Source

engine.lisp (file)

Method: name (CONDITION pseudo-selector-not-available)

Method: (setf name) NEW-VALUE (CONDITION pseudo-selector-not-available)

Source

engine.lisp (file)

Generic Function: selector CONDITION

Generic Function: (setf selector) NEW-VALUE CONDITION

Package

clss

Methods

Method: selector (CONDITION selector-malformed)

Method: (setf selector) NEW-VALUE (CONDITION selector-malformed)

Source

engine.lisp (file)

5.1.5 Conditions

Condition: pseudo-selector-not-available ()

Condition signalled when a pseudo selector is defined according to spec, but makes no sense in the context of CLSS and has thus been left unimplemented.

Package

clss

Source

engine.lisp (file)

Direct superclasses

error (condition)

Direct methods

• name (method)
• name (method)

Direct slots

Slot: %name

Initargs

:name

Initform

(quote (error "name required."))

Readers

name (generic function)

Writers

(setf name) (generic function)

Condition: selector-malformed ()

Signalled when a selector or matcher has been found to be malformed. This really shouldn’t happen unless you’re passing raw lists
for the selector to the matcher.

Package

clss

Source

engine.lisp (file)

Direct superclasses

error (condition)

Direct methods

• selector (method)
• selector (method)

Direct slots

Slot: %selector

Initargs

:selector

Initform

(quote (error "selector malformed."))

Readers

selector (generic function)

Writers

(setf selector) (generic function)

Condition: undefined-pseudo-selector ()

Condition signalled when trying to use a pseudo selector that has not been defined. This is signalled at match-time, rather than at selector-compile-time.

Package

clss

Source

engine.lisp (file)

Direct superclasses

error (condition)

Direct methods

• name (method)
• name (method)

Direct slots

Slot: %name

Initargs

:name

Initform

(quote (error "name required."))

Readers

name (generic function)

Writers

(setf name) (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *pseudo-selectors*

Hash table for pseudo selector functions.
Links string names to functions of one or more arguments.

Package

clss

Source

engine.lisp (file)

Special Variable: *valid-combinators*

Package

clss

Source

parser.lisp (file)

5.2.2 Functions

Function: ensure-selector THING

Package

clss

Source

parser.lisp (file)

Function: find-substring ITEM STRING SPLIT

Returns ITEM if it is an element of STRING split by the SPLIT character.

Package

clss

Source

engine.lisp (file)

Function: make-group &rest MATCHES-AND-OPS

Package

clss

Source

selector.lisp (file)

Function: match-nth I N

Package

clss

Source

pseudo-selectors.lisp (file)

Function: match-pair-breadth COMBINATOR MATCHER NODES

Match a combinator and matcher pair against a list of nodes. Returns a vector of matching nodes.

Package

clss

Source

engine.lisp (file)

Function: match-pair-depth COMBINATOR MATCHER PARENT MATCHING-NODES-PROCESSOR

Match a combinator and matcher pair against a list of nodes. For every match the function specified in "MATCHING-NODES-PROCESSOR" is called with the found match as the only argument.

Package

clss

Source

engine.lisp (file)

Function: read-any-constraint ()

Reads an any constraint and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-attribute-comparator ()

Reads an attribute comparator string and returns it if found.

Package

clss

Source

parser.lisp (file)

Function: read-attribute-constraint ()

Reads a complete attribute constraint and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-attribute-value ()

Reads an attribute value and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-class-constraint ()

Reads a class constraint and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-combinator ()

Reads the combinator between matchers and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-constraint ()

Read any constraint. Dispatches depending on the next character consumed.

Package

clss

Source

parser.lisp (file)

Function: read-group ()

Reads a selector group and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-id-constraint ()

Reads an ID attribute constraint and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-matcher ()

Read a matcher (a sequence of constraints) and return it.

Package

clss

Source

parser.lisp (file)

Function: read-name ()

Reads a CSS selector name-like string.

Package

clss

Source

parser.lisp (file)

Function: read-pseudo-args ()

Reads an arguments list of a pseudo selector.

Package

clss

Source

parser.lisp (file)

Function: read-pseudo-constraint ()

Reads a complete pseudo constraint and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-selector ()

Reads a complete selector and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-tag-constraint ()

Reads a tag constraint and returns it.

Package

clss

Source

parser.lisp (file)

Function: read-type-constraint ()

Reads a DOM type constraint and returns it.

Package

clss

Source

parser.lisp (file)

5.2.3 Generic functions

Generic Function: value CONDITION

Generic Function: (setf value) NEW-VALUE CONDITION

Package

clss

Methods

Method: value (CONDITION complete-match-pair)

Method: (setf value) NEW-VALUE (CONDITION complete-match-pair)

Source

engine.lisp (file)

5.2.4 Conditions

Condition: complete-match-pair ()

Condition signalled to immediately return from MATCH-PAIR.

Package

clss

Source

engine.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• value (method)
• value (method)

Direct slots

Slot: %value

Initargs

:value

Initform

(quote nil)

Readers

value (generic function)

Writers

(setf value) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types