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.parse('"incomplete');
if(result.complete && !result.error) {
  // okay to use result.parts
}

Usage

In regular mode

var parser = new SnailEscape();
var result = parser.parse("echo hello world");
if(result.error) {
  console.error("could not parse input: ", result.error);
} else {
  console.log("All done! You typed the below array (as json): ")
  console.log(JSON.stringify(result.parts));
}
 

In partial mode

var parser = new SnailEscape({partial: true});
var result = parser.parse("'arg1' 'arg\\n2' arg\\n3 arg4 arg5");
if(result.error) {
  console.log("This will never parse! Backspace now (starting at character " + result.error.index);
} else if(!result.complete) {
  console.log("Keep typing...");
} else if(result.complete && !result.error) {
  console.log("All done! You typed the below array (as json): ")
  console.log(JSON.stringify(result.parts));
}

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