= Alda REPL server API

Alda REPL clients and servers communicate using the https://nrepl.org[nREPL]
protocol, with https://en.wikipedia.org/wiki/Bencode[bencode] over TCP as the
transport.

[TIP]
--
You can also send JSON messages via the Alda CLI. For example:

[source]
----
$ alda repl --client --port 34223 --message '{"op": "eval-and-play", "code": "harmonica: c8 d e f"}'
{"id":"17aa14c2-fa23-4bde-af4d-85839a85fc5d","session":"2d9ca3d1-2bcb-4e8b-9344-957ee4e4bdd9","status":["done"]}

$ alda repl --client --port 34223 --message '{"op": "eval-and-play", "code": "g f e d c2"}'
{"id":"27612a45-7d4a-4f7e-b65d-be6cf5107abf","session":"60f70325-efd6-492c-9e8f-279eba76a4d7","status":["done"]}

$ alda repl --client --port 34223 --message '{"op": "score-text"}'
{"id":"f1f45d28-d7f3-4fc2-b605-0fbc2b8d4ae1","session":"3da40081-1007-4630-bb38-b19abeaeef0a","status":["done"],"text":"harmonica: c8 d e f\ng f e d c2\n"}
----
--

== Operations

=== `describe`

Returns information on the Alda REPL server.

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `ops` - the operations available on the Alda REPL server
* `problems` if there were any
* `status`
* `versions` - Alda version information

=== `eval-and-play`

Parses the provided input in the context of the current score, updates the score
with the parse results, and plays any new events that were added to the score.

This is the operation that occurs in an Alda REPL session each time you enter a
line of Alda code and press Enter.

Required parameters::
* `code` - a string of Alda code

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any

=== `export`

Exports the current score to MIDI and returns the binary data to be saved as a
MIDI file.

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any
* `binary-data` - exported MIDI binary data for the current score

=== `instruments`

Returns the list of instruments available to use in an Alda score.

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any
* `instruments` - the list of available instruments

=== `load`

Parses the provided input as a new score and loads the score into the REPL
server.

Required parameters::
* `code` - a string of Alda code

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any

=== `new-score`

Resets the REPL server state and initializes a new score.

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any

=== `replay`

Plays back the score currently loaded into the REPL server.

Required parameters::
{blank}

Optional parameters::
* `from` - a string that is either a minute-second marking (e.g. `0:30`) or a
marker name (e.g. `verse`), representing where in the score to start playing
* `to` - a string that is either a minute-second marking (e.g. `1:00`) or a
marker name (e.g. `chorus`), representing where in the score to stop playing

Returns::
* `status`
* `problems` if there were any

=== `score-ast`

Returns the parsed AST of the current score. (This is the output that you get
when you run `alda parse -o ast ...` at the command line.)

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any
* `ast` - the parsed AST of the current score, as a JSON string

=== `score-data`

Returns a data representation of the current score. (This is the output that you
get when you run `alda parse -o data ...` at the command line.)

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any
* `data` - a data representation of the current score

=== `score-events`

Returns the parsed events output of the score. (This is the output that you get
when you run `alda parse -o events ...` at the command line.)

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any
* `events` - the parsed events output of the current score

=== `score-text`

Returns the text (Alda code) of the current score.

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any
* `text` - the Alda code of the current score

=== `stop`

Stops playback.

Required parameters::
{blank}

Optional parameters::
{blank}

Returns::
* `status`
* `problems` if there were any

