ly-client

A wrapper around the python-ly package providing tools to work with LilyPond input code. It can interact with the standalone ly tool or the ly-server HTTP server.

Installation

The installation takes two parts: the node module and the Python package, which has to be installed and available. We intend to enable ly-client to run against a remotely running HTTP server, but hasn't been implemented yet.

Install the node module using npm:

$ npm install ly-client

optionally adding --save to register the module in your current package.json.

python-ly is available through pip:

$ pip install python-ly

optionally using sudo, depending on your operating system. You can check if it installed and available by typing

ly -h

from anywhere and using the opportunity to read the help document.

Usage

In order to use ly-client you should be familiar with python-ly and its features as the node module provides more or less a wrapper around the Python tool. The best place for this is the documentation on ReadTheDocs.

The major difference to using the original Python package is that ly-client never works on files. Instead the data is always provided as a function argument and returned as the function result.

Loading the Module

Make the module available with

var ly = require('ly-client');

which will give you access to its functionality:

ly.info

var m = ly.info.methods()

will assign an object to m with the following boolean fields:

• m.cli
• m.server
• m.server_running

The first two items tell whether the CLI tool and the HTTP server are available on the local machine, while the third item checks for the accessibility of the HTTP server. (Currently this is restricted to localhost, so the last two options are quite dependent on each other. But we intend to make it work with remote servers as well.)

You can use these informations to decide which access methods to use. If a request is executed against an unavailable resource errors will be thrown.

ly.info.version()

will return a string with the version of python-ly, in the form ly 0.9.4.

Prepare a request

Requests have to be prepared (similar to queries in database systems). This is because in the majority of use cases the same processes are applied to multiple documents. The preparation is done using the function

ly.prepare(commands, options, variables, doc)

All arguments take a single string, with their meaning lent from python-ly.

• commands
  Is the same string as the command string in python-ly. That is, it can contain an arbitrary number of commands, separated by semicolons.
  Valid commands are listed in the python-ly documentation. Commands may have arguments, as defined in the docs as well.
  Instead of a command there can also be variable assignments (see below). The assignments applied here are applied between the execution of different commands.
• options
  An options string as on the ly script's commadn line. Options apply to all contained commands. This argument is optional, but if there are any further arguments you have to provide an empty string here
• variables
  One or more variables as per python-ly's documentation. Multiple entries are separated by semicolons, and it is not necessary to provide the -d indicator. Variables assigned here will be set before the execution of the first command.
• doc
  It is possible to already pass the actual LilyPond document/data at this point. But usually you will provide this only in the actual execution of the request.

Please familiarize yourself with how python-ly works and be especially aware of the different command types. If you combine the execution of multiple commands there are plenty of ways to produce meaningless results. In doubt you should rather process one task at a time. Also the structure of the resulting data differs significantly when talking to the CLI or to the server. (We hope to streamline the interface in a future version of ly-client, though.)

Execute a Request

Once a request is prepared it can be executed using a number of different functions. Currently only synchronous requests are supported by there will be asynchronous versions available that return promises. Reuqests are executed either by invocing the command line script or by sending an HTTP request to python-ly's server component. It seems that the cli request is processed faster than the HTTP request, so generally this way is preferrable.

ly.exec.cli_sync(doc)
ly.exec.server_sync(doc)
ly.exec.sync(doc)

The first function executes a request through the command line script, while the second function sends a server request. The third function sends a server requests if the server is running and uses the CLI as a fallback.

The doc argument is the actual LilyPond data to be passed to python-ly. it is optional, and if it is not passed the value from the previous invocation is reused.

Using the Return Value

Currently the cli and the server versions return the result in substantially different form. While the CLI returns the result as a single string the server passes a stringified JSON object that has first to be parsed using JSON.parse().

When using the CLI ist is important to note that the output of all commands will be simply concatenated to one single string. So if that's necessary at all the client has to take care of requesting a meaningful set of commands whose output can still be parsed.

The server version packages the results of the different types of commands in the following structure:

{
  "info": [
    {
      "command": <command-name>,
      "info": <result>
    }
    ...
  ],
  "doc": {
    "content": <processed-input-document>,
    "commands": [
      "command1",
      "command2"
    ]
  },
  "exports": [
    {
      "command": <command>,
      "doc": <result>
    }
  ]
}

As an example: if highlight was used as the only “export” command then the resulting HTML document will be available in result['exports'][0]['doc'].