als-css-parser v0.5.0

CSS Parser

Beta version

• CSS Parser
  • Installation
  • Usage
    • Import CssParser
    • Create an instance of CssParser
    • Get ruleSets
    • Generate a stylesheet
    • Generate a minified stylesheet
  • Publish
  • parse method
  • Hooks

This module provides a simple yet powerful CSS parser for JavaScript, allowing you to easily parse, manipulate, and generate CSS stylesheets. The CssParser class accepts raw CSS code and provides a range of methods to manipulate, minify, or generate stylesheets. It also supports custom hooks to modify the behavior of the parser.

Installation

npm install als-css-parser

Usage

You can use CssParser on browser and on node.js.

Import CssParser

On node.js:

const CssParser = require('css-parser');

On browser:

<script src="node_modules/als-css-parser/css-parser.js"></script>

Create an instance of CssParser

const rawCss = 'your raw css code here';
const hooks = {}; // optional custom hooks
const cssParser = new CssParser(rawCss, hooks);

Example:

let rawCss = /*css*/`
/* Comment */
.example{
  color:red;
  display:none
}
@media screen and (max-width:600px){
  .example{
    display:block
  }
}
`
const cssParser = new CssParser(rawCss);

At this point, cssParser has rawBlocks and rawCss properties. RawCss is a rawCss parameter in constructor.

rawBlocks is an array with separated rule sets which looks like this:

cssParser.rawBlocks = [
    "/* Comment */",
    ".example {\n      color: red;\n      display: none;\n    }",
    "@media screen and (max-width:600px) {\n      .example {\n        display: block;\n      }}"
]

Get ruleSets

Method ruleSets return object with css tree by using hooks from constructor and options which used by hooks.

Syntax:

const options = {}; // optional ruleSets options
const ruleSets = cssParser.ruleSets(options);

The result looks like this:

ruleSets = [
    "/* Comment */",
    {
        ".example": [{"color": "red"},{"display": "none"}]
    },
    {
        "@media screen and (max-width:600px)": [
            {".example": [{"display": "block"}]}
        ]
    }
]

Generate a stylesheet

const options = {}
const stylesheet = cssParser.stylesheet(options);

By default options are:

let options = {
   space:cssParser.space, // space for formating levels
   n:cssParser.n, // new line
   nocomments:false, // don't include comments in stylesheet
   removeEmptyRulesets:true // remove empty rule sets
}

Also options may include options for hooks.

Result example:

stylesheet = 
`/* Comment */
.example{
  color:red;
  display:none
}
@media screen and (max-width:600px){
  .example{
    display:block
  }
}
`

Generate a minified stylesheet

const minifiedStylesheet = cssParser.minified(options);

The minified stylesheet add the folowing options:

options.space=''
options.n=''
options.nocomments = true

Result example:

minifiedStylesheet = 
`.example{color:red;display:none}@media screen and (max-width:600px){.example{display:block}}`

Publish

publish method creates new stylesheet or use existing one for inserting css rules to document.

cssParser.publish()

Each published rule add to CssParser.published static property and not publishing if rule allready published.

parse method

parse method creates new instance of CssParser.

const parsedRules = CssParser.parse(rawCss, hooks);

Here the code for parse method

CssParser.parse = function(rawCss,hooks) {
   return new CssParser(rawCss,hooks)
}

Hooks

Hooks can be provided when creating a new CssParser instance. Hooks are functions that get called at specific points in the parsing process and can modify the behavior of the parser. Hooks should be defined in the following format:

{
   ruleSets: {
      mainRuleSets: [],
      ruleSets: [],
      rule: []
      string: [], // may include comment, @import, @charset, @namespace
      selector: [], 
      propname: [],
      value: [],
  },
  stylesheet: {
    string: [],
    selector: [],
    propname: [],
    value: []
  }
}

hook function will get folowing parameters:

• item value
• args={parentSelector,selector} - selector only if needed
• options - options from stylesheet or ruleSets
• the instance
• the CssParser class

Every hook has to return new value and may add event and errors to instance.events and instance.errors.

Example:

function optimizeValue(value,{parentSelector='main'},options,obj) {
   if(options.optimizeValue == false) return value
   if(value.startsWith('url') || value.startsWith('content')) return value
   value = value.replace(/\s[,)]/g,s => s.trim())
   value = value.replace(/[,(]\s/g,s => s.trim())
   value = value.replace(/0\./g,'.')
   return value
}
let options = {ruleSets:{
   value:[optimizeValue]
}}

let rawCss = `
.some {
   font-size:0.8rem;
   color: rgb(50, 50, 50);
}
`
const cssParser = new CssParser(rawCss,options);
cssParser.ruleSets()

Result

[
    {".some": [
      {"font-size": ".8rem"},
      {"color": "rgb(50,50,50)"}
   ]}
]