usercss-meta

Parse usercss metadata supported by the Stylus userstyle manager

Install

NPM

$ npm install --save usercss-meta

unpkg.com CDN:

• https://unpkg.com/usercss-meta/dist/usercss-meta.js
• https://unpkg.com/usercss-meta/dist/usercss-meta.min.js

This module depends on URL parser. In Node.js, the module requires url module. In the browser build, it uses global variable URL.

Usage

const usercssMeta = require('usercss-meta');

const {metadata} = usercssMeta.parse(`/* ==UserStyle==
@name        test
@namespace   github.com/openstyles/stylus
@version     0.1.0
@description my userstyle
@author      Me
@var text my-color "Select a color" #123456
==/UserStyle== */`);

/* => {
  "vars": {
    "my-color": {
      "type": "text",
      "label": "Select a color",
      "name": "my-color",
      "value": null,
      "default": "#123456",
      "options": null
    }
  },
  "name": "test",
  "namespace": "github.com/openstyles/stylus",
  "version": "0.1.0",
  "description": "my userstyle",
  "author": "Me"
}
*/

usercssMeta.stringify(metadata, {alignKeys: true});

/* => `/* ==UserStyle==
@name        test
@namespace   github.com/openstyles/stylus
@version     0.1.0
@description my userstyle
@author      Me
@var         text my-color "Select a color" #123456
==/UserStyle== *\/`

*/

API Reference

This module exports following members:

• To parse metadata:
  • parse: Function. Parse metadata and return an object.
  • createParser: Function. Create a metadata parser.
  • ParseError: Class.
  • util: Object. A collection of parser utilities.
• To stringify metadata:
  • stringify: Function. Stringify metadata object and return the string.
  • createStringifier: Function. Create a metadata stringifier.

parse

const parseResult = parse(text: String, options?: Object);

This is a shortcut of

createParser(options).parse(text);

createParser

const parser = createParser({
  unknownKey?: String,
  mandatoryKeys?: Array<key: String>
  parseKey?: Object,
  parseVar?: Object,
  validateKey?: Object,
  validateVar?: Object,
  allowErrors?: Boolean
});

unknownKey decides how to parse unknown keys. Possible values are:

• ignore: The directive is ignored. Default.
• assign: Assign the text value (characters before \s*\n) to result object.
• throw: Throw a ParseError.

mandatoryKeys marks multiple keys as mandatory. If some keys are missing then throw a ParseError. Default: ['name', 'namespace', 'version'].

parseKey is a key/parseFunction map. It allows users to extend the parser. Example:

const parser = createParser({
  mandatoryKeys: [],
  parseKey: {
    myKey: util.parseNumber
  }
});
const {metadata} = parser.parse(`
  /* ==UserStyle==
  @myKey 123456
  ==/UserStyle==
`);
assert.equal(metadata.myKey, 123456);

parseVar is a variableType/parseFunction map. It extends the parser to parse additional variable types. For example:

const parser = createParser({
  mandatoryKeys: [],
  parseVar: {
    myvar: util.parseNumber
  }
});
const {metadata} = parser.parse(`/* ==UserStyle==
@var myvar var-name 'Customized variable' 123456
==/UserStyle== */`);
const va = metadata.vars['var-name'];
assert.equal(va.type, 'myvar');
assert.equal(va.label, 'Customized variable');
assert.equal(va.default, 123456);

validateKey is a key/validateFunction map, which is used to validate the metadata value. The function accepts a state object:

const parser = createParser({
  validateKey: {
    updateURL: state => {
      if (/example\.com/.test(state.value)) {
        throw new ParseError({
          message: 'Example.com is not a good URL',
          index: state.valueIndex
        });
      }
    }
  }
});

There are some builtin validators, which can be overwritten:

|Key|Description| |---|-----------| |version|Ensure the value matches semver-regex then strip the leading v or =.| |homepageURL|Ensure it is a valid URL and the protocol must be http or https.| |updateURL|Same as above.| |supportURL|Same as above.|

validateVar is a variableType/validateFunction map, which is used to validate variables. The function accepts a state object:

const parser = createParser({
  validateVar: {
    color: state => {
      if (state.value === 'red') {
        throw new ParseError({
          message: '`red` is not allowed',
          index: state.valueIndex
        });
      }
    }
  }
});

Builtin validators:

|Variable Type|Description| |-------------|-----------| |checkbox|Ensure the value is 0 or 1.| |number|Ensure sure the value is a number, doesn't exceed the minimum/maximum, and is a multiple of the step value.| |range|Same as above.|

If allowErrors is true, the parser will collect parsing errors while parser.parse() and return them as parseResult.errors. Otherwise, the first parsing error will be thrown.

parser.parse

const {
  metadata: Object,
  errors: Array
} = parser.parse(text: String);

Parse the text (metadata header) and return the result.

parser.validateVar

parser.validateVar(varObj);

Validate the value of the variable object. This function uses the validators defined in createParser.

varObj is the variable object in metadata.vars:

const {metadata} = parse(text);

/* modify metadata.vars['some-var'].value ... */

for (const varObj of Object.values(metadata.vars)) {
  validateVar(varObj);
}

ParseError

throw new ParseError(properties: Object);

Use this class to initiate a parse error.

properties would be assigned to the error object. There are some special properties:

• code - error code.
• message - error message.
• index - the string index where the error occurs.
• args - an array of values that is used to compose the error message. This allows other clients to generate i18n error message.

A table of errors thrown by the parser:

|err.code|err.args|Description| |----------|----------|-----------| |invalidCheckboxDefault||Expect 0 or 1.| |invalidRange|Variable type|Expect a number or an array.| |invalidRangeMultipleUnits|Variable type|Two different units are defined.| |invalidRangeTooManyValues|Variable type|Too many values in the array.| |invalidRangeValue|Variable type|Values in the array must be number, string, or null.| |invalidRangeDefault|Variable type|The default value of @var range must be a number. This error may be thrown when parsing number or range variables.| |invalidRangeMin|Variable type|The value is smaller than the minimum value.| |invalidRangeMax|Variable type|The value is larger than the maximum value.| |invalidRangeStep|Variable type|The value is not a multiple of the step value.| |invalidRangeUnits|[VARIABLE_TYPE, UNITS]|The value is not a valid CSS unit.| |invalidNumber||Expect a number.| |invalidSelect||The value of @var select must be an array or an object.| |invalidSelectValue||The value in the array/object must be a string.| |invalidSelectEmptyOptions||The options list of @var select is empty.| |invalidSelectLabel||The label of the option is empty.| |invalidSelectMultipleDefaults||Multiple options are specified as the default value.| |invalidSelectNameDuplicated||Found duplicated option names.| |invalidString||Expect a string that is quoted with ', ", or `.| |invalidURLProtocol|Protocol of the URL|Only http and https are allowed.| |invalidVersion|Version string|https://github.com/sindresorhus/semver-regex| |invalidWord||Expect a word.| |missingChar|A list of valid characters|Expect a specific character.| |missingEOT||Expect <<EOT ... data.| |missingMandatory|A list of missing keys|This error doesn't have err.index.| |missingValue||Expect a non-whitespace value.| |unknownJSONLiteral|Literal value|JSON has only 3 literals: true, false, and null.| |unknownMeta|[META_KEY, SUGGESTED_META_KEY]|Unknown @metadata. It may suggest the correct metadata name if there is a typo. SUGGESTED_META_KEY can be null| |unknownVarType|[META_KEY, VARIABLE_TYPE]|Unknown variable type. META_KEY could be var or advanced.|

util

A collection of parser utilities. Some of them might be useful when extending the parser.

• eatWhitespace(state): Move state.lastIndex to next non-whitespace character.
• parseEOT(state): Parse EOT multiline string used by xStyle extension.
• parseJSON(state): Parse JSON value. Note that the JSON parser can parse some additional syntax like single quoted string, backtick quoted multiline string, etc.
• parseNumber(state): Parse numbers.
• parseString(state): Parse quoted string.
• parseStringToEnd(state): Parse the text value before line feed.
• parseWord(state): Parse a word. ([\w-]+)

stringify

const text = stringify(metadata: Object, options?: Object);

This is a shortcut of:

createStringifier(options).stringify(metadata);

createStringifier

const stringifier = createStringifier(options?: Object);

options may contain following properties:

• alignKeys: Boolean. Decide whether to align metadata keys. Default: false.

• space: Number|String. Same as the space parameter for JSON.stringify.

• format: String. Possible values are 'stylus' and 'xstyle'. This changes how variables are stringified (@var v.s. @advanced). Default: 'stylus'.

• stringifyKey: Object. Extend the stringifier to handle specified keys.

  The object is a map of key: stringifyFunction pair. stringifyFunction would receive one argument:

  • value: The value of the key, which is the same as metadataObject[key].

  The function should return a string or an array of strings.

• stringifyVar: Object. Extend the stringifier to handle custom variable type.

  The object is a map of varType: stringifyFunction pair. The function would receive three arguments:

  • variable: The variable which should be stringified, which is the same as metadataObject.vars[variable.name].
  • format: The format parameter of the option.
  • space: The space parameter of the option.

  The function should return a string which represents the default value of the variable.

Related

• Stylus userstyle manager - source of most of this code
• usercss metadata spec
• xStyle metadata spec - Also supported by this parser

License

MIT

Run tests

This repo includes 3 tests:

• xo linter - which could be invoked with xo command.

• ava test - which could be invoked with ava command.

• Browser test - we currently support Chrome 49+. To run the test:

  1. Run npm run build to build the browser dist.
  2. Run node browser-test to generate browser test.
  3. Open browser-test.html with a browser.
  4. Open the console and ensure everything is OK.

Changelog

• 0.12.0 (Aug 1, 2021)

  • Add: detect typo in unknownMeta error.
  • Change: unknownMeta error has two arguments now.

• 0.11.0 (Jul 6, 2021)

  • Change: the version validator no longer follows semver strictly. Implement your own validator if you need strict version check.

• 0.10.1 (Jul 6, 2021)

  • Fix: remove incompat features. Pass Chrome 49 browser test.

• 0.10.0 (Nov 19, 2020)

  • Fix: precision issue when validating decimals.
  • Change: allow hyphen in key name.
  • Change: bump node version to 8.3.0.

• 0.9.0 (Nov 26, 2018)

  • The repository is moved.
  • Change: parseStringToEnd now throws an error if matched nothing.
  • Add: missingValue error.

• 0.8.4 (Nov 20, 2018)

  • Add: support Chrome 49.

• 0.8.3 (Nov 7, 2018)

  • Add: invalidSelectLabel/invalidSelectNameDuplicated errors.
  • Add: invalidSelect/invalidSelectValue errors.
  • Add: parse number exponent.
  • Fix: version validator doesn't match the entire string.
  • Fix: step validator doesn't match against min/max values.

• 0.8.2 (Oct 3, 2018)

  • Add: invalidRangeUnits error.
  • Fix: empty variable would make the parser consume the data after \n.
  • Fix: step validator is broken.

• 0.8.1 (Sep 26, 2018)

  • Add: attach variable type to range errors.

• 0.8.0 (Sep 23, 2018)

  • Bump dependencies. Move semver-regex to package dependencies.
  • Change: while parsing @advanced dropdown, the result type would be select.
  • Add: the parser/stringifier for @var number and @var range.
  • Add: parser method parser.validateVar.
  • Add: now parseNumber and parseJSON accept decimals without leading zeros e.g. .5 like CSS.
  • Add: asterisk syntax in @var select.
  • Add: validateKey and validateVar arguments to createParser.
  • Fix: when stringifying @var select in xstyle format, it should produce @advanced dropdown instead of @advanced select.
  • Fix: should throw an error with @var dropdown.
  • Fix: don't assign advanced key to metadata object.

• 0.7.1 (Sep 9, 2018)

  • Breaking: the return value of parser.parse is changed.
  • Breaking: the signature of ParseError is changed.
  • Add: createParser now accepts allowErrors arg.
  • Change: some error messages are changed.

• 0.6.1 (Jul 22, 2018)

  • Fix: stringify would throw if the value is number instead of string.

• 0.6.0 (Jul 13, 2018)

  • Change: the url module is shimmed with self.URL by using pkg.browser.
  • Fix: stringify multi-line description.

• 0.5.0 (May 16, 2018)

  • Change: the ParseResult object doesn't contain vars key if there is no variable in the input.
  • Fix: var key is accidentally assigned to ParseResult object.

• 0.4.0 (May 9, 2018)

  • Rewrite the parser, cleanup unused stuff.
  • Add stringify feature.