# Parsers Engine

## Overview

The Parsers Engine is a set of APIs you interact with anytime you need to transform your design data - tokens & assets - **from your repository token tree into pre-configured file outputs**.

The Parsers Engine serves as the orchestrator for a series of functions, called [**Parsers**](https://docs.specifyapp.com/reference/parsers) designed to transform design data, in parallel and/or chained. By configuring [**Parser Rules**](#parser-rules), you customize **how and where** design tokens and assets are exported.

The Parsers Engine can operate both [**remotely**](#remote-execution), using the Pipe Engine API over HTTP, **and** [**locally**](#local-execution), through the [Specify SDK](https://docs.specifyapp.com/distribute/available-destinations/specify-sdk). This dual capability enables it to be integrated into various workflows, offering flexibility whether working from remote servers, custom CI or directly within local development environments.

The Parsers Engine relies on the [Parsers functions](#the-parsers-functions), which are actual converter implementations from the SDTF tokens to their representation in various formats and languages.

## **Parser Rules**

As the medium to interact with the Parsers Engine, the parser rules are meant to be configured to follow your output needs.

A parser rule is simply a JSON object with two properties:

**`name`**: the name of the rule *— we recommend setting up the purpose: CSS variables, Icons export...*

**`parsers`**: an array of [parser configuration](#parser-configuration-properties)

#### Parser Configuration

**`name`**: the name of the parser - to-json, to-tailwind over the [parsers list](https://docs.specifyapp.com/reference/parsers#available-parsers).

**`output`**: an object describing the desired output type - can be optional when no output is expected.

{% hint style="info" %}
Looking for how to configure the output property? 👉 review the [Rule Output type](https://docs.specifyapp.com/reference/parsers-engine#rule-output-type) reference.
{% endhint %}

**`options`**: an object of arbitrary keys and values defined by the parser - can be optional.

{% hint style="info" %}
Looking for a precise parser option? 👉 review the full [parsers list](https://docs.specifyapp.com/reference/parsers#available-parsers).
{% endhint %}

#### Example of a parser rule for a CSS custom properties output

```json
{
  "rules": [
    {
      "name": "Generate tokens as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties", // parser name
          "output": {
            "type": "file",
            "filePath": "public/css/tokens.css" // ouput will be a file
          },
          "options": { // parser specific options
            "tokenNameTemplate": "--{{groups}}-{{token}}",
            "selectorTemplate": "[data-theme=\"{{mode}}\"]"
          }
        }
      ]
    }
  ]
}
```

### Parser rules templates

{% hint style="info" %}
To get started with the parser rules 👉 heads up to the [Parser Rules templates](https://docs.specifyapp.com/resources/parser-rules-templates) resources.
{% endhint %}

## Remote execution

Executed over HTTP, the parser rules are sent over to Specify servers to evaluate, transform and return the structured result.

[All destinations](https://docs.specifyapp.com/distribute/available-destinations) are compatible with the remote execution.

For some destinations, like [Github](https://docs.specifyapp.com/distribute/available-destinations/github) & the [Specify CLI](https://docs.specifyapp.com/distribute/available-destinations/cli) you need a Configuration file in order to keep track of your desired settings.

### Configuration file

A Specify configuration file allows you to:

* Define the [repository](https://docs.specifyapp.com/overview#repository) source from which to fetch design data.
* Provide a personal access token as authentication credentials for your user.
* Describe the [parsers rule(s)](#parserrule) to configure your ouput.

By default the file is named `.specifyrc.js` or `.specifyrc.json`

{% hint style="info" %}
Looking for the configuration file details? 👉 review the [Configuration file](https://docs.specifyapp.com/reference/parsers-engine#configuration-file) reference
{% endhint %}

## Local execution

Executed on the local environment, the parser rules are evaluated by the [Specify SDK](https://docs.specifyapp.com/distribute/available-destinations/specify-sdk).

Only the [generation parsers](#generation-parsers) are meant to be used in a local execution. In fact, you can apply any mutation on your token tree using the [SDTFClient](https://docs.specifyapp.com/reference/specify-sdk/sdtfclient) API, before generating the final output.

Once executed, the parsers pipeline yields the result back to the SDK instance.

{% hint style="info" %}
Get started with local execution 👉 review the [Execute a parser locally](https://docs.specifyapp.com/guides/specify-sdk-usage-101/executing-parsers#execute-a-parser-locally) guide.
{% endhint %}

## The Parsers functions

Parsers play a pivotal role. They are functions acting as interpreters and transformers of design tokens. They process the initial token tree and apply a set of transformations toward the expected output. Each parser, whether it pertains to utilities or generation, contributes to the workflow by either mutating the token tree or generating tangible assets and code snippets respectively.

{% hint style="info" %}
Looking for the parsers settings? 👉 review the [Parsers reference](https://docs.specifyapp.com/reference/parsers).
{% endhint %}

### Utility parsers

Utility parsers **mutate the design token tree**, through dedicated functions like `filter`, `convert-color`, `change-case`…

You configure their `options` property to instruct the changes to apply to your token tree before it get passed to the next step.

{% hint style="info" %}
The utility parsers are only available to the [Remote execution](#remote-execution) of the Parsers Engine.
{% endhint %}

### Generation parsers

Code generation parsers **generate one or several outputs** like CSS, JavaScript, TypeScript or assets like SVGs or bitmaps.

You configure their `output` property to produce the files that will end up in your codebase.

The `options` property is also available for most of the generation parsers.