@maniascript/api/README.md

Maniascript API generator

# Maniascript API

Parse the maniascript documentation file generated by the game executable (`game.exe /generatescriptdoc=maniascript.h`) and generate an object describing the maniascript API.

## Installation

Install with npm: `npm install @maniascript/api`.

## Binary

The package exposes a `generate-api` command.

```
Usage: generate-api [options]

Generate a typescript or json api file from a maniascript documentation file

Options:
  --in <path>         Path to the maniascript documentation file
  --out <path>        Path of the file were the api will be generated
  --format <json|ts>  Format of the data. Must be "json" or "ts"
  --help              Display help
```

Example: `generate-api --format json --in path/to/input/maniascript.h --out path/to/output/maniascript.json`

## Import

### api

`import { api } from '@maniascript/api'`

`api` is an object describing Trackmania and Maniaplanet maniascript api.

```ts
{
  trackmania: {
    classNames: [
      "CMlScript",
      "CManiaApp",
      "CEditorMainPlugin",
      "CServerPlugin",
      "CSmMode",
      "CSmAction",
      "CSmMapType",
      "CNod",
      ...
    ],
    namespaceNames: [
      "TextLib",
      "MathLib",
      ...
    ],
    classes: {
      CMlScript: {
        rawDocumentation: '/*! \brief: Brief description\nLong description\n\param _paramName : parameter description\n*/',
        documentation: {
          brief: 'Brief description',
          description: 'Long description',
          params: [{
            name: '_paramName',
            description: 'parameter description'
          }]
        },
        enums: {
          LinkType: {
            rawDocumentation: '/*! Raw documentation string */',
            documentation: {
              brief: '',
              description: 'Raw documentation string',
              params: []
            },
            values: [
              "ExternalBrowser",
              ...
            ]
          }
        },
        variables: {
          Page: {
            rawDocumentation: '/*! Raw documentation string */',
            documentation: {
              brief: '',
              description: 'Raw documentation string',
              params: []
            },
            isConst: true,
            type: {
              category: "class",
              name: "CMlPage"
            }
          },
          ...
        },
        functions: {
          IsKeyPressed: [
            {
              rawDocumentation: '/*! Raw documentation string */',
              documentation: {
                brief: '',
                description: 'Raw documentation string',
                params: []
              },
              type: {
                category: "literal",
                name: "Boolean"
              },
              parameters: [
                {
                  type: {
                    category: "literal",
                    name: "Integer"
                  },
                  name: "KeyCode"
                }
              ]
            }
          ],
          ...
        }
      },
      ...
    },
    namespaces: {
      MathLib: {
        enums: { ... },
        variables: { ... },
        functions: { ... }
      },
      ...
    }
  },
  maniaplanet: { ... }
}
```

* `classNames` contains the name of all classes listed in the `classes` object.
* `namespaceNames` contains the name of all namespaces listed in the `namespaces` object.
* `classes` contains the description of each of this classes.
* `namespaces` contains the description of all the default maniascript libraries. eg: `MathLib`, `TextLib`, ...

### generate

`import { parse, generateFromParseResult, generateFromInput, generateFromFile } from '@maniascript/api'`

There are three functions that take different kinds of input and return an an object describing the `api`.

* `generateFromParseResult` generate the api from the result of the `parse()` function.
* `generateFromInput` generate the api from a text input.
* `generateFromFile` generate the api from a path to a maniascript documentation file.

```ts
const result = parse('Content of a `maniascript.h` documentation file')
const apiFromParseResult = generateFromParseResult(result)
const apiFromInput = generateFromInput('Content of a `maniascript.h` documentation file')
const apiFromFile = await generateFromFile('./path/to/maniascript.h')
```

### execute

`import { execute } from '@maniascript/api'` or `const { execute } = require('@maniascript/api')`

`execute` is a function that takes the path to the maniascript documentation file to parse and create a file containing the description of the api defined in the documentation in json format.

```ts
await execute('path/to/maniascript.h')
// generate a file: 'path/to/maniascript.json'
```

Optionally, `execute` can take a path to the file where the api will be generated and a format for the output.

```ts
await execute('path/to/maniascript.h', 'path/to/api.ts', 'ts')
// or
await execute('path/to/maniascript.h', 'path/to/api.json', 'json')
```