@desertnet/pcre

    0.0.2 • Public • Published

    pcre

    Perl compatible regular expressions for JavaScript

    Installation

    npm install @desertnet/pcre
    

    Usage

    Internally this module uses the PCRE2 library, running in a WebAssembly instance. This has a side effect of requiring you do a few unusual things when using this module:

    Initialization

    Before calling any constructors or methods, you must first asynchronously initialize the module by calling init.

    import PCRE from '@desertnet/pcre'
     
    async function main () {
      await PCRE.init()
      // make other PCRE calls...
    }
     
    main()

    Memory Management

    When you create a new PCRE instance, you are allocating memory within the WebAssembly instance. Currently, there are no hooks in JavaScript that let us automatically free this memory when the PCRE instance is garbage collected by the JavaScript runtime. This means that in order to prevent memory leaks, you must call .destroy() on a PCRE instance when it is no longer needed.

    API

    import PCRE from '@desertnet/pcre'

    PCRE.init()

    Initializes the module, returning a Promise that is resolved once initialization is complete. You must call this at least once and await the returned Promise before calling any other PCRE methods or constructors.

    PCRE.version()

    Returns a string with the PCRE2 version information.

    new PCRE(pattern, flags)

    Creates a new PCRE instance, using pcre2_compile() to compile pattern, using flags as the compile options. You must call .destroy() on the returned instance when it is no longer needed to prevent memory leakage.

    • pattern: A string containing a Perl compatible regular expression. Tip: use String.raw to avoid needing to escape backslashes.
    • flags: An optional string with each character representing an option. Supported flags are i, m, s, and x. See perlre for details.
    const pattern = String.raw`\b hello \s* world \b`
    const re = new PCRE(pattern, 'ix')
     
    // ...
     
    re.destroy()

    In the event of a compilation error in the pattern or an unsupported flag, an Error will be thrown with an error message from PCRE2. Additionally, it will have an offset property indicating the character offset in pattern where the error was encountered.

    let re
     
    try {
      re = new PCRE(String.raw`a)b`)
    }
    catch (err) {
      console.error(`Compilation failed: ${err.message} at ${err.offset}.`)
      // Prints: Compilation failed: unmatched closing parenthesis at 1.
    }

    re.destroy()

    Releases the memory allocated in the WebAssembly instance. You must call this method manually once you no longer have a need for the instance, or else your program will leak memory.

    Contributing

    Prerequisites for development include Docker, make and curl.

    Install

    npm i @desertnet/pcre

    DownloadsWeekly Downloads

    4

    Version

    0.0.2

    License

    MIT

    Unpacked Size

    452 kB

    Total Files

    8

    Last publish

    Collaborators

    • limulus