charcode-is-valid-xml-name-character

Does a given character belong to XML spec's "Production 4 OR 4a" type (is acceptable for XML element's name)

Table of Contents

• Install
• What is does
• In practice
• API
• Contributing
• Licence

Install

npm i charcode-is-valid-xml-name-character

// consume via a CommonJS require:
const {
  isProduction4,
  isProduction4a
} = require("charcode-is-valid-xml-name-character");

// or as an ES Module:
import {
  isProduction4,
  isProduction4a
} from "charcode-is-valid-xml-name-character";

Here's what you'll get:

⬆ back to top

What is does

It returns a Boolean, is the given character the Production 4a of XML spec, or in human terms, a possible ending character of an XML element.

This library is used to detect where (X)HTML element names end.

This article contains an in-depth explanation of the spec terminology: https://www.xml.com/pub/a/2001/07/25/namingparts.html — it helped me to get up to speed on this subject.

⬆ back to top

In practice

Let's say you are iterating through string, character-by-character and it contains (X)HTML code source. This library will evaluate any given character and tell, is it a valid character for an element name. You use this library to detect where element names end.

In the most simple scenario:

<img class="">
    ^     ^
    1     2

Characters space (1) and = (2) in the example above mark the ending of the element names (img and class). OK, so we know spaces and equals' are not allowed as element names and therefore mark their ending. Are there more of such characters? Oh yes. Quite a lot according to spec what warrants a proper library dedicated only for that purpose.

⬆ back to top

API

Two functions - one to check requirements for first character, another to check requirements for second character and onwards. Both functions return a Boolean.

⬆ back to top

isProduction4() / validFirstChar() - requirements for 1st char

XML spec production 4 - the requirements for the first character of the XML element. It's more strict than requirements for the subsequent characters, see production 4a below.

Pass any character (including astral-one) into function isProduction4(), and it will respond with a Boolean, is it acceptable as first XML character (or not).

const {
  isProduction4,
  validFirstChar
  // isProduction4a,
} = require("charcode-is-valid-xml-name-character");

const res1 = isProduction4("-"); // or use validFirstChar(), the same
console.log("res1 = " + res1);
// => 'res1 = false <---- minus is not allowed for first character

const res2 = isProduction4("z"); // or use validFirstChar(), the same
console.log("res2 = " + res2);
// => 'res2 = true

It consumes a single character (can be any Unicode character, including astral-one, comprising two surrogates). Returns Boolean - is it acceptable as the first character in XML element's name.

⬆ back to top

isProduction4a() / validSecondCharOnwards() - requirements for 2nd char onwards

XML spec production 4a - the requirements for the second character onwards in XML element's name.

Pass any character (including astral-one) into function isProduction4a(), and it will respond with a Boolean, is it acceptable as second XML character and onwards (or not). Requirements are same as for the first character but a bit more permissive.

const {
  // isProduction4,
  isProduction4a
} = require("charcode-is-valid-xml-name-character");

const res1 = isProduction4a("-"); // or use validSecondCharOnwards(), the same
console.log("res1 = " + res1);
// => 'res1 = true <---- minus is allowed for second character-onwards

const res2 = isProduction4a("z"); // or use validSecondCharOnwards(), the same
console.log("res2 = " + res2);
// => 'res2 = true

It consumes a single character (can be any Unicode character, including astral-one, comprising two surrogates). Returns Boolean - is it acceptable as the second or subsequent character in XML element's name.

⬆ back to top

Contributing

• If you see an error, raise an issue.
• If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
• If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
• If you want to contribute some code, fork the monorepo via BitBucket, then write code, then file a pull request via BitBucket. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command line application).

The npm script "dev", the "dev": "rollup -c --dev --silent" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License

Copyright (c) 2015-2019 Roy Revelt and other contributors