human2regex/API.md

Tutorial

Preface

Human2Regex (H2R) comes with a simple API allowing you to embed the H2R language inside your application. The steps to generate a regular expression go as follows

• Lex the input text (detects lexing errors)
• Parse the input text (detects parsing errors)
• Generate/interpret the input text (detects semantic errors)

Lexing your text

H2R's lexer comes with a few options for stricter parsing and some performance optimizations

export declare class Human2RegexLexerOptions {
    // If true, the lexer will skip validations (~25% faster)
    skip_validations?: boolean = false;
    // The type of indents the lexer will allow
    type?: IndentType = IndentType.Both;
    // Number of spaces per tab
    spaces_per_tab?: number = 4;
}

export declare enum IndentType {
    Tabs = 0,
    Spaces = 1,
    Both = 2
}

Once your options are determined, you can instanciate a lexer like so:

import { Human2RegexLexer, Human2RegexLexerOptions } from "./lexer";
const lexer = new Human2RegexLexer(new Human2RegexLexerOptions(true));

Due to a technical limitation as well as just for performance reasons, only 1 instance of Human2RegexLexer is allowed.

To use the lexer, call tokenize on your input text:

const lex_result = lexer.tokenize("<your text here>");

This returns an ILexingResult which is passed on to the parser.

export interface ILexingResult {
    // tokens parsed
    tokens: IToken[];
    // errors found
    errors: ILexingError[];
}

To determine if the lex occured successfully, check to see if lex_result.errors contains any elements. If so you can extract the errors by converting them to CommonError and calling the toString() function

import { CommonError } from "./utilities";
result.errors.map(CommonError.fromLexError).forEach((x) => console.log(x.toString()));

You may also use the CommonError itself if you wish to incorporate it into a text editor

export declare class CommonError {
    // Type of error (Lexer, Parser, Semantic)
    type: string;
    
    // position of error
    start_line: number;
    start_column: number;
    length: number;

    //textual message
    message: string;
}

You can reuse the lexer by calling tokenize() again.

Parsing the tokens

H2R's parser comes only with a performance optimization

export declare class Human2RegexParserOptions {
    // If true, the lexer will skip validations (~25% faster)
    skip_validations?: boolean = true;
}

Once your options are determined, you can instanciate a lexer like so:

import { Human2RegexParser, Human2RegexParserOptions } from "./parser";
const parser = new Human2RegexParser(new Human2RegexParserOptions(true));

Due to a technical limitation as well as just for performance reasons, only 1 instance of Human2RegexParser is allowed.

To use it, call the parser with your tokens from the lexer:

parser.input = lex_result.tokens;
const parse_result = parser.parse();

The parser's errors are found via parser.errors and again can be checked to see if the parse was successful by checking the length of this list. If it contains any errors, you can extract the errors by converting them to CommonError and calling the toString() function

parser.errors.map(CommonError.fromParseError).forEach((x) => console.log(x.toString()));

The parser contains state and so to re-use it, it must be reset by inputting (new) tokens to reset it

parser.input = lex_result.tokens;

Generating your regex

Assuming no errors were found, now it's time to generate the regular expression

H2R supports a few languages so far:

export enum RegexDialect {
    JS,
    PCRE,
    DotNet,
    Java
}

After choosing one, you must validate the regular expression. This may be skipped if and only if the input has already been validated before as the generator is not guaranteed to work unless there are no errors.

const validation_errors = parse_result.validate();

The result is a list of errors which, again, may be converted to a CommonError to extract information from it.

validation_errors.map(CommonError.fromParseError).forEach((x) => console.log(x.toString()));

If there are no errors, you can call the toRegex() function to create a string representation of the regular expression. You can then convert that to a RegExp object for regex matching.

const my_regex = new RegExp(parse_result.toRegex());

This will contain your regular expression.