Add support for literal keys

[Genarito]

Motivation

As proposed in #5, Gura needs a way to represent other configuration languages' key formats to improve portability.

Proposal

Add support for Literal Keys which allows users to define keys with any Unicode char. It would be defined between Grave accents (U+0060). Eg.:

`a.literal&key!`: "Some value"

Considerations

This type of key should not be used unless portability with another configuration language is required. It should be stated in the specifications that their use is discouraged.

Version

Gura 2.0.0 which includes breaking changes from #11.

Changes

1. Add a new subsection in the Keys section with the new proposal.
2. Add a Changelog section where changes are listed.

[i509VCB]

How do we want to handle escaping ` if it is the escaping character?

[zajrik]

I'm thinking we will likely have to make special consideration for \, requiring it to be escaped so that it can be used specifically for escaping only backticks. So if we wanted to have a backslash and a back tick in a literal key, we'd have:

`foo\`bar\\baz`: "foobarbaz"

Does this seem reasonable? I do worry that it implies the support of other escape characters, though.

[Genarito]

Good point @i509VCB. If you check this JSON validator you'll see that JSON keys are defined in double quotes with the possibility of getting the escaped characters as literal, it also checks against a valid escape sentence. Eg.:

Valid JSON key

Note that " in the middle is escaped but printed as literal

{
   "!\"\n``\t\bsome&/key":1
}

Invalid JSON key

In this case, using the \ (the first character in the key) without a valid escape char produces an error against RFC 8259:

{
   "\!\"\n``\t\bsome&/key":1
}

So, in my opinion, we just could use the same criteria: if you want to use ` inside a literal key you must use \, in case you use the \ it must be with a valid escape char or `. The key emitted by the parsers should include the \ like a literal string.

Gura example

`literal\`\b\nkey`: "Test"

Should produce the key "literal\`\b\nkey"

In case the user uses \ with an invalid escaped char it should throw a ParseError. Eg.:

`\invalid`: "Test"

The above example fails as \i is not a valid escaping sentence.

What do you think?

[Genarito]

Ok, I've read the JSON specs in the IETF RFC and json.org. There's no specification about interpreting the strings inside a key. In the RFC string section they said:

The representation of strings is similar to conventions used in the C
family of programming languages. A string begins and ends with
quotation marks. All Unicode characters may be placed within the
quotation marks, except for the characters that MUST be escaped:
quotation mark, reverse solidus, and the control characters (U+0000
through U+001F).

But it's not clear how implementations must represent keys in objects. For example, using the same example I put above in Firefox generates this object key:

> Object.keys(JSON.parse('{"!\\"\\n``\\t\\bsome&/key":1}'))[0]
> "!\"
``	\u0008some&/key"

But in Chrome:

> Object.keys(JSON.parse('{"!\\"\\n``\\t\\bsome&/key":1}'))[0]
> '!"\n``\t\bsome&/key'

In both, the invalid example works ⚠️ removing implicitly the invalid escaping sentence:

> Object.keys(JSON.parse('{"\!\\"\\n``\\t\\bsome&/key":1}'))[0]
> '!"\n``\t\bsome&/key'

Note that the first reverse solidus is removed...

So I think we could be more specific and explicit than JSON, and add to the official specs the interpretation for Literal Keys. In my opinion, interpreting as literal makes all clearer as one can get what It writes without any kind of magic. The rules would be:

1. You can use any UTF-8 character inside Literal Keys.
2. If you want to write ` (U+0060 GRAVE ACCENT) you must escape it.
3. You also can use any of the valid escape sentences listed in Gura docs String section in Literal Keys.
4. Grave accents count as a valid escaping char only if they're used in Literal Keys (so no change is required for strings interpretation in previous Gura implementations).
5. To preserve consistency with already String specs (see Change escaped character behavior in Strings #11), if you use reverse solidus with any other character, implementations must raise InvalidEscapedCharacterError

What do you think?