The clss Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The clss Reference Manual

This is the clss Reference Manual, version 0.3.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:35:32 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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>"))

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 clss

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

License

Artistic

Description

A DOM tree searching engine based on CSS selectors.

Version

0.3.1

Dependencies
Source

clss.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 clss.asd

Location

clss.asd

Systems

clss (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 clss/package.lisp

Parent

clss (system)

Location

package.lisp

Packages

clss


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 clss/selector.lisp

Dependency

package.lisp (file)

Parent

clss (system)

Location

selector.lisp

Exported Definitions
Internal Definitions

make-group (function)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 clss/parser.lisp

Dependency

selector.lisp (file)

Parent

clss (system)

Location

parser.lisp

Exported Definitions

parse-selector (function)

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 clss/engine.lisp

Dependency

parser.lisp (file)

Parent

clss (system)

Location

engine.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.6 clss/pseudo-selectors.lisp

Dependency

engine.lisp (file)

Parent

clss (system)

Location

pseudo-selectors.lisp

Internal Definitions

match-nth (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 clss

Source

package.lisp (file)

Nickname

org.shirakumo.clss

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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
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)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
clss.asd: The clss<dot>asd file
clss/engine.lisp: The clss/engine<dot>lisp file
clss/package.lisp: The clss/package<dot>lisp file
clss/parser.lisp: The clss/parser<dot>lisp file
clss/pseudo-selectors.lisp: The clss/pseudo-selectors<dot>lisp file
clss/selector.lisp: The clss/selector<dot>lisp file

F
File, Lisp, clss.asd: The clss<dot>asd file
File, Lisp, clss/engine.lisp: The clss/engine<dot>lisp file
File, Lisp, clss/package.lisp: The clss/package<dot>lisp file
File, Lisp, clss/parser.lisp: The clss/parser<dot>lisp file
File, Lisp, clss/pseudo-selectors.lisp: The clss/pseudo-selectors<dot>lisp file
File, Lisp, clss/selector.lisp: The clss/selector<dot>lisp file

L
Lisp File, clss.asd: The clss<dot>asd file
Lisp File, clss/engine.lisp: The clss/engine<dot>lisp file
Lisp File, clss/package.lisp: The clss/package<dot>lisp file
Lisp File, clss/parser.lisp: The clss/parser<dot>lisp file
Lisp File, clss/pseudo-selectors.lisp: The clss/pseudo-selectors<dot>lisp file
Lisp File, clss/selector.lisp: The clss/selector<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   D   E   F   G   M   N   P   R   S   V  
Index Entry  Section

(
(setf name): Exported generic functions
(setf name): Exported generic functions
(setf name): Exported generic functions
(setf pseudo-selector): Exported functions
(setf selector): Exported generic functions
(setf selector): Exported generic functions
(setf value): Internal generic functions
(setf value): Internal generic functions

C
Compiler Macro, node-matches-p: Exported compiler macros
Compiler Macro, select: Exported compiler macros

D
define-pseudo-selector: Exported macros

E
ensure-selector: Internal functions

F
find-substring: Internal functions
Function, (setf pseudo-selector): Exported functions
Function, ensure-selector: Internal functions
Function, find-substring: Internal functions
Function, make-any-constraint: Exported functions
Function, make-attribute-constraint: Exported functions
Function, make-class-constraint: Exported functions
Function, make-clss-matcher: Exported functions
Function, make-group: Internal functions
Function, make-id-constraint: Exported functions
Function, make-pseudo-constraint: Exported functions
Function, make-selector: Exported functions
Function, make-tag-constraint: Exported functions
Function, make-type-constraint: Exported functions
Function, match-constraint: Exported functions
Function, match-group: Exported functions
Function, match-group-backwards: Exported functions
Function, match-matcher: Exported functions
Function, match-nth: Internal functions
Function, match-pair-breadth: Internal functions
Function, match-pair-depth: Internal functions
Function, match-selector: Exported functions
Function, node-matches-p: Exported functions
Function, parse-selector: Exported functions
Function, pseudo-selector: Exported functions
Function, read-any-constraint: Internal functions
Function, read-attribute-comparator: Internal functions
Function, read-attribute-constraint: Internal functions
Function, read-attribute-value: Internal functions
Function, read-class-constraint: Internal functions
Function, read-combinator: Internal functions
Function, read-constraint: Internal functions
Function, read-group: Internal functions
Function, read-id-constraint: Internal functions
Function, read-matcher: Internal functions
Function, read-name: Internal functions
Function, read-pseudo-args: Internal functions
Function, read-pseudo-constraint: Internal functions
Function, read-selector: Internal functions
Function, read-tag-constraint: Internal functions
Function, read-type-constraint: Internal functions
Function, remove-pseudo-selector: Exported functions
Function, select: Exported functions

G
Generic Function, (setf name): Exported generic functions
Generic Function, (setf selector): Exported generic functions
Generic Function, (setf value): Internal generic functions
Generic Function, name: Exported generic functions
Generic Function, selector: Exported generic functions
Generic Function, value: Internal generic functions

M
Macro, define-pseudo-selector: Exported macros
make-any-constraint: Exported functions
make-attribute-constraint: Exported functions
make-class-constraint: Exported functions
make-clss-matcher: Exported functions
make-group: Internal functions
make-id-constraint: Exported functions
make-pseudo-constraint: Exported functions
make-selector: Exported functions
make-tag-constraint: Exported functions
make-type-constraint: Exported functions
match-constraint: Exported functions
match-group: Exported functions
match-group-backwards: Exported functions
match-matcher: Exported functions
match-nth: Internal functions
match-pair-breadth: Internal functions
match-pair-depth: Internal functions
match-selector: Exported functions
Method, (setf name): Exported generic functions
Method, (setf name): Exported generic functions
Method, (setf selector): Exported generic functions
Method, (setf value): Internal generic functions
Method, name: Exported generic functions
Method, name: Exported generic functions
Method, selector: Exported generic functions
Method, value: Internal generic functions

N
name: Exported generic functions
name: Exported generic functions
name: Exported generic functions
node-matches-p: Exported compiler macros
node-matches-p: Exported functions

P
parse-selector: Exported functions
pseudo-selector: Exported functions

R
read-any-constraint: Internal functions
read-attribute-comparator: Internal functions
read-attribute-constraint: Internal functions
read-attribute-value: Internal functions
read-class-constraint: Internal functions
read-combinator: Internal functions
read-constraint: Internal functions
read-group: Internal functions
read-id-constraint: Internal functions
read-matcher: Internal functions
read-name: Internal functions
read-pseudo-args: Internal functions
read-pseudo-constraint: Internal functions
read-selector: Internal functions
read-tag-constraint: Internal functions
read-type-constraint: Internal functions
remove-pseudo-selector: Exported functions

S
select: Exported compiler macros
select: Exported functions
selector: Exported generic functions
selector: Exported generic functions

V
value: Internal generic functions
value: Internal generic functions

Jump to:   (  
C   D   E   F   G   M   N   P   R   S   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %   *  
S  
Index Entry  Section

%
%name: Exported conditions
%name: Exported conditions
%selector: Exported conditions
%value: Internal conditions

*
*pseudo-selectors*: Internal special variables
*valid-combinators*: Internal special variables

S
Slot, %name: Exported conditions
Slot, %name: Exported conditions
Slot, %selector: Exported conditions
Slot, %value: Internal conditions
Special Variable, *pseudo-selectors*: Internal special variables
Special Variable, *valid-combinators*: Internal special variables

Jump to:   %   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   U  
Index Entry  Section

C
clss: The clss system
clss: The clss package
complete-match-pair: Internal conditions
Condition, complete-match-pair: Internal conditions
Condition, pseudo-selector-not-available: Exported conditions
Condition, selector-malformed: Exported conditions
Condition, undefined-pseudo-selector: Exported conditions

P
Package, clss: The clss package
pseudo-selector-not-available: Exported conditions

S
selector-malformed: Exported conditions
System, clss: The clss system

U
undefined-pseudo-selector: Exported conditions

Jump to:   C   P   S   U