Code.string_to_quoted

You're seeing just the function string_to_quoted, go back to Code module for more information.
Link to this function

string_to_quoted(string, opts \\ [])

View Source

Specs

string_to_quoted(List.Chars.t(), keyword()) ::
  {:ok, Macro.t()} | {:error, {location :: keyword(), term(), term()}}

Converts the given string to its quoted form.

Returns {:ok, quoted_form} if it succeeds, {:error, {line, error, token}} otherwise.

Options

  • :file - the filename to be reported in case of parsing errors. Defaults to "nofile".

  • :line - the starting line of the string being parsed. Defaults to 1.

  • :column - (since v1.11.0) the starting column of the string being parsed. Defaults to 1.

  • :columns - when true, attach a :column key to the quoted metadata. Defaults to false.

  • :existing_atoms_only - when true, raises an error when non-existing atoms are found by the tokenizer. Defaults to false.

  • :token_metadata (since v1.10.0) - when true, includes token-related metadata in the expression AST, such as metadata for do and end tokens, for closing tokens, end of expressions, as well as delimiters for sigils. See Macro.metadata/0. Defaults to false.

  • :literal_encoder (since v1.10.0) - how to encode literals in the AST. It must be a function that receives two arguments, the literal and its metadata, and it must return {:ok, ast :: Macro.t} or {:error, reason :: binary}. If you return anything than the literal itself as the term, then the AST is no longer valid. This option may still useful for textual analysis of the source code.

  • :static_atoms_encoder - the static atom encoder function, see "The :static_atoms_encoder function" section below. Note this option overrides the :existing_atoms_only behaviour for static atoms but :existing_atoms_only is still used for dynamic atoms, such as atoms with interpolations.

  • :warn_on_unnecessary_quotes - when false, does not warn when atoms, keywords or calls have unnecessary quotes on them. Defaults to true.

Macro.to_string/2

The opposite of converting a string to its quoted form is Macro.to_string/2, which converts a quoted form to a string/binary representation.

The :static_atoms_encoder function

When static_atoms_encoder: &my_encoder/2 is passed as an argument, my_encoder/2 is called every time the tokenizer needs to create a "static" atom. Static atoms are atoms in the AST that function as aliases, remote calls, local calls, variable names, regular atoms and keyword lists.

The encoder function will receive the atom name (as a binary) and a keyword list with the current file, line and column. It must return {:ok, token :: term} | {:error, reason :: binary}.

The encoder function is supposed to create an atom from the given string. To produce a valid AST, it is required to return {:ok, term}, where term is an atom. It is possible to return something other than an atom, however, in that case the AST is no longer "valid" in that it cannot be used to compile or evaluate Elixir code. A use case for this is if you want to use the Elixir parser in a user-facing situation, but you don't want to exhaust the atom table.

The atom encoder is not called for all atoms that are present in the AST. It won't be invoked for the following atoms:

  • operators (:+, :-, and so on)

  • syntax keywords (fn, do, else, and so on)

  • atoms containing interpolation (:"#{1 + 1} is two"), as these atoms are constructed at runtime.