selector
is a CSS selector parsing/generation/construction library.
npm install @hgargg-0710/selector
The following is the precise description of the library's exports (v0.1).
parse
(function)generate
(function)parser
(submodule)generator
(submodule)tokens
(submodule)tree
(submodule)
NOTE: it is built on top of the parsers.js
library for parser-making,
so some of the terminology comes from there.
This is one of the two primary functions of the library.
Given a string
with a syntactically correct CSS selector, it returns
an Abstract Syntax Tree constructed using the library's AST API.
function parse(selector: string): Combinator | CompoundSelector | SelectorList
The result of parse
can later be passed to generate
to reverse the parsing operation.
An inverse of parse
. Provided an AST constructed with the usage of library's API,
returns a string
.
function generate(selector: Combinator | CompoundSelector | SelectorList): string
Funny note: the combination generate(parse(selector))
can be used as a kind of generally-inneficient-but-easy-to-make-with-the-library selector-formatter...
This is a submodule, including all the exports of the parsing-dedicated modules.
In particular, the mult-layered parse
function is composed of the contents of the module. It also provides the parse
function as the export (aliased as SelectorParser
).
The layers of parsing of a selector employed by the library are (in order of their application):
char
(tokenization)escaped
(escaped sequences)string
(string character sequences)bracket
(identifying of sub-selectors)list
(identifying of selector-lists)simple
(finalization of simple selectors)attribute
(parsing of attribute selectors)identifier
(parsing of identifiers - key elements of all simple selectors)
compound
(uniting simple selectors into compound ones)despace
(elimination of undesired space tokens to simplify further descendant combinator identification)combinator
(identifies combinators, and orders thecompound
results based on them)
The parser
module exports are broken down into these submodules, which are the immidiate exports.
What follows is the enumeration of different submodules' exports and their meanings/uses within the parser.
export | description |
---|---|
SelectorTokenizer |
The tokenization function (a PatternTokenizer ). Accepts a Pattern<string, RegExp, RegExp> (example: StringPattern ). Returns a PatternCollection |
charMap |
The IndexMap , on which the SelectorTokenizer is based. Keys are regular expressions, values - TokenType s corresponding to them |
export | description |
---|---|
EscapeParser |
The main parsing function. Accepts Stream , returns an array. Converts Escape followed by something else into appropriate Escaped |
isHex |
Checks whether the given string tests positive against /[0-9a-fA-F]/ |
readHex |
Reads a hexidecimal from the given stream (up to 6 characters), altering the Stream passed |
readEscaped |
Reads a single character from a given Stream , altering it |
HandleEscaped |
Main handler for the Escape token within the escapeMap IndexMap |
escapedMap |
The TypeMap , on which the EscapeParser is based |
export | description |
---|---|
SelectorStringParser |
The main parsing function. Accepts Stream , returns an array. Converts token sequences between pairs of " or ' to SelectorString tokens. Happens after Escaped |
StringCharacterParser |
Converts a given Stream , which is a result of limiting another Stream to an array, in which SelectorSymbols were grouped into StringCharacters |
quoteRead |
An object containing cached functions for reading a string starting with ' and " respectively |
readUntilEscaped |
Reads from a given Stream , altering it, until an Escaped is met |
stringMap |
A TypeMap , on which the SelectorStringParser is based |
stringCharMap |
A TypeMap , on which the SelectorCharacterParser is based |
export | description |
---|---|
EndParser |
The "latter" part of the parse function. It unites BracketParser , list , simple , compound , despace and combinator . It also deals with recursive brackets |
SelectorListParser |
Accepts Stream , puts the input through BracketParser and SelectorCommaParser (from list ). |
BracketParser |
Recursively applies EndParser on all encountered sub-selectors within the passed Stream . |
recursiveBracketParser |
The recursive component of the EndParser |
flatBracketParser |
The finite ("flat", non-recursive) component of the EndParser |
SubSelectorHandler |
The handler of sub-selectors within the subSelectorMap |
nestedBrack |
Returns the nested limitation of the given Stream to cover the entirety of the current sub-selector |
subSelectorMap |
The TypeMap , on which the BracketMap is based |
export | description |
---|---|
SelectorCommaParser |
Breaks all the pieces of parsed Stream into arrays and eliminates all Comma s |
export | description |
---|---|
SimpleSelectorParser |
The main simple selectors' parser. Takes a Stream , returns an array of transformed tokens |
HandleElement |
Handles an element selector |
HandleId |
Handles an id selector |
HandleClass |
Handles a class selector |
HandleAttribute |
Handles an attribute selector |
HandlePseudoClass |
Handles a pseudo-class selector |
HandlePseudoElement |
Handles a pseudo-element selector |
HandleUniversal |
Handles a universal selector |
HandleParent |
Handles a parent selector |
readSimple |
Reads an identifier, optionally skipping an element of the passed Stream . Sub-routine used for defining some of the handlers |
simpleMap |
The TypeMap , on which the SimpleSelectorParser is based. |
export | description |
---|---|
AttributeParser |
The BasicParser for parsing attribute selectors. |
AttributeHandler |
Handler for attribute selectors. |
attributeMap |
The TypeMap , on which AttributeParser is based |
export | description |
---|---|
IdentifierParser |
Takes in an array of tokens, returns a SelectorIdentifier . Parser for Identifiers |
readSymbol |
Reads from a Stream for as long as its current symbol is a SelectorSymbol |
limitPartial |
Limits a given Stream , and moves it, to the point where the next identifier ends. Returns the limited portion. |
parseIdentifier |
Parses the identifier (a global sub-routine utilizing the IdentifierParser and limitPartial ) |
identifierMap |
A TypeMap , on which the IdentifierParser is based. |
export | description |
---|---|
CompoundSelectorParser |
Main parsing function. Combines different simple selectors into CompoundSelector s |
CompoundHandler |
The handler for simple selectors |
compoundMap |
The TypeMap , on which CompoundSelectorParser is based |
export | description |
---|---|
DeSpacer |
Replaces sequences of Space tokens with a single one. |
DeSpace |
The handler of Space |
despaceMap |
The TypeMap , off which DeSpacer is based |
skipSpaces |
Skips spaces within the given Stream |
export | description |
---|---|
SelectorCombinatorParser |
Structures compound selectors together using combinators. The main parser function of the module |
HandleCombinator |
Combinator handler. |
HandleCompound |
Compound handler. |
combinatorMap |
TypeMap , off which the SelectorCombinatorParser is based |
This module provides functions for generation of selectors, relating to different package's AST-belonging tokens. In particular, it includes the generate
function as an export (aliased as SelectorGenerator
).
The abstractions work primarily with Stream
s , including those based off trees provided by the tree
submodule.
export | description |
---|---|
SelectorGenerator |
The generate function |
GenerateCombinator |
Generates the Combinator selector |
GeneratePseudoClass |
Generates the pseudo-class selector |
GenerateAttribute |
Generates the attribute selector |
GenerateCompound |
Generates the compound selector |
GenerateElement |
Generates the element selector |
GenerateId |
Generates the id selector |
GenerateClass |
Generates the class selector |
GeneratePseudoElement |
Generates the pseudo-element selector |
GenerateCharacters |
Generates the characters (those are StringCharacters and IdentifierCharacters ) |
GenerateEscaped |
Generates the Escaped |
GenerateChildCombinator |
Generates the child combinator (> ) |
GenerateDescendantCombinator |
Generates the descendant combinator ( ) |
GenerateNextSiblingCombinator |
Generates the next sibling combinator (+ ) |
GenerateNamespaceCombinator |
Generates the namespace combinator (| ) |
GenerateSubseqSibilngCombinator |
Generates the subsequent sibling combinator (~ ) |
GenerateEndsWithMatch |
Generates the ends-with match $= |
GenerateIncludesMatch |
Generates the includes match ~= |
GenerateHyphBeginMatch |
Generates the hyphen-begin match |= |
GeneratePrefixMatch |
Generates the prefix match ^= |
GenerateFindMatch |
Generates the find match *= |
GenerateEqualityMatch |
Generates the equality match = |
GenerateUniversalSelector |
Generates the universal selector * |
GenerateParentSelector |
Generates the parent selector & |
GenerateString |
Generates a string (note: preserves the quotes used - either ' , or " ) |
GenerateSubSelector |
Generates a sub-selector |
GenerateSelectorList |
Generates a selector-list |
GenerateIdentifier |
Generates an identifier |
SelectorSourceGenerator |
The SourceGenerator , on which the generate function is based off |
generatorMap |
The TypeMap , on which the SelectorSourceGenerator is based off |
Provides exports related to TreeStream
-building based off the parser
-created AST
.
export | description |
---|---|
SelectorStream |
A function accepting the library's AST (result of parse , for instance), and transforming it into a Stream |
SelectorTree |
The default export of the submodule. Converts the given library's AST into a tree that can be put through TreeStream to make a Stream (on it, teh SelectorStream is based) |
SimpleTree |
Like others below, a function for transforming a node of an AST into a TreeStream argument. Converts the .value to the tree, and makes [.value] the children array |
ChildlessTree |
The tree without children |
ValueTree |
The tree in which .value is the .children |
AttributeTree |
The function that transforms an SelectorAttribute into a tree |
PseudoClassTree |
The function that transforms a PseudoClassSelector into a tree |
CombinatorTree |
The function that transforms a CombinatorToken into a tree |
treeMap |
The IndexMap , on which the SelectorTree is based |
The tokens
submodule includes various TokenType
s, used by the library to represent various classes of tokens.
Like, parser
, tokens
submodule is, too, broken down onto submodules itself:
char
(tokenization)escaped
(escaped sequences)string
(string character sequences)bracket
(identifying of sub-selectors)list
(identifying of selector-lists)simple
(finalization of simple selectors)attribute
(parsing of attribute selectors)identifier
(parsing of identifiers - key elements of all simple selectors)
compound
(uniting simple selectors into compound ones)combinator
(identifies combinators, and orders thecompound
results based on them)
The following is the enumeration of TokenType
s exported by the corresponding submodules.
TokenType |
represents | type -word |
---|---|---|
SelectorHash |
The hash (# ) symbol |
"hash" |
SelectorDot |
The dot (. ) symbol |
"dot" |
Space |
One of the space (/\s/ ) symbols |
"space" |
RectOp |
The opening square bracket ([ ) symbol |
"rop" |
RectCl |
The closing square bracket (] ) symbol |
"rcl" |
DoubleColon |
The double colon symbol sequence (:: ) |
"double-colon" |
Colon |
The single colon (: ) symbol |
"colon" |
Plus |
The plus (+ ) symbol |
"plus" |
Child |
The child combinator symbol (> ) |
"child" |
OpBrack |
The opening bracket (( ) symbol |
"opbrack" |
ClBrack |
The closing bracket () ) symbol |
"clbrack" |
EndsWithMatch |
The ends-with match ($= ) symbol-sequence |
"endswith" |
IncludesMatch |
The includes-match (~= ) symbol-sequence |
"includes" |
HyphenBeginMatch |
The hyphen-beign match (|= ) symbol-sequence |
"hyphbeg" |
PrefixMatch |
The prefix-match (^= ) symbol-sequence |
"prefix" |
FindMatch |
The find-match (*= ) symbol-sequence |
"find" |
EqMatch |
The equality-match (*= ) symbol |
"eq" |
Any |
The universal selector (* ) symbol |
"any" |
Namespace |
The namespace combinator symbol (| ) |
"namespace" |
Sibling |
The sibling combinator symbol (~ ) |
"sibling" |
Quote |
One of the quote symbols (' or " ) |
"quote" |
Comma |
The comma (, ) symbol |
"comma" |
Ampersand |
The ampersand (& ) symbol |
"ampersand" |
Escape |
The escape (\ ) symbol |
"escape" |
SelectorSymbol |
Any other symbol (not in the table already) | "symbol" |
These TokenType
s are used for initial tokenization of the given CSS selector.
const Escaped: TokenType
Represents an escaped character or a hex number up to 6 digits. Used inside identifiers and strings.
Type-word: "escaped"
const SelectorPartial: (x: any): boolean
Checks for whether a given item is one of SelectorSymbol
s or Escaped
s.
TokenType |
represents | type -word |
---|---|---|
SelectorString |
A string | "string" |
StringCharacters |
A sequence of in-string characters | "string-chars" |
TokenType |
represents | type -word |
---|---|---|
SubSelector |
A sub-selector | "sub-selector" |
TokenType |
represents | type -word |
---|---|---|
SelectorList |
A selector-list (..., ..., ... ) |
"selector-list" |
TokenType |
represents | type -word |
---|---|---|
SelectorElement |
An element-selector (ex: h1 ) |
"selector-list" |
SelectorId |
An id-selector (ex: #i-am-unique ) |
"id" |
SelectorClass |
A class-selector (ex: .we-are-many ) |
"class" |
SelectorAttribute |
An attribute-selector (ex: [nom="valeur"] ) |
"attribute" |
PseudoClassSelector |
A pseudo-class selector (ex: :hover ) |
"pseudo-class" |
PseudoElementSelector |
A pseudo-element selector (ex: ::after ) |
"pseudo-element" |
UniversalSelector |
A universal selector ("*" ) |
"universal" |
ParentSelector |
Parent-selector (& ) |
"parent" |
The only export is the isMatch
predicate.
const isMatch: (x: any): boolean
Returns true
only for one of EndsWithMatch
, IncludesMatch
, HyphenBegMatch
, PrefixMatch
, FindMatch
, EqMatch
.
TokenType |
represents | type -word |
---|---|---|
SelectorIdentifier |
An identifier | "identifier" |
IdentifierCharacters |
A sequence of in-identifier characters | "id-chars" |
TokenType |
represents | type -word |
---|---|---|
CompoundSelector |
A compound selector, includes simple selectors | "compound" |
Also, contains the isSelector
predicate
const isSelector: (x: any): boolean
Returns true
only if the argument is one of SelectorElement
, SelectorId
, SelectorClass
, SelectorAttribute
, PseudoClassSelector
, PseudoElementSelector
,
UniversalSelector
, ParentSelector
TokenType |
represents | type -word |
---|---|---|
CombinatorToken |
A combinator, consists of a combinator token and arguments | "compound" |
Also, exports the isCombinator
predicate.
const isCombinator: (x: any): boolean
Returns true
only to one of the Child
, Space
, Plus
, Namespace
, Sibling
.