@desertnet/pcre
v0.0.2
Published
Perl compatible regular expressions for JavaScript
Downloads
7
Readme
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: useString.raw
to avoid needing to escape backslashes.flags
: An optional string with each character representing an option. Supported flags arei
,m
,s
, andx
. 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.