selector

selector is a CSS selector parsing/generation/construction library.

Installation

npm install @hgargg-0710/selector

Documentation

The following is the precise description of the library's exports (v0.1).

1. parse (function)
2. generate (function)
3. parser (submodule)
4. generator (submodule)
5. tokens (submodule)
6. tree (submodule)

NOTE: it is built on top of the parsers.js library for parser-making, so some of the terminology comes from there.

parse

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.

generate

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

parser

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

1. char (tokenization)
2. escaped (escaped sequences)
3. string (string character sequences)
4. bracket (identifying of sub-selectors)
5. list (identifying of selector-lists)
6. simple (finalization of simple selectors)
   1. attribute (parsing of attribute selectors)
   2. identifier (parsing of identifiers - key elements of all simple selectors)
7. compound (uniting simple selectors into compound ones)
8. despace (elimination of undesired space tokens to simplify further descendant combinator identification)
9. combinator (identifies combinators, and orders the compound 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.

char

| 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 - TokenTypes corresponding to them |

escaped

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

string

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

bracket

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

list

| export | description | | --------------------- | -------------------------------------------------------------------------------- | | SelectorCommaParser | Breaks all the pieces of parsed Stream into arrays and eliminates all Commas |

simple

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

attribute

| export | description | | ------------------ | -------------------------------------------------- | | AttributeParser | The BasicParser for parsing attribute selectors. | | AttributeHandler | Handler for attribute selectors. | | attributeMap | The TypeMap, on which AttributeParser is based |

identifier

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

compound

| export | description | | ------------------------ | ----------------------------------------------------------------------------------- | | CompoundSelectorParser | Main parsing function. Combines different simple selectors into CompoundSelectors | | CompoundHandler | The handler for simple selectors | | compoundMap | The TypeMap, on which CompoundSelectorParser is based |

despace

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

combinator

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

generator

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 Streams , 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 |

tree

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 |

tokens

The tokens submodule includes various TokenTypes, used by the library to represent various classes of tokens.

Like, parser, tokens submodule is, too, broken down onto submodules itself:

1. char (tokenization)
2. escaped (escaped sequences)
3. string (string character sequences)
4. bracket (identifying of sub-selectors)
5. list (identifying of selector-lists)
6. simple (finalization of simple selectors)
   1. attribute (parsing of attribute selectors)
   2. identifier (parsing of identifiers - key elements of all simple selectors)
7. compound (uniting simple selectors into compound ones)
8. combinator (identifies combinators, and orders the compound results based on them)

The following is the enumeration of TokenTypes exported by the corresponding submodules.

char

| 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 TokenTypes are used for initial tokenization of the given CSS selector.

escaped

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 SelectorSymbols or Escapeds.

string

| TokenType | represents | type-word | | ------------------ | ---------------------------------- | ---------------- | | SelectorString | A string | "string" | | StringCharacters | A sequence of in-string characters | "string-chars" |

bracket

| TokenType | represents | type-word | | ------------- | -------------- | ---------------- | | SubSelector | A sub-selector | "sub-selector" |

list

| TokenType | represents | type-word | | -------------- | --------------------------------- | ----------------- | | SelectorList | A selector-list (..., ..., ...) | "selector-list" |

simple

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

attribute

The only export is the isMatch predicate.

const isMatch: (x: any): boolean

Returns true only for one of EndsWithMatch, IncludesMatch, HyphenBegMatch, PrefixMatch, FindMatch, EqMatch.

identifier

| TokenType | represents | type-word | | ---------------------- | -------------------------------------- | -------------- | | SelectorIdentifier | An identifier | "identifier" | | IdentifierCharacters | A sequence of in-identifier characters | "id-chars" |

compound

| 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

combinator

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