style-search

What is style-search?

The style-search npm package is a utility for searching through CSS-like strings. It allows you to find specific patterns, such as selectors, properties, and values, within a CSS string. This can be particularly useful for building tools that need to analyze or transform CSS code.

What are style-search's main functionalities?

Search for Selectors

This feature allows you to search for CSS selectors within a CSS string. In the example, it searches for the '.' character, which indicates the start of a class selector, and logs the index where each selector is found.

const styleSearch = require('style-search');

const css = '.class1 { color: red; } .class2 { color: blue; }';

styleSearch({ source: css, target: '.' }, (match) => {
  console.log('Found selector at index:', match.startIndex);
});

Search for Properties

This feature allows you to search for specific CSS properties within a CSS string. In the example, it searches for the 'color' property and logs the index where each occurrence is found.

const styleSearch = require('style-search');

const css = '.class1 { color: red; } .class2 { color: blue; }';

styleSearch({ source: css, target: 'color' }, (match) => {
  console.log('Found property at index:', match.startIndex);
});

Search for Values

This feature allows you to search for specific CSS values within a CSS string. In the example, it searches for the 'red' value and logs the index where each occurrence is found.

const styleSearch = require('style-search');

const css = '.class1 { color: red; } .class2 { color: blue; }';

styleSearch({ source: css, target: 'red' }, (match) => {
  console.log('Found value at index:', match.startIndex);
});

Other packages similar to style-search

postcss

PostCSS is a tool for transforming CSS with JavaScript plugins. It provides a more comprehensive set of features compared to style-search, including parsing, transforming, and stringifying CSS. While style-search is focused on searching within CSS strings, PostCSS allows for more complex manipulations and transformations.

css-tree

CSS-tree is a tool for working with CSS, including parsing, generating, and analyzing CSS code. It offers more advanced features than style-search, such as building and traversing an Abstract Syntax Tree (AST) for CSS. This makes it suitable for more complex tasks that go beyond simple string searches.

csstree-validator

CSSTree Validator is a tool for validating CSS syntax and structure. It provides functionality for checking the correctness of CSS code, which is not a feature of style-search. While style-search is useful for finding specific patterns, CSSTree Validator ensures that the CSS code adheres to standards.

README

style-search

Search CSS (and CSS-like) strings, with sensitivity to whether matches occur inside strings, comments, and functions.

Usage

var styleSearch = require('style-search');

styleSearch(options, callback);

By default, the search ignores strings, comments, and function names. You can use the options to change this behavior or introduce other restrictions. That is what makes this module more useful for many searches than indexOf() or a RegExp.

However, if you need more detailed parsing, you should consider using the real parsers PostCSS, postcss-selector-parser, and postcss-value-parser.

Example

/* Here is some pink */
a { color: pink; }
a::before { content: "pink" }
b { color: shadesOfPink(7); }

styleSearch({
  source: theCssStringAbove,
  target: "pink",
}, function(match, count) {
  /* Only the "pink" in `color: pink` will be
  reported as a match */
});

Reporting matches

For every match found your callback is invoked. It is passed two arguments:

• A match object with the following properties:
  • startIndex: where the match begins
  • endIndex: where the match ends
  • target: what got matched (useful if your target option is an array instead of a single string)
  • insideFunctionArguments: whether the match is inside a function — this includes the parentheses around the arguments
  • insideComment: whether the match is inside a comment
  • insideString: whether the match is inside a string
• The count of how many matches have been found up to this point.

Options

Below you'll see that syntax feature options all accept three keywords: "skip", "check", "only". An error will be thrown if you use "only" more than once.

source

String. Required.

The source string to search through.

target

String or array of strings. Required.

The target of the search. Can be

• a single character
• a string with some length
• an array of strings, all of which count as matches (the match object passed to the callback will differentiate which string in the array got matched via its target property)

once

Boolean. Default: false.

If true, the search will stop after one match is found.

comments

"skip" | "check" | "only". Default: "skip".

This includes both standard /* CSS comments */ and non-standard but widely used // single line comments.

strings

"skip" | "check" | "only". Default: "skip".

functionNames

"skip" | "check" | "only". Default: "skip".

functionArguments

"skip" | "check" | "only". Default: "check".

parentheticals

"skip" | "check" | "only". Default: "check".

This designates anything inside parentheses, which includes standard functions, but also Sass maps and other non-standard constructs. parentheticals is a broader category than functionArguments.

Changelog

0.1.0

• Initial extraction from stylelint, API refactoring, and release.