snailescape.js 🐌
Snail escape is a simple javascript library that implements a sane subset of bash escaping, similar to the ANSI C standard for escapes.
Supported Quoting
Single quotes, double quotes, and space-separation of parts are supported. This is best explained through an example:
All of the following:
echo "hello world"
, echo hello\ world
, "echo" 'hello world'
Will be split into:
["echo", "hello world"]
Supported Escapes
\a
— Bell (0x07
)\b
— Backspace (0x08
)\t
— Tab (0x09
)\e
— Escape (0x1B
)\n
— Newline (0x0A
)\v
— Vertical tab (0x0B
)\f
— Form feed (0x0C
)\r
— Carriage return (0x0D
)\
— Space (0x20
)\"
— Double quote (0x22
)\'
— Single quote (0x27
)\\
— Backslash (0x5C
)\[0-7]{1,3}
— Octal ASCII character\x[0-9a-f]{1,2}
— Hex ASCII character
When escapes apply
None of the above escapes apply within single quotes. All of the above escapes apply within double quotes or when not within quotes.
Escaping a space character or single quote characer is entirely redundant within double quotes, but both may be done.
Error handling
Error index
Any time the error
field of the output is set, the errorNdx
field is also
set to an integer indicating what offset is erroneous.
Modes
Snail escape has two modes of error handling:
This mode may be toggled by passing the argument {partial: true}
to the
constructor. It defaults to false.
Complete parse errors
Complete parse errors operates under the assumption that the given string should completely parse with no issues. It should have no trailing characters or mismatched quotes, and if it does that's an error.
Partial parse errors
Partial parse errors operates under the assumption that the string might be incomplete. this is useful if you are taking user-input as it is being typed and parsing it.
In this mode, it will return both an error and a 'complete' value. It is possible for a parse to be marked as not complete, and also not having any errors. If a parse is marked as incomplete and does have errors, that means there is no way for any added characters to make the arguments valid (e.g. if there is an invalid escape sequence).
In this mode, you must check both complete
and error
before you may safeuly use the result.
var result = parser;ifresultcomplete && !resulterror // okay to use result.parts
Usage
In regular mode
var parser = ;var result = parser;ifresulterror console; else console console;
In partial mode
var parser = partial: true;var result = parser;ifresulterror console; else if!resultcomplete console; else ifresultcomplete && !resulterror console console;
Known issues
- In partial mode, mismatched quotes indicate the end of the string as erroneous, not the opening quote.
- High unicode cannot be represented via escapes, only via the actual characters.
Contributions
Welcome, though please add tests and make sure that npm test
passes.
License
Apache 2.0