API.md

regex-translator.js

Convert a Regular Expression from one flavour to another.

Internal module name: RegexTranslator

Author: Anadian

Code license: MIT

	Copyright 2020 Anadian
	Permission is hereby granted, free of charge, to any person obtaining a copy of this 
software and associated documentation files (the "Software"), to deal in the Software 
without restriction, including without limitation the rights to use, copy, modify, 
merge, publish, distribute, sublicense, and/or sell copies of the Software, and to 
permit persons to whom the Software is furnished to do so, subject to the following 
conditions:
	The above copyright notice and this permission notice shall be included in all copies 
or substantial portions of the Software.
	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE 
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation License:

The source-code comments and documentation are written in GitHub Flavored Markdown.

The type notation used in this documentation is based off of the Google Closure type system.

The status and feature lifecycle keywords used in this documentation are based off of my own standard defined here.

Functions

setLogger

Allows this module's functions to log the given logger object.

Parametres:

name	type	description
logger	{?object}	The logger to be used for logging or null to disable logging.

Throws:

code	type	condition
'ERR_INVALID_ARG_TYPE'	{TypeError}	Thrown if logger is neither an object nor null

Status:

version	change
0.0.0	Introduced

getMultiPartObjectFromInputString

Parses the given input string to identify its individual parts and returns said parts as an object.

Parametres:

name	type	description
input_string	{string}	The input string to be parsed.
options	{?Object}	[Reserved] Additional run-time options. [default: {}]

Returns:

type	description
{Object}	The multipart object with possible properties 'input_flavour', 'regex_string', 'replace_string', and 'output_flavour'.

Throws:

code	type	condition
'ERR_INVALID_ARG_TYPE'	{TypeError}	Thrown if a given argument isn't of the correct type.
'ERR_INVALID_ARG_VALUE'	{Error}	Thrown if given input string contains more than three regex seperators.

Status:

version	change
0.0.1	Introduced

getMediaryStringFromRegexString

Returns an intermediary string with special characters converted to a flavour-agnostic syntax.

Parametres:

name	type	description
regex_string	{string}	A string of the regex to be converted.
input_flavour_string	{string}	The flavour of the input string. [default: 'pcre']
options	{?Object}	[Reserved] Additional run-time options. [default: {}]

Returns:

type	description
{string}	The intermediary string after converting the input regex string.

Throws:

code	type	condition
'ERR_INVALID_ARG_TYPE'	{TypeError}	Thrown if a given argument isn't of the correct type.

Status:

version	change
0.2.1	Stable
0.0.1	Introduced

getMediaryObjectFromRegexString

Returns a mediary object from the given regular expression string. This function should be used instead of getMediaryStringFromRegexString as this properly handles chracter classes in a "round-trip" fashion.

Parametres:

name	type	description
regex_string	{string}	The regular expression string to be converted to a mediary object.
flavour_string	{string}	The flavour of the regex string. [default: ]
options	{?Object}	[Reserved] Additional run-time options. [default: {}]

Returns:

type	description
{object}	A mediary object with the property mediary_string and, if necessary, a property character_class_codes_array.

Throws:

code	type	condition
'ERR_INVALID_ARG_TYPE'	{TypeError}	Thrown if a given argument isn't of the correct type.

Status:

version	change
0.2.3	Introduced: Breaking change; function now returns an object with an intermediary_string property and a character_class_codes_array property if necessary.

getRegexStringFromMediaryString

Returns the given mediary string reformatted to the given regex flavour.

Parametres:

name	type	description
mediary_string	{string}	The mediary string to be converted to the given format.
flavour_string	{string}	The regex flavour to convert the mediary string to. [default: 'pcre']
options	{?Object}	[Reserved] Additional run-time options. [default: {}]

Returns:

type	description
{string}	The output regex string.

Throws:

code	type	condition
'ERR_INVALID_ARG_TYPE'	{TypeError}	Thrown if a given argument isn't of the correct type.

Status:

version	change
0.2.1	Stable
0.0.1	Introduced

getRegexStringFromMediaryObject

Returns a regex string from the given mediary object formatted to the given regex flavour.

Parametres:

name	type	description
mediary_object	{object}	A mediary object with a mediary_string and character_class_codes_array properties.
flavour_string	{string}	A string repesenting the Regular Expression flavour to return the string in. [default: 'pcre']
options	{?Object}	[Reserved] Additional run-time options. [default: {}]

Returns:

type	description
{string}	The regex string translated from the mediary obejct.

Throws:

code	type	condition
'ERR_INVALID_ARG_TYPE'	{TypeError}	Thrown if a given argument isn't of the correct type.

Status:

version	change
0.2.7	Updated to add improved error handling.
0.2.3	Introduced

main_Async (private)

The main function when the script is run as an executable. Not exported and should never be manually called.

Parametres:

name	type	description
options	{?options}	An object representing the command-line options. [default: {}]

Status:

version	change
0.2.1	Stable
0.0.1	Introduced