unitfile-parser/README.md

# unitfile-parser

This is a small utility library to parse systemd unitfiles to- and from JavaScript data structures. Three formats are available:
1. `string`, which is the representation inside a unit file,
2. `ast`, which is a JS object representation of the parser AST, including comments,
3. `data`, which is a normalized representation of the data, useful to do general computing. It hast the following format:

```
{
  title: String,
  settings: {
    [key:String]: String|String[],
  }
}[]
```

Conversions are available in all directions between these formats, with the only external dependency being `chevrotain`.

This package does not know or check whether the logic of a unit file is correct (e.g. are you using the correct names for options, etc.), it only know what the syntax is supposed to be.

## Usage

For most usecases, you'll only need two functions: `stringToData` and `dataToString`:

```
import { readFile, writeFile } from 'fs/promises';
import { stringToData, dataToString } from 'systemd-unitfiles';

(async () => {
  const unitFilePath = '~/.config/systemd/user/xsettingsd.service';

  // Read the current file from disk
  const fileContents = await readFile(unitFilePath);

  // Transform it to a useful data structure
  const unit = stringToData(fileContents);

  // Change it around
  const transformedUnit = doSomeTransformation(unit);

  // Transform the changed unit back to a string
  const newFileContents = dataToString(transformedUnit);

  // Write the changed file back to disk
  await writeFile(unitFilePath, newFileContents);
})();
```

## API

This package is written for esm5 and above, providing only JS modules (`.mjs` files) to work with.

### stringToAst(input: String): Object

Convert a unit file string to a JS AST.

```
import { readFile } from 'fs/promises';
import { stringToAst } from 'systemd-unitfiles';

readFile('~/.config/systemd/user/xsettingsd.service')
  .then(fileContents => {
    const ast = stringToAst(fileContents);
    console.log(ast);
  });

```

### stringToData(input: String): Array

Convert a unit file string to a normalized representation. This is equivalent to the following:

```
const data = astToData(stringToAst(string));
```

### astToData(ast: Object): Array

Convert the parser ast to a normalized representation.

### astToString(ast: Object): String

Convert an ast to a valid unit file string.

```
import { writeFile } from 'fs/promises';
import { astToString } from 'systemd-unitfiles';

const ast = // some ast here

const unitFile = astToString(ast);

writeFile('~/.config/systemd/user/xsettingsd.service', unitFile);
```

### dataToAst(data: Array): Object

Convert the normalized JS representation to the parser ast.

### dataToString(data: Array): String

Convert the normalized JS representation to a valid unit file string. This is equivalent to the following:

```
const string = astToString(dataToAst(data));
```

### Lexer 

Constructor for a lexer that extends the [chevrotain Lexer](https://sap.github.io/chevrotain/documentation/7_0_3/classes/lexer.html).

### Parser 

Constructor for a parser that extends the [chevrotain CSTParser](https://sap.github.io/chevrotain/documentation/7_0_3/classes/cstparser.html).

### visitorCreator(parser: Parser): ICSTVisitor

Function that takes a parser and returns a visitor for that parser that would normalize the ast to the abovementioned data format.

## Motivation

There already is a `systemd-unitfile` package on npm, but it is unmaintainted and has some bad behaviour, like not recognizing multiline values.