Requirements

The only requirement is to have Java 1.8 installed.

Installation

The SMNP suite has no any install scripts. You are able to use the tool simply by downloading required jar files and running it by yourself, using java. The base SMNP is provided as an executable app.jar file, which means it is supposed to be executed with java -jar command, i.e.:

$ java <jvm arguments> -jar smnp.jar <smnp arguments>

Apart from the app.jar in order to use the SMNP you have to provide also modules (the smnp.lang at least). The default location of modules is the modules/ directory located at the same files-tree level as app.jar. You are able to override the default location by passing -Dsmnp.modulesDir JVM property (note, that this is a property for JVM, not SMNP so you have to pass it before -jar command-line argument), e.g.:

$ java -Dsmnp.modulesDir=~/.smnp/modules -jar ~/.smnp/app.jar examples/adeste.mus

Getting started

Take a look at the following examples. Feel also free to dive into examples/ directory to find more examples.

Hello, world!

The must-be program of each programming language. The SMNP implementation would look something like this:

import smnp.io;

println("Hello, world!"); # Hello, world!

Play some music

Following example shows the note literals as well as the staff syntax used to produce a polyphonic melody of Prząśniczka - a Polish song composed by Stanisław Moniuszko. The staffs are being consumed by smnp.audio.midi#midi function from smnp.audio.midi module which puts the notes on your system's MIDI engine and eventually plays the song.

import smnp.io;
import smnp.audio.midi;

println("Prząśniczka");
println("by S. Moniuszko");

S = $ 4/4 @a:4d @a:8 @c5 @d5         | @e5:2 @a @a  | @f5:2 @e5 @d5       | @e5:2d @e5 |
          @e5:4d @h:8 @e5 @h         | @c5:2 @a @c5 | @e5:2 @h @h         | @c5:2d @e5 |
          @g5:4d @f5:8 @e5:4d @d5:8  | @c5:2d @c5   | @d5:4d @d5:8 @h @g  | @e5:2d 4   |
          @e5:4d @f5:8 @e5:4d @d#5:8 | @e5:2 @a5:2  | @f5:4d @d5:8 @h @e5 | @a:2d 4    ||;

A = $ 4/4 1                          | @a:2 2       | @a:2 2              | @a:2d 4    |
          @g#:4d @g#:8 @g# @g#       | @a:2 2       | @g#:2 @g# @g#       | @a:2d 4    |
          1                          | 1            | @h:4d @h:8 @g 4     | @c5:2d 4   |
          1                          | 1            | 1                   | 1          ||;

midi({ bpm -> 284 }, S, A);

Presets

Presets are predefined snippets of code that are considered to be useful in number of cases and should be available with a simple command. You can run preset simply by passing -p NAME argument with desired preset's name.

Presets also supports parameters, which can be passed using -P name argument with desired parameter's name or -P name=value argument with desired parameter's name and value.

So far, SMNP implementation provides following presets:

metronome
midi
mic
alert

All of these presets supports help parameter. You can simply provide -P help parameter to find out more about given preset, for example:

$ java -jar smnp.jar -p alert -P help
Run sound alarm

Optional parameters:
  - cycles: int           - set number of cycles that running alarm has to reach to get quiet
                            infinite on absence of argument
  - melody: string [beep] - set melody of alert
                            available melodies:
                              - beep
                              - bell
                              - alarm1
                              - alarm2

Command line interface

usage: [-h] [--tokens] [--ast] [--dry-run] [--modules-all] [--modules MODE]
       [-P PARAMETER]... [-p NAME] [-c CODE] [SOURCE]

optional arguments:
  -h, --help              show this help message and exit

  --tokens                print tokens

  --ast                   print abstract syntax tree

  --dry-run               don't evaluate parsed code

  --modules-all           print all available modules

  --modules MODE          print modules loaded by executed script. Allowed
                          values for MODE are: list | tree | content. The
                          'list' option prints loaded modules as list of
                          canonical names of each one. The 'tree' option
                          organises modules into the tree model and then
                          prints them. The 'content' option is the same as
                          tree, however, prints also contained functions and
                          methods.

  -P PARAMETER,           define parameter to be consumed in script. Default
  --parameter PARAMETER   syntax for parameter is 'key=value' (whitespaces
                          around '=' are not allowed). In this case value will
                          be of string type. However, it is also possible to
                          pass parameter without any value. In this case,
                          value will be of bool type. The parameters are
                          available through global-accessible variable of map
                          type and of '__param__' name.

  -p NAME, --preset NAME  load preset by name and execute it. Preset is a
                          predefined snippet of SMNP code that allows user to
                          perform some useful action without having to script
                          it himself. Presets are located in SMNP executable
                          JAR file. Available presets: metronome, midi, mic,
                          alert

  -c CODE, --code CODE    inline code to be executed


positional arguments:
  SOURCE                  file with SMNP language code to be executed

Simple Music Notation Processor

SMNP Language Reference

Modules and standard library: