View Source Ymlr.Encode (ymlr v5.1.3)
This module implements the logic of encoding scalars.
Strings and Characters
Printable Characters
The YAML spec defines a set of printable characters c-printable (see
https://yaml.org/spec/1.2.2/#character-set). All these characters can
theoretically be left alone when encoding a string.
Escape Characters
The YAML spec also defines a set of escape charactesr c-ns-esc-char (see
https://yaml.org/spec/1.2.2/#57-escaped-characters). Some of these chars are
also in the printable range c-printable. Being in c-printable means they
could be left alone. I.e. there would be no need to encode them as escape
chars. However, we think in certain cases, escape characters are more
reader friendly than the actual characters. An example is the "next line"
character (U+0085 or \N). It is part of c-printable. However, on the
screen this character cannot be distinguished from a simple "line feed"
character (U+000A or \n). Therefore all characters in c-ns-esc-char with
the exception of \n and \t are always encoded using their escape character.
Other 8-bit Unicode Characters
Any 8-bit unicode character that neither a printable nor an escape character has to be encoded using one of the three unicode escape characters \x, \u or \U (i.e. \xXX, \u00XX or \U000000XX).
Double Quotes for Escape Characters
Printable Characters can be encoded unquoted, single-quoted or double-quoted. Escape characters require double quotes.
Chars with Special Treatments
Chars \n and \t
These two characters are never converted to their escape characters. One exception: If the given string is literally just a newline, we encode it as "\n" (double quotes required for escape chars) rather than a single newline.
Chars " and \
These two characters have escape characters (\" and \\) but they are also
part of the of the printable character range c-printable and they have a
well-defined presentation on the screen. Ocurrance of these characters don't
enforce double-quotes but if they occur within a string that for other reasons
requires double-quotes, they need to be escaped.
Implemented Decision Logic
First matching rule is applied:
- Char is
\tor\n=> leave alone - Char is
"or\=> if within double quotes, escape. Otherwise leave alone. - Char has an escape character (i.e. is part of
c-ns-esc-char) => force double quotes and encode as escape character - Char is a printable character => leave alone
- Char is a non-printable character => force double quotes and encode as \xXX (only 8-bit supported for now)
Summary
Functions
Encodes the given data as YAML string.
Encodes the given data as YAML string. Raises if it cannot be encoded.
Functions
@spec list(data :: list(), indent_level :: integer(), opts :: Ymlr.Encoder.opts()) :: iodata()
@spec map(data :: map(), indent_level :: integer(), opts :: Ymlr.Encoder.opts()) :: iodata()
@spec to_s(data :: term(), opts :: Ymlr.Encoder.opts()) :: {:ok, binary()} | {:error, binary()}
Encodes the given data as YAML string.
Examples
iex> Ymlr.Encode.to_s(%{a: 1, b: 2})
{:ok, "a: 1\nb: 2"}@spec to_s!(data :: term(), opts :: Ymlr.Encoder.opts()) :: binary()
Encodes the given data as YAML string. Raises if it cannot be encoded.
Examples
iex> Ymlr.Encode.to_s!(%{})
"{}"
iex> Ymlr.Encode.to_s!(%{a: 1, b: 2})
"a: 1\nb: 2"
iex> Ymlr.Encode.to_s!(%{"a" => "a", "b" => :b, "c" => "true", "d" => "100"})
"a: a\nb: b\nc: 'true'\nd: '100'"