@fav/text.escape

Escapes characters for various syntaxes and formats.

"fav" is an abbreviation of "favorite" and also the acronym of "for all versions". This package is intended to support all Node.js versions and many browsers as possible. At least, this package supports Node.js >= v0.10 and major Web browsers: Chrome, Firefox, IE11, Edge, Vivaldi and Safari.

Install

To install from npm:

$ npm install --save @fav/text.escape

NOTE: npm < 2.7.0 does not support scoped package, but old version Node.js supports it. So when you use such older npm, you should download this package from github.com, and move it in node_modules/@fav/text.escape/ directory manually.

Usage

For Node.js:

var escape = require('@fav/text.escape').RegExp;
escape('[@fav/text.escape]');  // => '\\[@fav/text\\.escape\\]'
console.log(escape('[@fav/text.escape]')); // => \[@fav/text\.escape\]

For Web browsers:

<script src="fav.text.escape.min.js"></script>
<script>
var escape = fav.text.escape.RegExp;
escape('[@fav/text.escape]');  // => '\\[@fav/text\\.escape\\]'
console.log(escape('[@fav/text.escape]'));  // => \[@fav/text\.escape\]
</script>

API

escape : object

Is a set of functins to escape characters in a string.

This function set provides escapings for following syntaxes and formats:

• RegExp
• RegExpCharClass
• HtmlEntity
• HtmlAttribute

In addition, the factory functions for two types of escaping are provided:

• byProposition
• byReplacement

NOTE: These functions doesn't check data types of the arguments, and assumes that they are given as per the specific data types.

escape.RegExp(source) : string

Escapes special characters of Regular Expression.

The special characters which are escaped are as follows: ^$\.*+?()[]{}|.

The specification of the special characters of Regular Expression comes from ECMA-262 — 21.2 RegExp (Regular Expression) Objects.

Parameter:

Parameter	Type	Description
source	string	The source string.

Return:

Type	Descriptionn
string	An escaped string.

escape.RegExpCharClass(source) : string

Escapes special characters of Regular Expression Character Class.

The special characters which are escaped are as follows: -^]\.

Parameter:

Parameter	Type	Description
source	string	The source string.

Return:

Type	Description
string	An escaped string.

escape.HtmlEntity(source) : string

Escapes special characters of HTML entity to character references, etc.

The escape mapping for HTML entity is as follows:

source character	replaced text
'<' (\u003c)	'&lt;'
'>' (\u003e)	'&gt;'
'&' (\u0026)	'&amp;'
' ' (\u0020)	'&nbsp;'
'\n' (\u000a)	'<br/>'

NOTE: To reserve multiple spaces(\u0020) and EOL(\n), should use CSS's white-space: pre-wrap.

Parameter:

Parameter	Type	Description
source	string	The source string.

Return:

Type	Description
string	An escaped string.

escape.HtmlAttribute(source) : string

Escapes special characters of HTML attributes to character references.

The escape mapping for HTML attribute is as follows:

source character	replaced text
'<' (\u003c)	'&lt;'
'>' (\u003e)	'&gt;'
'&' (\u0026)	'&amp;'
'"' (\u0022)	'&quot;'
"'" (\u0027)	'&apos;'

Parameter:

Parameter	Type	Description
source	string	The source string.

Return:

Type	Description
string	An escaped string.

escape.byPreposition(escapingChar [, ...escapedChars]) : function

Creates an escape function which escapes special characters by preposition of an espacing character, for example:

var escape = fav.text.escape.byPreposition('\\', '"\'');
escape('escaping ", \' and \\.');
// => 'escaping \\", \\\' and \\\\.'

Parameter:

Parameter	Type	Description
escapingChar	string	The escaping character placed before special characters. This character is escaped, too.
escapedChars	string	The special characters to be escaped.

Return:

Type	Description
function	An escaping function.

escape.byReplacement(escapingMap) : function

Creates an escape function which escapes special characters by replacement to corresponding strings, for examples:

var escape = fav.text.escape.byReplacement({ '"': '"', "'": ''' });
escape('escaping " and  \'.');
// => 'escaping " and '.'

Parameter:

Parameter	Type	Description
escapingMap	object	The plain object of which keys and values are mappings of escaped characters and replaced strings.

Return:

Type	Description
function	An escaping function.

Checked

Node.js (4〜12)

Platform	11	12
macOS	◯	◯
Windows10	◯	◯
Linux	◯	◯

Platform	4	5	6	7	8	9	10
macOS	◯	◯	◯	◯	◯	◯	◯
Windows10	◯	◯	◯	◯	◯	◯	◯
Linux	◯	◯	◯	◯	◯	◯	◯

io.js (1〜3)

Platform	1	2	3
macOS	◯	◯	◯
Windows10	◯	◯	◯
Linux	◯	◯	◯

Node.js (〜0.12)

Platform	0.8	0.9	0.10	0.11	0.12
macOS	◯	◯	◯	◯	◯
Windows10	◯	◯	◯	◯	◯
Linux	◯	◯	◯	◯	◯

Web browsers

Platform	Chrome	Firefox	Vivaldi	Safari	Edge	IE11
macOS	◯	◯	◯	◯	--	--
Windows10	◯	◯	◯	--	◯	◯
Linux	◯	◯	◯	--	--	--

License

Copyright (C) 2017-2019 Takayuki Sato

This program is free software under MIT License. See the file LICENSE in this distribution for more details.