# `VulnCheck.Literal`
[🔗](https://github.com/Voskan/vulncheck/blob/v1.0.1/lib/vulncheck/literal.ex#L1)

Safe reader for Elixir-syntax data files (`.vulncheck.exs`, `.vulncheck.ignore`,
`mix.lock`, `mix.exs`, `config/*.exs`).

Files are parsed with `Code.string_to_quoted/2` and a static atom encoder, so
**no atoms are created** and **no code is ever evaluated**. Literal values are
converted into a neutral term representation:

  * atoms become `{:atom, "name"}` (except `nil`, `true` and `false`)
  * module aliases become `{:alias, "Elixir.Mod.Name"}`
  * tuples become `{:tuple, [elements]}`
  * maps become `{:map, [{key, value}]}` (insertion order preserved)
  * strings, numbers and lists are kept as they are

Any other expression (function calls, variables, operators, ...) is rejected
with `{:error, {:unsafe_expression, line, code}}` by `to_term/1`.

# `lterm`

```elixir
@type lterm() ::
  {:atom, String.t()}
  | {:alias, String.t()}
  | {:tuple, [lterm()]}
  | {:map, [{lterm(), lterm()}]}
  | [lterm()]
  | binary()
  | number()
  | boolean()
  | nil
```

# `alias_name`

```elixir
@spec alias_name(Macro.t()) :: String.t() | nil
```

Converts an `__aliases__` AST node into its canonical module string, or `nil`.

# `atom?`

```elixir
@spec atom?(Macro.t(), String.t()) :: boolean()
```

Returns `true` if the encoded AST node is the given atom literal.

# `atom_name`

```elixir
@spec atom_name(Macro.t()) :: String.t() | nil
```

Returns the name of an encoded atom AST node, or `nil`.

# `keyword_pairs`

```elixir
@spec keyword_pairs(lterm()) :: {:ok, [{String.t(), lterm()}]} | :error
```

Converts a literal keyword list into `[{key_string, value}]`, or `:error`.

# `kw_get`

```elixir
@spec kw_get(lterm(), String.t(), term()) :: term()
```

Looks up a key in a keyword-like literal list (`[{{:atom, key}, value}]`).

# `parse`

```elixir
@spec parse(String.t(), keyword()) :: {:ok, lterm()} | {:error, term()}
```

Parses a source string and converts it into a literal term.

# `parse_file`

```elixir
@spec parse_file(Path.t()) :: {:ok, lterm()} | {:error, term()}
```

Reads and parses a file into a literal term.

# `quote_string`

```elixir
@spec quote_string(String.t(), keyword()) :: {:ok, Macro.t()} | {:error, String.t()}
```

Parses source into an encoded AST without creating atoms.

# `to_term`

```elixir
@spec to_term(Macro.t()) :: {:ok, lterm()} | {:error, term()}
```

Converts an encoded AST into a literal term, rejecting any executable code.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
