reascriptluaparser

About

This tool parses the reascripthelp.html file generated by Reaper and generates a JSON containing an array of methods from the api. It can be used as as CLI that will write a reaperAPI.json file to the same directory of the given html file, or as a module that receives a string with the html and returns an array of methods.

If you need help generating reascripthelp.html from reaper, see Generating Reaper API HTML

The resulting api has been eye checked but not extensively manually checked yet. if you find any bugs or unexpected output, please open an issue.

Example parsed result

[
  // Lua: MediaItem reaper.AddMediaItemToTrack(MediaTrack tr)
  {
    "name": "AddMediaItemToTrack",
    "params": [{ "type": "MediaTrack", "name": "tr" }],
    "returns": [{ "type": "MediaItem" }],
    "namespace": "reaper",
    "description": "creates a new media item."
  },
  // Lua: integer reaper.AddProjectMarker(ReaProject proj, boolean isrgn, number pos, number rgnend, string name, integer wantidx)
  {
    "name": "AddProjectMarker",
    "params": [
      { "type": "ReaProject", "name": "proj" },
      { "type": "boolean", "name": "isrgn" },
      { "type": "number", "name": "pos" },
      { "type": "number", "name": "rgnend" },
      { "type": "string", "name": "name" },
      { "type": "integer", "name": "wantidx" }
    ],
    "returns": [{ "type": "integer" }],
    "namespace": "reaper",
    "description": "Returns the index of the created marker/region, or -1 on failure. Supply wantidx>=0 if you want a particular index number, but you'll get a different index number a region and wantidx is already in use."
  },
  // Lua: integer reaper.DeleteTakeStretchMarkers(MediaItem_Take take, integer idx, optional number countIn)
  {
    "name": "DeleteTakeStretchMarkers",
    "params": [
      { "type": "MediaItem_Take", "name": "take" },
      { "type": "integer", "name": "idx" },
      { "type": "number", "name": "countIn", "optional": true }
    ],
    "namespace": "reaper",
    "description": "Deletes one or more stretch markers. Returns number of stretch markers deleted."
  }
]

Install

Use as a CLI:

npm install --global reascriptluaparser

Use as a module in your project:

npm install reascriptluaparser

CLI Usage

This tool does one thing, and one thing only: It parses a given html file and saves the parsed array to a JSON file in the same directory of the source file.

reascriptluaparser /path/to/reascripthelp.html

options:

Options:
  -V, --version  output the version number
  -h, --help     display help for command

Module Usage

This package is written in Typescript and bundles it's own types declarations. It can therefore be used out of the box in JS or TS projects.

It exports a single Synchronous method that takes a string containing the HTML from the file and returns an array of methods

In case of malformed HTML or invalid input the parser will throw.

Minimal Example

Javascript + Node

const fs = require('fs')
const { parser } = require('reascriptluaparser')

const html = fs.readFileSync('./reascripthelp.html', 'utf8')
const api = parser(html)

Typescript (depends on your tsconfig.json)

import fs = require('fs')
import { parser } from 'reascriptluaparser'

const html = fs.readFileSync('./reascripthelp.html', 'utf8')
const api = parser(html)

Types

typescript types:

interface Method {
  name: string
  params?: Variable[]
  returns?: Variable[]
  description?: string
  namespace?: string
}

interface Variable {
  type?: string
  name?: string
  optional?: boolean
}

reascriptluaparser returns type Method[]

Generating Reaper API HTML

Open Reaper
Select Help -> ReaScript Documentation from the top menu. this will open a page in your browser
The address for the page points to the generated file. You might want to copy it somewhere else.

Known Issues

parser ignores entries Lua: reaper.new_array([table|array][size]), gfx.triangle(x1,y1,x2,y2,x3,y3[x4,y4...]), and gfx.printf("format"[, ...])

Claudiohbsantos/reascriptluaparser