{"id":13745,"library":"parserlib","title":"ParserLib CSS Parser","description":"ParserLib is a CSS3 SAX-inspired parser written in JavaScript, designed for event-driven parsing of CSS stylesheets. It supports standard CSS syntax and offers a degree of validation for property names and values, though it is not exhaustive. The library is currently at version 1.1.1, with its most recent update focused on build file regeneration and minor CSS3 feature additions like `turn` units and nested media query support. Unlike AST-based parsers, ParserLib emits events during the parsing process rather than constructing a syntax tree, requiring developers to implement listeners for desired functionalities. It is built to operate in various JavaScript environments, including Node.js, Rhino, and directly in HTML pages, making it versatile for different project setups.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/CSSLint/parser-lib","tags":["javascript","parser","css","css3","sax","style","stylesheet"],"install":[{"cmd":"npm install parserlib","lang":"bash","label":"npm"},{"cmd":"yarn add parserlib","lang":"bash","label":"yarn"},{"cmd":"pnpm add parserlib","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily supports CommonJS 'require' syntax. Direct ESM 'import' is not natively supported without a transpilation step.","wrong":"import parserlib from 'parserlib';","symbol":"parserlib","correct":"const parserlib = require('parserlib');"},{"note":"Access the Parser class through the `css` namespace of the main `parserlib` object. ESM imports are not directly supported.","wrong":"import { Parser } from 'parserlib/css';","symbol":"parserlib.css.Parser","correct":"const { Parser } = require('parserlib').css;"},{"note":"ParserLib is SAX-inspired and event-driven; there is no AST. Interact with the parsed CSS by adding listeners for specific events like 'property', 'rule', etc.","symbol":"parser.addListener","correct":"parser.addListener('property', (event) => console.log(event.property.text));"}],"quickstart":{"code":"const parserlib = require('parserlib');\n\nconst parser = new parserlib.css.Parser({\n starHack: true, // Treat properties with a leading asterisk as if the asterisk wasn't there\n underscoreHack: true // Treat properties with a leading underscore as if the underscore wasn't there\n});\n\nconst someCSSText = `\n /* This is a sample CSS block */\n @media screen and (min-width: 768px) {\n .container {\n width: 90%;\n margin: 0 auto;\n }\n }\n\n body {\n font-family: Arial, sans-serif;\n color: #333;\n }\n\n h1._title { /* underscore hack example */\n font-size: 2em;\n *color: #00f; /* star hack example, if 'starHack' is true */\n text-decoration: underline;\n }\n`;\n\ntry {\n parser.parse(someCSSText);\n console.log('CSS parsed successfully. Remember, this is an event-driven parser; attach listeners for detailed output.');\n} catch (e) {\n console.error('Parsing error:', e.message);\n}","lang":"javascript","description":"Demonstrates initializing the CSS parser with 'starHack' and 'underscoreHack' options and parsing a sample CSS string. It highlights the event-driven nature where no AST is returned directly."},"warnings":[{"fix":"Review project-specific changelogs or GitHub releases for `v1.0.0` if available, and adapt code to the updated API. Implement comprehensive tests to identify regressions.","message":"Major version `1.0.0` was released without explicit breaking change documentation. Users upgrading from `0.x` versions should anticipate potential API changes and thoroughly test their applications.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Instead of expecting a return value with a parse tree, register event listeners for specific CSS constructs (e.g., `startstylesheet`, `property`, `rule`) to capture and process information as it's parsed. Example: `parser.addListener('property', (event) => { /* ... */ });`","message":"ParserLib is a SAX-inspired, event-driven parser and *does not* construct or return an Abstract Syntax Tree (AST). Developers must attach event listeners to process CSS rules and properties incrementally.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For strict CSS validation requirements, integrate additional dedicated CSS validation tools alongside ParserLib. Do not rely solely on ParserLib for comprehensive syntax or semantic checks.","message":"The parser's validation capabilities are not exhaustive; it is 'not guaranteed to thoroughly validate all possible CSS properties.'","severity":"gotcha","affected_versions":"All versions"},{"fix":"In Node.js environments, use `const parserlib = require('parserlib');`. For browser use, ensure the `parserlib.js` script is loaded via a `