# `StylesheetParser.Syntax.Parser`
[🔗](https://github.com/zestcreative/stylesheet_parser/blob/v0.1.0/lib/stylesheet_parser/syntax/parser.ex#L1)

The parsing algorithms of [CSS Syntax Level 3](https://www.w3.org/TR/css-syntax-3/#parsing), as
its current draft has them with [CSS Nesting](https://www.w3.org/TR/css-nesting-1/), over the
tokenizer's tokens, `{type, value, metadata}` with `[line: l, column: c]`, like Elixir AST.

Rules, declarations, functions and simple blocks carry the `line` and `column` where they start.
The component values inside them (a declaration's value, an at-rule's prelude, a block's or a
function's value) are `{type, value}`, without positions.

A qualified rule's prelude is its selector list (`StylesheetParser.Selector.Parser`), with relative
selectors such as `> a` when it's nested in a style rule, or in `@keyframes` its component
values, such as `50%`. A block, a style rule's or an at-rule's, is its declarations and rules in
order.

Malformed input is dropped, as the spec recovers from it: a declaration with no colon, anything
else where a declaration belongs, a rule whose selectors don't parse or that ends before its
block. An unclosed block or function closes at the end of the input. `parse_stylesheet/1` keeps
each as a `StylesheetParser.ParseError` in the stylesheet's `errors`, with the line and
column where it is; `parse_rules/2` and `parse_declarations/1` return them with their results.

`StylesheetParser` tokenizes CSS and parses it with these; they're for parsing tokens you
already have:

    iex> {:ok, tokens} = StylesheetParser.tokenize("a { color: red } @media print { a { color: black } }")
    iex> {:ok, stylesheet} = StylesheetParser.Syntax.Parser.parse_stylesheet(tokens)
    iex> Enum.map(stylesheet.rules, &to_string/1)
    ["a { color: red; }", "@media print { a { color: black; } }"]
    iex> {:ok, rule, rest} = StylesheetParser.Syntax.Parser.build_qualified_rule(tokens)
    iex> {to_string(rule), hd(rest)}
    {"a { color: red; }", {:whitespace, " ", [line: 1, column: 17]}}

# `build_at_rule`

# 5.4.2. Consume an at-rule

Consume the next input token. Create a new at-rule with its name set to the value of the current
input token, its prelude initially set to an empty list, and its value initially set to nothing.

Repeatedly consume the next input token:

- `<semicolon-token>` - Return the at-rule.
- `<EOF-token>` - This is a parse error. Return the at-rule.
- `<{-token>` - Consume a simple block and assign it to the at-rule’s block. Return the at-rule.
- anything else - Reconsume the current input token. Consume a component value. Append the
  returned value to the at-rule’s prelude.

The block is its declarations and rules (the draft's "consume a block's contents"). Returns the
component values after the at-rule.

# `build_component_value`

# 5.4.6. Consume a component value

- If the current input token is a `<{-token>`, `<[-token>`, or `<(-token>`, consume a simple
  block and return it.
- Otherwise, if the current input token is a `<function-token>`, consume a function and return it.
- Otherwise, return the current input token.

# `build_declaration`

# 5.4.5. Consume a declaration

Over component values that start with an `<ident-token>`:

1. While the next input token is a `<whitespace-token>`, consume the next input token.
2. If the next input token is anything other than a `<colon-token>`, this is a parse error.
   Return nothing. Otherwise, consume the next input token.
3. While the next input token is a `<whitespace-token>`, consume the next input token.
4. As long as the next input token is anything other than an `<EOF-token>`, consume a component
   value and append it to the declaration’s value.
5. If the last two non-`<whitespace-token>`s in the declaration’s value are a `<delim-token>`
   with the value "!" followed by an `<ident-token>` with a value that is an ASCII
   case-insensitive match for "important", remove them from the declaration’s value and set the
   declaration’s important flag to true.
6. While the last token in the declaration’s value is a `<whitespace-token>`, remove that token.
7. Return the declaration.

From the draft: unless it's a custom property, a value with a `{}` block in it is the block
alone, else it's nothing; and a `unicode-range` value has its `:urange`s, such as `U+0-7F`.

# `build_function`

# 5.4.8. Consume a function

Create a function with a name equal to the value of the current input token (without its `(`),
and with a value which is initially an empty list. Repeatedly consume the next input token:

- `<)-token>` - Return the function.
- `<EOF-token>` - This is a parse error. Return the function.
- anything else - Reconsume the current input token. Consume a component value and append the
  returned value to the function’s value.

# `build_qualified_rule`

# 5.4.3. Consume a qualified rule

Create a new qualified rule with its prelude initially set to an empty list, and its value
initially set to nothing.

Repeatedly consume the next input token:

- `<EOF-token>` - This is a parse error. Return nothing.
- `<{-token>` - Consume a simple block and assign it to the qualified rule’s block. Return the
  qualified rule.
- anything else - Reconsume the current input token. Consume a component value. Append the
  returned value to the qualified rule’s prelude.

A rule whose prelude isn't a selector list is nothing too, a syntax error. Returns the component
values after the rule.

# `build_simple_block`

# 5.4.7. Consume a simple block

The ending token is the mirror variant of the current input token. Repeatedly consume the next
input token and process it as follows:

- ending token - Return the block.
- `<EOF-token>` - This is a parse error. Return the block.
- anything else - Reconsume the current input token. Consume a component value and append it to
  the value of the block.

# `parse_component_value`

# 5.3.7. Parse a component value

1. While the next input token is a `<whitespace-token>`, consume the next input token.
2. If the next input token is an `<EOF-token>`, return a syntax error.
3. Consume a component value and let value be the return value.
4. While the next input token is a `<whitespace-token>`, consume the next input token.
5. If the next input token is an `<EOF-token>`, return value. Otherwise, return a syntax error.

# `parse_component_values`

# 5.3.8. Parse a list of component values

1. Repeatedly consume a component value until an `<EOF-token>` is returned, appending the
   returned values (except the final `<EOF-token>`) into a list. Return the list.

# `parse_declaration`

# 5.3.5. Parse a declaration

1. While the next input token is a `<whitespace-token>`, consume the next input token.
2. If the next input token is not an `<ident-token>`, return a syntax error.
3. Consume a declaration. If anything was returned, return it. Otherwise, return a syntax error.

# `parse_declarations`

# 5.3.6. Parse a list of declarations

The draft's "parse a block's contents": the declarations, at-rules and nested style rules of a
style attribute, in order. Returns `{:ok, contents, errors}`, the errors as a stylesheet's are.

# `parse_rule`

# 5.3.4. Parse a rule

1. While the next input token is a `<whitespace-token>`, consume the next input token.
2. If the next input token is an `<EOF-token>`, return a syntax error.
   Otherwise, if the next input token is an `<at-keyword-token>`, consume an at-rule, and let rule be the return value.
   Otherwise, consume a qualified rule and let rule be the return value. If nothing was returned, return a syntax error.
3. While the next input token is a `<whitespace-token>`, consume the next input token.
4. If the next input token is an `<EOF-token>`, return rule. Otherwise, return a syntax error.

# `parse_rules`

# 5.3.3. Parse a list of rules

1. Consume a list of rules from the stream of tokens, with the top-level flag unset.
2. Return the returned list.

Returns `{:ok, rules, errors}`, the errors as a stylesheet's are.

# `parse_stylesheet`

# 5.3.2. Parse a stylesheet

1. Create a new stylesheet.
2. Consume a list of rules from the stream of tokens, with the top-level flag set. Let the return value be rules.
3. Assign rules to the stylesheet’s value.
4. Return the stylesheet.

---

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