2373 lines
76 KiB
Markdown
2373 lines
76 KiB
Markdown
# Simple Music Notation Processor
|
|
|
|
## What is it?
|
|
SMNP is a command line tool aimed on doing music stuff using custom domain-specific language.
|
|
You are able to create music (both monophonic and polyphonic) using simple notation
|
|
and then synthesize it with custom settings, plot the signal, evaluate DFT on it and so on.
|
|
Music tools can be used not only to create music but also to prepare kind of scenarios
|
|
of ear trainings like recognizing intervals etc.
|
|
Apart of that developed domain-specific language offers you tools known from most popular
|
|
programming languages like conditional statements, loops, variable mechanism,
|
|
functions (including defining custom ones) etc.
|
|
|
|
|
|
## For what?
|
|
You might ask whether such kind of tool including design of custom language isn't
|
|
over-engineering of ear-training problem. There are a lot of ear-training tools developed even
|
|
on mobile platforms which can make them more convenient to use because of their portability feature.
|
|
|
|
The reasons for this tool are:
|
|
* I'm Java developer and I just wanted to get know more Python, which I used to use at the college.
|
|
And well, I'm starting from the assumption, that te best thing that you can do to learn new programming
|
|
language is... creating a new one with it. ;-)
|
|
Besides, I'm kind of interested in technical side of programming languages that I'm using at work,
|
|
so designing and implementing a custom language from scratch would be a nice experience.
|
|
* I'm musician also and no one of available tools is suitable for me.
|
|
I'm church organist and most of my work is based on dialogue between me and priest. He can
|
|
sing melodies in different keys and it requires me to answer keeping the same key.
|
|
My tool allows me to create scenarios that can pick one key randomly and play melody
|
|
waiting for my answer (basing on input from microphone).
|
|
* As a musician I'm also keen on physic nature of sounds and relations between them.
|
|
All audio stuff (except hardware layer) implemented to this tool is created from scratch.
|
|
It means that the tool synthesises sound by itself and makes use of 3rd party library
|
|
only to send compiled wave to speakers.
|
|
|
|
## Disclaimers
|
|
1. Readability of the code and its structure is one of most important things
|
|
related to educational aspect of the project. And in spite of having huge negative impact
|
|
on efficiency of the tool, according to one of the assumptions
|
|
it has much higher priority. So don't be surprised
|
|
if the tool turns out to be extremely slow or ineffective.
|
|
2. I try writing consistent code and sticking with some convention of programming of course,
|
|
however, as a Java developer I like Java guidelines and I really don't
|
|
like PEP8 (especially snakecased identifiers).
|
|
Just don't be surprised if you see Java-like code - it has been intentionally written.
|
|
|
|
## SMNP language
|
|
As mentioned before, SMNP introduces new language. All language evaluation engine (tokenizer, parser and evaluator)
|
|
is implemented without any 3rd party libraries and frameworks, just using vanilla Python.
|
|
|
|
### About language
|
|
SMNP language is interpreted, high-level, formal language with syntax
|
|
mostly inspired by Java language and - according to Chomsky's hierarchy - *context-free* grammar.
|
|
|
|
#### Type system
|
|
SMNP is dynamic language, because there is no any static analyser between
|
|
parsing and evaluating stages. It means that any type-mismatching
|
|
will be raised on runtime, when control flow reacheas the point of error.
|
|
|
|
For example:
|
|
```
|
|
function foo(integer n) {
|
|
println(n);
|
|
}
|
|
|
|
x = false;
|
|
|
|
if (x) {
|
|
foo("hello");
|
|
}
|
|
```
|
|
As long as `x == false`, the code will be executed without any errors,
|
|
even though `foo` function expects `integer` argument and is being called
|
|
with `string`.
|
|
However if you switch `x` value to `true`, error will be raised when
|
|
control flow reaches `foo` function invocation with wrong argument's type.
|
|
|
|
Even though there is no real definition of *strongly-typed language*,
|
|
we can say SMNP is strongly-typed, because there are no any implicit type
|
|
conversions. You always have to provide correct type, even for
|
|
string concatenation which accepts only `string` values:
|
|
```
|
|
# Incorrect
|
|
"My number is: " + 14;
|
|
|
|
# Correct
|
|
"My number is: " + 14.toString();
|
|
```
|
|
|
|
### Comments
|
|
SMNP language allows you to make comments in the code.
|
|
It can be done with `#` character, like:
|
|
```
|
|
# This is is a comment
|
|
```
|
|
There is no syntax for multiline comment, but you can of course do something like this:
|
|
```
|
|
# This is
|
|
# a multiline
|
|
# comment
|
|
```
|
|
Note that because of hash-beginning comments you can
|
|
put a *shebang* at the very first of your code making it more
|
|
convenient to execute:
|
|
```
|
|
#!/usr/bin/smnp
|
|
println("Hello, world!");
|
|
|
|
# And now add executable flag (chmod +x)
|
|
# to the file and execute it like any other
|
|
# script/program from the shell
|
|
```
|
|
|
|
### Delimiter
|
|
SMNP language doesn't require you to delimit instructions, however it is still possible
|
|
and highly recommended, because it helps you to get rid of code ambiguity.
|
|
|
|
Example:
|
|
```
|
|
size = [1, 2, 3].size
|
|
(size - 1) as i ^ print(i)
|
|
```
|
|
Execution of this code is interrupted with error, because SMNP parser
|
|
tries to interpret `size` property as method `size(size - 1)`.
|
|
As long as lists don't have `size` method (but they have `size` property),
|
|
error will be raised and you will be able to fix problem. However ambiguity could be
|
|
a less obvious and you can stick with debugging code having no idea what is going wrong.
|
|
|
|
To remove ambiguity you can end each instruction with semicolon `;`:
|
|
```
|
|
size = [1, 2, 3].size;
|
|
(size - 1) as i ^ print(i); # 01
|
|
```
|
|
|
|
All code snippets of present document follows the convention of ending each
|
|
instruction with semicolon.
|
|
|
|
### Basic types
|
|
SMNP language introduces 9 data types and *void* which is a *quasi-type* because of it special meaning.
|
|
Most of the types is known from other popular programming languages, like Java etc.
|
|
|
|
#### integer
|
|
`integer` is numeric data type and is suitable to signed integers, like -6, 0, 1, 14, 23164 etc.
|
|
|
|
Example:
|
|
```
|
|
a = 1;
|
|
b = -15;
|
|
|
|
sum = a + b; # Produces also an integer
|
|
println(sum); # -14
|
|
```
|
|
|
|
###### Methods:
|
|
* `toString()` [string] - returns a string representation of integer: `14.toString() == "14"`
|
|
|
|
###### Unary operators:
|
|
* `-` - negates value
|
|
|
|
###### Binary operators:
|
|
* `+` - sum
|
|
* `-` - difference
|
|
* `*` - product
|
|
* `/` - quotient
|
|
* `**` - power
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
* `>` - greater than
|
|
* `>=` - greater or equals
|
|
* `<` - less than
|
|
* `<=` - less or equal
|
|
|
|
#### float
|
|
`float` is numeric data type suitable for non-integer values, like: -3.4, 0.01, 3.14, 12.0043 etc.
|
|
|
|
Example:
|
|
```
|
|
pi = 3.14;
|
|
r = 12.5;
|
|
|
|
area = pi*r**2;
|
|
println(area); # 490.625
|
|
```
|
|
|
|
###### Methods:
|
|
* `toString()` [string] - returns a string representation of float: `1.4.toString() == "1.4"`
|
|
|
|
###### Unary operators:
|
|
see `integer`
|
|
|
|
###### Binary operators:
|
|
see `integer`
|
|
|
|
#### string
|
|
`string` type is suitable to any sort of texts enabling you
|
|
to create string of any characters, including Unicode.
|
|
For now, strings can be delimited only with double quote (`"`).
|
|
|
|
Example:
|
|
```
|
|
text = "Hello, world!";
|
|
|
|
println(text); # Hello, world!
|
|
println(-text); # !dlrow ,olleH
|
|
```
|
|
|
|
###### Properties
|
|
* `length` [integer] - length of string: `"hello".length == 5`
|
|
|
|
###### Methods
|
|
* `join(list<string> l)` [string] - join all elements of list `l` with
|
|
given string as delimiter: `":".join(["1", "2", "3", "4"]) == "1:2:3:4"`
|
|
* `toString()` [string] - returns itself ;-)
|
|
|
|
###### Unary operators
|
|
* `-` - reverse string: `-"Hey!" == "!yeH"` (why not? ;-))
|
|
|
|
###### Binary operators
|
|
* `+` - concatenate strings: `"he" + "llo" == "hello"`
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
|
|
#### bool
|
|
`bool` data type allows you to perform basic Boolean logic
|
|
operations introducing two constant values: `true` and `false`.
|
|
|
|
Example:
|
|
```
|
|
_2b = false;
|
|
|
|
println(_2b or not _2b); # true
|
|
```
|
|
|
|
###### Methods:
|
|
* `toString()` [string] - returns a string representation of bool: `true.toString() == "true"`
|
|
|
|
###### Unary operators
|
|
* `not` - negate value: `not false == true`
|
|
|
|
###### Binary operators
|
|
* `and` - logical conjunction: `true and false == false`
|
|
* `or` - logical alternative: `true or false == true`
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
|
|
#### note
|
|
`note` is basic data type allowing you to compose music sheets.
|
|
It is a base music unit that represents a sound, i.e. its pitch and duration.
|
|
|
|
Note literal is written with the following syntax:
|
|
```
|
|
'@' PITCH [OCTAVE] [:DURATION [d]]
|
|
|
|
; where
|
|
|
|
PITCH := (c|d|e|f|g|a) [b|#] | h# | b
|
|
| (C|D|E|F|G|A) [b|#] | H# | B
|
|
OCTAVE := 1-9
|
|
DURATION := /non-negative integer/
|
|
```
|
|
Duration number means the denominator (`n`) of fraction `1/n`, i.e.:
|
|
* `1` stands for whole note
|
|
* `2` stands for half note
|
|
* `4` stands for quarter note
|
|
* `8` stands for eighth note
|
|
* `16` stands for sixteenth note
|
|
* and so on
|
|
|
|
You can also put a `d` character after duration number to add a ***d**ot* to note, like:
|
|
* `2d` stands for half note and quarter note (dotted half note)
|
|
* `4d` stands for quarter note and eighth note (dotted quarter note)
|
|
* `16d` stands for sixteenth note and thirty-second note (dotted sixteenth note)
|
|
* and so on
|
|
|
|
Default octave is `4` (1 Line) and default duration is `4` (quarter note).
|
|
Examples (note that pitch is case-insensitive):
|
|
* `@c` is quarter note with pitch *c'*
|
|
* `@F5:2` is half note with pitch *f''*
|
|
* `@g#3:4d` is dotted quarter note with pitch *g♯*
|
|
* `@Ab6:16` is sixteenth note with pitch *a♭'''*
|
|
* `@b2:1` is whole note with pitch *B* (*H♭*)
|
|
* `@C#1:32d` is dotted thirty-second note with pitch *C♯,*
|
|
|
|
**Note:** note literal syntax cannot include any whitespace character.
|
|
|
|
###### Properties
|
|
* `pitch` [string] - pitch of note: `@d#5:2d.pitch == "DIS"`
|
|
* `octave` [integer] - octave of note: `@d#5:2d.octave == 5`
|
|
* `duration` [integer] - duration of note: `@d#5:2d.duration == 2`
|
|
* `dot` [bool] - does note is dotted: `@d#5:2d.dot == true`
|
|
|
|
###### Methods
|
|
* `withOctave(integer octave)` [note] - factory method that copies
|
|
note with new `octave` value: `@c.withOctave(5) == @c5`
|
|
* `withDuration(integer duration)` [note] - factory method that copies
|
|
note with new `duration` value: `@c.withDuration(2) == @c:2`
|
|
* `withDot(bool dot)` [note] - factory method that copies
|
|
note with new `dot` value: `@c.withDot(true) == @c:4d`
|
|
* `toIntRepr()` [integer] - convert note's pitch and octave to unique integer value
|
|
* `transpose(integer semitones)` [note] - copy note and transpose
|
|
it with given number of semitones: `@c.transpose(2) == @d`
|
|
* `toString()` [string] - returns a string representation of note: `@g#.toString() == "G#"`
|
|
|
|
###### Binary operators
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
|
|
#### sound
|
|
`sound` is a wrapper for external music file, like `ogg`, `mp3` etc.
|
|
This is the only type that isn't possible to create syntactically.
|
|
Instead of that it can be instantiated with constructor-like function,
|
|
as at the example below:
|
|
```
|
|
myMusic = Sound("Music/Piano/Chopin/NocturneOp9No2.ogg");
|
|
myMusic.play();
|
|
```
|
|
|
|
###### Properties
|
|
* `file` [string] - a sound source file
|
|
* `fs` [integer] - sampling rate
|
|
|
|
###### Methods
|
|
* `play()` [void] - play a loaded sound file
|
|
* `toString()` [string] - returns a string representation of sound: `Sound("/../../music.ogg").toString == "/../../music.ogg"`
|
|
|
|
###### Binary operators
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
|
|
#### list
|
|
`list` is an ordered container able to store objects with different types.
|
|
List is created within square brackets (`[` and `]`) with items separated by comma (`,`).
|
|
Lists can be nested, which means they can contain another
|
|
lists that can contain yet another lists and so on.
|
|
|
|
Example:
|
|
```
|
|
myList = [1, "hello", @Ab:2d, true, 14.0, [ "even", "other", list!"], [], {}];
|
|
println(myList.size); # 9
|
|
println([14].size); # 1
|
|
println([].size); # 0
|
|
println(myList.contains(1)); # true
|
|
println(myList.contains(2)); # false
|
|
```
|
|
|
|
###### Properties
|
|
* `size` [integer] - a number of elements in list
|
|
|
|
###### Methods
|
|
* `get(integer index`) [?] - returns item of list with given index (**note:** indices start from **0**)
|
|
* `contains(element)` [bool] - test if list does contain given element
|
|
* `toString()` [string] - returns a string representation of list: `[1, 2].toString() == "[1, 2]`
|
|
|
|
###### Unary operators
|
|
* `-` - reverse lists (just because!): `-[1, 2, 3, 4] == [4, 3, 2, 1]`
|
|
|
|
###### Binary operators
|
|
* `+` - join lists: `[1, 2] + [3, 4] == [1, 2, 3, 4]`
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
|
|
|
|
#### map
|
|
`map` is unordered container able to store pairs `key-value` with different
|
|
types of both key and value.
|
|
Syntactically map is a set of pairs `key-value` separated with comma (`,`) and placed
|
|
between braces (`{` and `}`). Single `key-value` pair is created from two items
|
|
separated with arrow operator `->`. Similarly to lists, maps can also be nested.
|
|
Keys of course must be unique for single map object.
|
|
|
|
Even though value of pair can be arbitrary expression, key
|
|
should be explicit literal, like integer, note, bool value, type and string.
|
|
Lists and other maps can't be used as keys. Note that if string
|
|
key doesn't have any whitespaces, there is no need to use quotes around it.
|
|
|
|
Example:
|
|
```
|
|
myMap = {
|
|
1 -> "hello",
|
|
@c -> "world",
|
|
true -> false,
|
|
"hey" -> 14,
|
|
hey2 -> "key without quotes!",
|
|
empty -> {},
|
|
theList -> [1, 2, [], { inside -> ":-)" }]
|
|
};
|
|
|
|
println(myMap.size); # 4
|
|
println(myMap.get(@c)); # world
|
|
println(myMap.get("hey")); # 14
|
|
println(myMap.get("hey2")); # key without quotes!
|
|
```
|
|
|
|
###### Properties
|
|
* `size` [integer] - number of map entries (pairs)
|
|
* `keys` [list] - list of keys: `{ a -> 1, b -> 2 }.keys == ["a", "b"]`
|
|
* `values` [list] - list of values: `{ a -> 1, b -> 2}.values == [1, 2]`
|
|
|
|
###### Methods
|
|
* `containsKey(key)` [bool] - test if map does contain pair with given key
|
|
* `containsValue(value)` [bool] - test if map does contain pair with given value
|
|
* `contains(key, value)` [bool] - test if map does contain pair with given key **and** given value
|
|
* `toString()` [string] - returns a string representation of map: `{ a -> 1, b -> 2}.toString() == "{'a' -> '1', 'b' -> '2'}"`
|
|
|
|
###### Binary operators
|
|
* `+` - join maps: `{ a -> 1 } + { b -> 2 } == { a -> 1, b -> 2 }`
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
|
|
#### type
|
|
`type` represents all available data types including itself.
|
|
It is mostly used to get meta information about other values in code.
|
|
|
|
Example:
|
|
```
|
|
myNumber = 14;
|
|
println(typeOf(myNumber) == integer); # true
|
|
println(typeOf(myNumber) == bool); # false
|
|
println(typeOf(myNumber) == note); # false
|
|
println(typeOf(typeOf(myNumber)) == type); # true
|
|
println(typeOf(type)); # type
|
|
```
|
|
|
|
###### Methods
|
|
* `toString()` [string] - returns a string representation of type: `integer.toString() == "integer"`
|
|
|
|
###### Binary operators
|
|
* `==` - equals
|
|
* `!=` - not equals
|
|
|
|
#### void
|
|
`void` is special data type introduced to distinguish functions returning a value from
|
|
functions that don't return anything. It can't be used in any way and the only possibility
|
|
to do something with that is getting the type of it or getting a string representation of it.
|
|
|
|
Example:
|
|
```
|
|
void; # It actually does nothing
|
|
println(void.toString()); # void
|
|
println(typeOf(void)); # type
|
|
```
|
|
|
|
### Variables
|
|
SMNP language's variable mechanism allows you to store some data in memory which could be
|
|
used in the later stages of code. Even though SMNP language has a data types, declaring
|
|
new variables doesn't require you to explicitly put a type before declaration as in the case
|
|
of most popular languages, like Java etc. Hence it is not possible to declare variable
|
|
without initialization. You always have to initialize your variable when you are declaring it.
|
|
Initialization can be done with assignment operator (`=`). The right hand side should be
|
|
expression (value, function call or even other variable) but the left hand side can be only
|
|
variable identifier.
|
|
|
|
```
|
|
myVar; # It is not a declaration
|
|
myVar = 2; # It is a declaration. From now you are able to use variable myVar
|
|
3 = 2; # error!
|
|
var2 = foo(); # Correct
|
|
var2 = myVar; # Also correct
|
|
```
|
|
|
|
Variables are nothing but references to objects (values) and their don't have any type.
|
|
In other words you are able to assign value of different type to already initialized variable.
|
|
|
|
```
|
|
myVar = 2;
|
|
println(myVar); # 2
|
|
myVar = "Hello, world!";
|
|
println(myVar); # Hello, world!
|
|
```
|
|
|
|
Because assignment is an expression which returns a value being assigned it is possible
|
|
to perform multiple initialization.
|
|
|
|
```
|
|
a = b = c = 10; # It is like a = (b = (c = 10))
|
|
println(a == b and b == c); # true
|
|
```
|
|
|
|
SMNP language doesn't have any equivalent of Python's `del` instructions, so you aren't
|
|
able to delete already created variable. The only way is using scopes.
|
|
|
|
#### Scopes
|
|
Scopes are strongly related to blocks.
|
|
Block is a set of statements and expressions bounded on both sides with `{` and respectively `}`.
|
|
Even though it is not required and you can write whole code in one line, it is highly recommend
|
|
to use any kind of indentations for each block, including blocks nested inside.
|
|
```
|
|
println("I'm outside any block");
|
|
|
|
{
|
|
println("I'm in the first-level block");
|
|
{
|
|
println("I'm in second-level block");
|
|
}
|
|
|
|
println("Greetings from first-level block again");
|
|
}
|
|
|
|
```
|
|
|
|
In context of variable mechanism it is important to know that variables declared inside
|
|
block are available to each instructions following declaration **in the same block**
|
|
and for each nested block placed after variable declaration.
|
|
|
|
```
|
|
var1 = "top-level";
|
|
{
|
|
var2 = "first-level";
|
|
println(var1); # "top-level"
|
|
println(var3); # error!
|
|
{
|
|
var3 = "second-level";
|
|
println(var1); # "top-level"
|
|
println(var2); # "first-level"
|
|
println(var3); # "second-level"
|
|
}
|
|
println(var2); # "first-level"
|
|
println(var3); # error!
|
|
}
|
|
|
|
println(var2); # error!
|
|
println(var1); # "top-level"
|
|
```
|
|
|
|
#### Identifiers
|
|
It is also important to know what is identifier in context of SMNP language.
|
|
Identifier is a string that contains only letters (both lowercase and uppercase), numbers and `_` character.
|
|
Identifier must not start with number and must not be any of reserved words (keywords).
|
|
|
|
List of keywords:
|
|
* `and`
|
|
* `or`
|
|
* `not`
|
|
* `integer`
|
|
* `string`
|
|
* `float`
|
|
* `note`
|
|
* `bool`
|
|
* `type`
|
|
* `list`
|
|
* `map`
|
|
* `function`
|
|
* `return`
|
|
* `extend`
|
|
* `import`
|
|
* `throw`
|
|
* `from`
|
|
* `with`
|
|
* `if`
|
|
* `else`
|
|
* `as`
|
|
|
|
|
|
```
|
|
# Valid identifiers
|
|
i
|
|
var
|
|
myVar
|
|
my_var
|
|
var20
|
|
x_YZ
|
|
_vArIaBlE
|
|
_if
|
|
_return
|
|
returns
|
|
|
|
# Invalid identifiers
|
|
19i
|
|
foo[
|
|
bar@
|
|
return
|
|
!@#%$
|
|
if
|
|
as
|
|
```
|
|
|
|
#### Immutability
|
|
It's a good place to say that all values in SMNP code are **immutable**.
|
|
That means you are not able to e.g. change pitch of existing note, change arbitrary letter
|
|
of string, put object to list and so on.
|
|
|
|
You are able to produce note basing on given one with new pitch or join two or more lists
|
|
but these operations produces new objects and leave values unmodified.
|
|
|
|
```
|
|
a = [1, 2];
|
|
b = [3, 4];
|
|
c = a + b;
|
|
println(a == [1, 2]); # true
|
|
println(b == [3, 4]); # true
|
|
println(c == [1, 2, 3, 4]); # true
|
|
|
|
a = @c;
|
|
b = a.withDuration(2);
|
|
println(a == @c); # true
|
|
println(b == @c:2); # true
|
|
```
|
|
|
|
### Operators precedence
|
|
SMNLP language's operators have their unique priorities which determine operations' order
|
|
in case of ambiguity.
|
|
|
|
| Operator(s) | Precedence |
|
|
|----------------:|:----------:|
|
|
| `-` (unary) | 1 |
|
|
| `.` | 2 |
|
|
| `**` | 3 |
|
|
| `not` | 4 |
|
|
| `*` `/` | 5 |
|
|
| `+` `-` (binary)| 6 |
|
|
| `==` `!=` | |
|
|
| `<=` `>=` | 7 |
|
|
| `<` `>` | |
|
|
| `and` | 8 |
|
|
| `or` | 9 |
|
|
| `^` | 10 |
|
|
|
|
Remember, that in spite of operators precedence you can always force priority using parentheses:
|
|
```
|
|
a = -2+2;
|
|
b = -(2+2);
|
|
|
|
println(a); # 0
|
|
println(b); # -4
|
|
```
|
|
|
|
### Methods and functions
|
|
Function is a code snippet that takes some arguments and produces result.
|
|
Both arguments and result can be optionals.
|
|
Method in turn is a special function that is called in behalf of some
|
|
object.
|
|
Function (and method of course) can be invoked using its name and optional arguments
|
|
separated with commas (`,`) bounded on both sides with parentheses (`(` and `)`).
|
|
Even if no arguments are passed you have to put empty arguments list: `()`.
|
|
|
|
Some functions are available out-of-the-box as they are implemented
|
|
to SMNP tool. Set of such functions is called *standard library* (you can
|
|
read more about standard library in later section). You are able also
|
|
to create custom functions and methods (it'll be covered in next section).
|
|
|
|
As you can see on below examples implemented functions and methods mechanism
|
|
is really similar to other popular languages, like Java or Python.
|
|
|
|
Examples:
|
|
```
|
|
# Invoking function 'println' without any arguments
|
|
println();
|
|
|
|
# Invoking function 'println' with 1 argument
|
|
println("Hello, world!"); # Hello, world
|
|
|
|
# Invoking function 'println' with 2 argument
|
|
println(1, 2); # 12
|
|
|
|
# Invoking function 'println' with 2 argument
|
|
# Invoked function produces also result which
|
|
# is being assigned to variable 'newNote1'
|
|
newNote1 = transpose(2, @c);
|
|
|
|
# Method equivalent of function above
|
|
newNote2 = @c.transpose(2);
|
|
|
|
# Another example of method
|
|
firstElementOfList = [14, 3, 20, -4].get(0);
|
|
|
|
|
|
println(newNote1 == newNote2); # true
|
|
```
|
|
|
|
Note, that some functions or methods don't return anything.
|
|
In this case expecting any returned value can throw an exception.
|
|
```
|
|
# 'println' is example of function, that doesn't return anything
|
|
# in this case following instruction will raise an error
|
|
println(println()); # error
|
|
|
|
# other examples
|
|
x = println(); # error
|
|
|
|
println([1, 2, 3, println(), 5, 6]); # error
|
|
```
|
|
|
|
#### Function/method signature
|
|
Signature is feature of both functions and methods that makes them unique.
|
|
Signature consists of function/method name, function/method arguments
|
|
and applicable type in case of method.
|
|
It is a good place to say, that methods technically are just simple functions
|
|
with one additional argument placed at the beginning of arguments list.
|
|
Because of that we can say that signature consists only of name and arguments
|
|
list. This is also the reason of a little bit meaningless errors
|
|
that you can get when you are trying to call method with invalid arguments' types:
|
|
```
|
|
# correct
|
|
x = [1, 2, 3].get(0);
|
|
|
|
# invalid
|
|
x = [1, 2, 3].get(@c);
|
|
```
|
|
in this case you'll get following error (note first argument type
|
|
of expected signatures):
|
|
```
|
|
Invocation Error
|
|
(...)
|
|
|
|
Expected signature:
|
|
get(list, integer)
|
|
or
|
|
get(map, <integer, string, note, bool, type>)
|
|
|
|
Found:
|
|
get(list<integer>, note)
|
|
```
|
|
|
|
### Custom methods and functions
|
|
SMNP language introduces possibility to define custom functions and methods.
|
|
They can be invoked later in the same way as regular functions/methods
|
|
provided by SMNP standard library.
|
|
|
|
Functions and methods can be defined only at top level of the code, which means
|
|
they cannot be nested in any blocks.
|
|
|
|
#### Function definition
|
|
Functions can be defined with `function` keyword, like it is shown on following example:
|
|
```
|
|
function multipleBy2(number) {
|
|
return 2*number;
|
|
}
|
|
|
|
# Correct invocations
|
|
x = multipleBy2(2); # x = 4
|
|
x = multipleBy2(14); # x = 28
|
|
x = multipleBy2("hey"); # in spite of correctness it will cause an error
|
|
# because string argument doesn't support '*' operator
|
|
|
|
# Incorrect invocations
|
|
x = multipleBy2(1, 2); # it'll cause Invocation Error because of signatures mismatch
|
|
x = multipleBy2(); # as above
|
|
```
|
|
Thanks to `return` keyword you can produce an output value basing on e.g. passed arguments.
|
|
Example above takes one arbitrary argument, multiplies it by 2 and then returns a result.
|
|
|
|
##### Explicit argument types
|
|
Because arbitrary argument can be passed, the `multipleBy2` function can throw an error
|
|
in case of trying to multiple e.g. note or string, that don't support `*` operator.
|
|
In this case you can put a constraint to the argument which accepts only chosen types:
|
|
```
|
|
function multipleBy2(integer number) {
|
|
return 2*number;
|
|
}
|
|
|
|
# Correct invocations
|
|
x = multipleBy2(2); # x = 4
|
|
x = multipleBy2(14); # x = 28
|
|
|
|
# Incorrect invocations
|
|
x = multipleBy2(1, 2); # it'll cause Invocation Error because of signatures mismatch
|
|
x = multipleBy2(); # as above
|
|
x = multipleBy2("hey"); # as above
|
|
```
|
|
Function `multipleBy2` will work only with integer argument now. Any attempt to invoke it
|
|
with no-integer values will cause Invocation Error related to mismatched signatures.
|
|
|
|
Of course you are still able to create functions without any arguments or mix their types:
|
|
```
|
|
function noArgs() {
|
|
println("Hello, I don't accept any arguments.");
|
|
println("Also see that I don't return anything!");
|
|
}
|
|
|
|
function mixedArguments(integer a1, note a2, a3) {
|
|
println("See, " + a1.toString() + " is an integer!");
|
|
println("And " + a2.toString() + " is a note.");
|
|
println("Type of third argument is " + typeOf(a3).toString());
|
|
}
|
|
|
|
# Correct invocations
|
|
mixedArgument(1, @c, "hey");
|
|
mixedArguments(14, @Gb:4d, true);
|
|
|
|
# Incorrect invocations
|
|
mixedArgument(@c, @c, @c);
|
|
mixedArgument(1, 1, 1);
|
|
|
|
```
|
|
##### Functions returning nothing
|
|
Notice also that functions presented in previous example don'tactually return anything.
|
|
Technically they **do** return a `void` type and it is transparent to SMNP user. You should remember, that
|
|
you can expect value produced by function only and only if `return` statement
|
|
is declared in invoked function and the statement **has been called**. Otherwise
|
|
function being invoked will return `void` type which cannot act as expression.
|
|
|
|
##### Ambiguous arguments
|
|
SMNP language allows you also to declare more than one argument that functions can accept.
|
|
Accepted types are separated with commas (`,`) and are bounded on both sides with `<` and `>` characters.
|
|
|
|
Example:
|
|
```
|
|
function foo(<string, bool, integer, float> x, sound y, z) {
|
|
# 'x' can be either string, bool, integer or float
|
|
# whereas 'y' can be only a sound
|
|
# and 'z' can be of any available type
|
|
}
|
|
|
|
# Correct invocations
|
|
foo("hey", Sound("..."), [1, 2, true, [@c], { a -> 1, b -> 2 }]);
|
|
foo(true, Sound("..."), integer);
|
|
foo(14, Sound("..."), @c#:16d);
|
|
foo(1.4, Sound("..."), 3.14);
|
|
|
|
# Incorrect invocations
|
|
foo(integer, Sound("..."), 10);
|
|
foo("hey", 20, 10);
|
|
foo([1, 2, 3], Sound("..."), 10);
|
|
```
|
|
|
|
##### Specified lists
|
|
SMNP language allows you to specify what objects can be contained in lists.
|
|
It can be done with construction similar to previous one.
|
|
Accepted types are separated with commas (`,`), bounded on both sides with `<` and `>` characters and placed
|
|
next to `list` keyword:
|
|
```
|
|
function foo(list<integer> x) {
|
|
# 'x' can be only list of integers
|
|
}
|
|
|
|
# Correct invocations
|
|
foo([1, -2, 3]);
|
|
foo([0]);
|
|
foo([]);
|
|
|
|
# Incorrect invocations
|
|
foo(1);
|
|
foo(2, 3);
|
|
foo([ 1, 2, @c ]);
|
|
```
|
|
|
|
You are still able to use multiple type as constraints:
|
|
```
|
|
function foo(list<integer, note> x) {
|
|
# 'x' can be only list of integers and notes, nothing else
|
|
}
|
|
|
|
# Correct invocations
|
|
foo([1, @c, 4]);
|
|
foo([]);
|
|
foo([0]);
|
|
foo([@d#]);
|
|
|
|
# Incorrect invocations
|
|
foo([1, @c, true]);
|
|
foo(@c, 1);
|
|
foo({ @c -> 1 });
|
|
```
|
|
|
|
List specifier can be empty or even be absent. In this case list can contain
|
|
any available types:
|
|
```
|
|
function foo(list<> x) {
|
|
# 'x' can be only a list containing arbitrary objects
|
|
}
|
|
|
|
# the same function can be implemented as
|
|
|
|
function foo(list x) {
|
|
# ...
|
|
}
|
|
|
|
# Correct invocations
|
|
foo([1, @c, true]);
|
|
foo([]);
|
|
foo([integer, float, @g#:32d, false, [[[]]], { a -> 1, @d -> 2, true -> {} }]);
|
|
|
|
# Incorrect invocations
|
|
foo({});
|
|
foo([1, @c, true], 1);
|
|
foo(true);
|
|
```
|
|
|
|
Specifiers can be nested - you are able to create e.g. list of lists of lists of integers etc.
|
|
```
|
|
function foo(list<list<list<integer>>> x) {
|
|
}
|
|
|
|
# Correct invocations
|
|
foo([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]);
|
|
|
|
# Incorrect invocations
|
|
foo([[[1, 2], [3, 4]], [[5, 6], [7, 8]], 9]);
|
|
```
|
|
|
|
Of course ambiguous arguments can include specified lists:
|
|
```
|
|
function foo(<integer, note, list<integer, note> x) {
|
|
# 'x' can be integer, note or list containing only integers and notes
|
|
}
|
|
|
|
# Correct invocations
|
|
foo(@c);
|
|
foo(1);
|
|
foo([]);
|
|
foo([2, @G]);
|
|
foo([@h]);
|
|
|
|
# Incorrect invocations
|
|
foo(1.0);
|
|
foo([true]);
|
|
```
|
|
|
|
##### Specified maps
|
|
Maps can be also specified. All rules related to specified lists are also applicable for maps.
|
|
The only difference is map supports **2** specifiers: first one for keys and second one for values.
|
|
|
|
Example:
|
|
```
|
|
function foo(map<string><note> x) {
|
|
# 'x' can be only a map with strings as keys and notes as values
|
|
}
|
|
|
|
function bar(map<string><> x) {
|
|
# 'x' can be only a map with strings as keys and arbitrary values
|
|
}
|
|
|
|
function xyz(map<string, bool><integer, note> x) {
|
|
# 'x' can be only a map with strings and booleans as keys and integers and notes as values
|
|
}
|
|
|
|
function abc(map<><integer, bool> x) {
|
|
# 'x' can be only a map with arbitrary keys and integers with booleans as values
|
|
}
|
|
|
|
# Correct invocations
|
|
foo({ c -> @c, d -> @d });
|
|
bar({ a -> @c, b -> 1, c -> true, d -> map, e -> { x -> [] });
|
|
xyz({ a -> 1, true -> @c, false -> 2, b -> @d });
|
|
abc({ a -> true, 1 -> false, @c -> 10, true -> 14 });
|
|
|
|
# Incorrect invocations
|
|
foo({ c -> @c, @d -> @d, @c -> "hey" });
|
|
bar({ a -> @c, @d -> @c });
|
|
xyz({ integer -> @c, 2 -> 3, float -> bool });
|
|
abc({ a -> true, false -> @c });
|
|
```
|
|
|
|
##### Optional arguments
|
|
SMNP language allows you also to use default arguments.
|
|
Optional arguments are special kind of arguments that can have default value and are
|
|
totally optional to pass during invocation. Syntax of optional arguments is similar
|
|
to variable assignment syntax.
|
|
|
|
Example:
|
|
```
|
|
function foo(x = 10) {
|
|
# 'x' can be of any available type.
|
|
# You can override default value but you don't have to.
|
|
# In this case default value will be used.
|
|
|
|
return x;
|
|
}
|
|
|
|
# Correct invocations
|
|
y = foo(); # y = 10
|
|
y = foo(10); # y = 10
|
|
y = foo(true); # y = true
|
|
```
|
|
|
|
All kinds of arguments mentioned so far can be optional:
|
|
```
|
|
function foo(x = 1, integer y = 14, <note, list<list<integer, note>> z = [[1, @c], [@d]]) {
|
|
}
|
|
|
|
# Correct invocations
|
|
foo();
|
|
foo(2);
|
|
foo(10, 11);
|
|
foo(-2, 33, @c);
|
|
foo(-2, 33, [[1, @d, @f#], [4, 3], [@c, @d, @e]);
|
|
foo(0, 0, []);
|
|
foo(0, 0, [[]]);
|
|
|
|
# Incorrect invocations
|
|
foo(true);
|
|
foo(1, 0.5);
|
|
foo(10, 2, 13);
|
|
foo(0, 0, [], 3);
|
|
```
|
|
|
|
As you can see, you can have as many optional arguments as you want.
|
|
Just remember, that after first declared optional argument you can't use regular
|
|
arguments in the same signature anymore.
|
|
```
|
|
# Correct signatures
|
|
function foo(a, b, c = 0) {}
|
|
function bar(a, b = "hello", c = true) {}
|
|
function xyz(a = integer, b = [12.5], c = @c) {}
|
|
|
|
# Incorrect signatures (will throw an error)
|
|
function abc(a = 0, b) {}
|
|
function def(a, b, c = 0, d = true, e, f = @G#) {}
|
|
```
|
|
In other words, optional arguments should be declared at the tail of function signature.
|
|
|
|
##### Varargs
|
|
SMNP language also supports functions' signatures with arbitrary length.
|
|
This is exactly how `println` or `print` functions work.
|
|
You can pass as many arguments as you want and they still are able to handle it.
|
|
SMNP language provides a special operator `...` that enables you to have function
|
|
with variable number of arguments.
|
|
|
|
Remember that:
|
|
* you can have only one vararg at the signature
|
|
* vararg should be placed at the very end of signature
|
|
* you can't mix varargs with optional arguments in one signature.
|
|
|
|
After invocation, all matched arguments are collected into one list which is passed
|
|
as vararg.
|
|
|
|
Example:
|
|
```
|
|
function foo(a, b, c...) {
|
|
# 'c' is a list of arguments passed after 'a' and 'b'
|
|
|
|
return c;
|
|
}
|
|
|
|
# Correct invocations:
|
|
x = foo(0, 1); # x = []
|
|
x = foo(1, 2, 3, 4); # x = [3, 4]
|
|
x = foo(true, false, @c, [3.14, 5, integer], float); # x = [@c, [3.14, 5, integer], float]
|
|
|
|
# Incorrect invocations:
|
|
foo();
|
|
foo(true);
|
|
```
|
|
|
|
Same as optional arguments, vararg can work with any previously mentioned kinds
|
|
of arguments (except optional arguments of course).
|
|
```
|
|
function foo(a, note b, map<string><list<integer, note>> c...) {
|
|
# after two arguments you can pass any number of
|
|
# maps with strings as keys and list of integers and notes as values
|
|
}
|
|
|
|
# Correct invocations:
|
|
foo(1, @c, { a -> [@d], b -> [@c, @g] }, { a -> [], b -> [@e] });
|
|
foo(1, @c, {}, {}, {}, {}, {}, {}, {}, {});
|
|
|
|
# Incorrect invocations:
|
|
foo();
|
|
foo(1, @c, { a -> [@d], b -> [@c, @g] }, { a -> [], b -> @e });
|
|
```
|
|
|
|
#### Method definition
|
|
All rules related to defining custom functions are applicable to methods either.
|
|
The difference is method can be invoked in a context of some object.
|
|
That's why methods can be defined only as a part of some type.
|
|
|
|
##### `extend` statement
|
|
SMNP language introduces `extend` statement which allows you to add custom
|
|
methods to existing types. All you need is to precise desired type and define function
|
|
which will be working as new method.
|
|
Following listing presents a syntax of `extend` statement:
|
|
```
|
|
extend integer as i with function multipleBy(integer x) {
|
|
return i*x;
|
|
}
|
|
|
|
# From now you can use new method as follows:
|
|
x = 10.multipleBy(2); # x = 20
|
|
y = x.multipleBy(4); # y = 80
|
|
```
|
|
|
|
As mentioned before, all rules related to functions are applicable here, so there
|
|
is no need to cover `function multipleBy(...) {...}` statement again.
|
|
|
|
Code from listing above defines new method of `integer` type.
|
|
Note, that thanks to `integer as i` instruction, object that holds the context of method
|
|
is available through variable with name `i`. This works similar to arguments
|
|
passed to function and actually there are no differences between
|
|
using them in function's body.
|
|
|
|
Even though type actually works as additional argument passed to function, there
|
|
is a slight difference between them. As mentioned before, you can use such features
|
|
in function signature as optional arguments, ambiguous arguments, varargs etc.
|
|
For obvious reasons these are not available for declaring type.
|
|
Type being extended must be declared only as a simple data type or map/list with optional
|
|
specifier. Also you have always provide an identifier by which you can refer to the type (`as` part).
|
|
|
|
Examples:
|
|
```
|
|
# Correct
|
|
extend integer as x with function a() {}
|
|
extend list as x with function b() {}
|
|
extend list<> as x with function c() {}
|
|
extend list<list<note, integer>> as x with function d() {}
|
|
extend map<string><note> as x with function e() {}
|
|
extend map<><> as x with function f() {}
|
|
extend map<><list<map<><note, string, list<integer>>>> as x with function g() {}
|
|
|
|
# Incorrect
|
|
extend <string, integer> as x with function h() {}
|
|
extend <integer> as x with function i() {}
|
|
extend <> as x with function j() {}
|
|
extend integer with function k() {}
|
|
```
|
|
|
|
Because extending statement supports list/map specifiers, you can define
|
|
methods that are applicable only for list/map with specified content:
|
|
```
|
|
# Extends all lists, no matter of content
|
|
extend list as l with function foo() {
|
|
println("foo()");
|
|
}
|
|
|
|
# Extends only list<integer>
|
|
extend list<integer> as l with function bar() {
|
|
println("bar()");
|
|
}
|
|
|
|
l1 = [1, 2, 3, 4];
|
|
l2 = [1, 2, @c, 4];
|
|
l3 = ["a", "b", "c", "d"];
|
|
|
|
l1.foo(); # foo()
|
|
l2.foo(); # foo()
|
|
l3.foo(); # foo()
|
|
|
|
l1.bar(); # bar()
|
|
l2.bar(); # error!
|
|
l3.bar(); # error!
|
|
```
|
|
|
|
Because SMNP doesn't allow you to extend multiple types in one instruction, if you want
|
|
extend for example `list<integer>` and `list<note>` (but not `list<integer, note>`) you have
|
|
to do it separately:
|
|
```
|
|
# This won't work at all
|
|
extend <list<integer>, list<note>> as l with function foo() {
|
|
# ...
|
|
}
|
|
|
|
# Instead of that you can do:
|
|
extend list<integer> as l with function foo() {
|
|
# ...
|
|
}
|
|
|
|
extend list<note> as l with function foo() {
|
|
# ...
|
|
}
|
|
```
|
|
Note that there is no signature collision problem, because technically first argument
|
|
is different in both methods.
|
|
|
|
##### `extend` block
|
|
In case of extending type with more than one function you can use block of methods.
|
|
|
|
Example:
|
|
```
|
|
extend integer {
|
|
function multipleBy2() {
|
|
return 2*i;
|
|
}
|
|
|
|
function multipleBy4() {
|
|
return 4*i;
|
|
}
|
|
}
|
|
|
|
# Construction above is equivalent of following code:
|
|
|
|
extend integer as i with function multipleBy2() {
|
|
return 2*i;
|
|
}
|
|
|
|
extend integer as i with function multipleBy4() {
|
|
return 4*i;
|
|
}
|
|
```
|
|
|
|
#### Overloading function/methods
|
|
Unfortunately functions/methods overloading
|
|
is not supported in custom functions/methods so far.
|
|
However you can notice that some functions and methods coming
|
|
from SMNP standard library core are overloaded, like `get()` method,
|
|
some constructor-like methods, `wait()` function and so on.
|
|
That's because these functions are implemented right in Python
|
|
and there still lacks function/method overloading mechanism directly in SMNP language.
|
|
|
|
However you can still use ambiguous arguments and just check in function's body
|
|
their types by hand using `typeOf()` function:
|
|
```
|
|
function myFunction(<integer, note> arg) {
|
|
if (typeOf(arg) == integer) {
|
|
println("You have passed integer");
|
|
} else {
|
|
println("You have passed note!");
|
|
}
|
|
}
|
|
|
|
myFunction(1); # You have passed integer
|
|
myFunction(@c); # You have passed note
|
|
myFunction("hey"); # error!
|
|
```
|
|
|
|
### Imports
|
|
SMNP language allows you to split code into multiple files and then join them together
|
|
using `import` statement.
|
|
The statement loads file, executes its code and appends newly created context into
|
|
main file. It means that all imperative code (code that produces immediately result, like function calls)
|
|
will be executed just once, whereas declarative part (code that appends something to context, like
|
|
variable assignments or function definitions) will be appended to main context, so that
|
|
you will be able to take advantage of defined functions and variables.
|
|
|
|
Example:
|
|
```
|
|
#################### file_a.mus ####################
|
|
function foo() {
|
|
println("Hello, world!");
|
|
}
|
|
|
|
var = 14;
|
|
|
|
println("I'm a file_a.mus!");
|
|
```
|
|
```
|
|
##################### main.mus #####################
|
|
import "file_a.mus"; # I'am a file_a.mus!
|
|
|
|
foo(); # Hello, world!
|
|
println(var); # 14
|
|
```
|
|
|
|
It is important to know, that `import` is just simple statement that loads external file and executes its code.
|
|
Thus there is no any protection from some known dependency problems, like circular dependencies
|
|
or repeatedly imported files.
|
|
|
|
### `if` and `if-else` statement
|
|
SMNP language has support for good old condition statement
|
|
and syntax is inspired by Java language.
|
|
|
|
#### `if` statement
|
|
The simplest form consists only of `if` keyword followed
|
|
by condition bounded on both sides with
|
|
parentheses (`(` and `)`) and statement
|
|
(or block of code):
|
|
```
|
|
if (2 > 3) println("It gonna never be displayed!");
|
|
|
|
# or (using block of code)
|
|
|
|
if (2 > 3) {
|
|
println("It gonna never be displayed!");
|
|
}
|
|
```
|
|
|
|
Just like in Java condition **must be** of `bool` type.
|
|
```
|
|
# Correct examples
|
|
if (true) println();
|
|
if (false) println();
|
|
if (not false) println();
|
|
if (0 == 0) println();
|
|
if ("hello".length > 0) println();
|
|
if (true and not true or not false and true) println();
|
|
if (true and (not true or not false) and true) println();
|
|
|
|
# Incorrect examples
|
|
if () println();
|
|
if (0) println();
|
|
if (1) println();
|
|
if ("hello") println();
|
|
if (true.toString()) println();
|
|
```
|
|
|
|
#### `if-else` statement
|
|
You can use additional `else` clause which is always executed
|
|
when condition is resolved to `false`.
|
|
|
|
Example:
|
|
```
|
|
if (2 > 3) println("It gonna never be displayed!");
|
|
else println("but this always will be displayed");
|
|
|
|
# or you can use blocks of code to increase readability
|
|
|
|
if (2 > 3) {
|
|
println("It gonna never be displayed!");
|
|
} else {
|
|
println("but this always will be displayed");
|
|
}
|
|
```
|
|
|
|
Remember that only one condition statement branch (`if` or `else`)
|
|
can be executed in single statement. There is no possibility
|
|
to execute both clauses:
|
|
```
|
|
x = 1;
|
|
|
|
if (x > 0) {
|
|
println(true);
|
|
} else {
|
|
println(false);
|
|
}
|
|
|
|
if (x < 0) {
|
|
println(false);
|
|
} else {
|
|
println(true);
|
|
}
|
|
```
|
|
Above example will print twice `true`. First statement's condition is met,
|
|
so `if` clause did execute, but second statement's condition is resolved
|
|
to false so `else` clause did execute.
|
|
|
|
#### `if-else-if-else-if-...` statement
|
|
Above constructions are sufficient
|
|
to create `if-else-if-...` pseudo-construction.
|
|
Thanks to it you are able to put additional execution branches
|
|
to existing condition statement.
|
|
*Pseudo* in this case means that there is no special parsing rules
|
|
nor evaluators related to this construction. It is just a combination
|
|
of `if` and `if-else` statements presented above.
|
|
|
|
Example:
|
|
```
|
|
x = 3;
|
|
if (x == 0) {
|
|
println("x is zero");
|
|
} else if (x == 1) {
|
|
println("x is one");
|
|
} else if (x == 2) {
|
|
println("x is two");
|
|
} else if (x == 3) {
|
|
println("x is three");
|
|
} else {
|
|
println("x is neither zero, one, two nor three");
|
|
}
|
|
|
|
# technically this construction is:
|
|
|
|
if (x == 0) {
|
|
println("x is zero");
|
|
} else {
|
|
if (x == 1) {
|
|
println("x is one");
|
|
} else {
|
|
if (x == 2) {
|
|
println("x is two");
|
|
} else {
|
|
if (x == 3) {
|
|
println("x is three");
|
|
} else {
|
|
println("x is neither zero, one, two nor three");
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
Thanks to its tree-like construction control flow falls through all conditions.
|
|
A branch first matched branch is executed
|
|
and following conditions are not checked anymore:
|
|
```
|
|
x = 0
|
|
if (x == 1) {
|
|
println(); # Condition is resolved to false
|
|
} else if (x == 0) {
|
|
println(); # Condition is met
|
|
} else if (x == 0) {
|
|
println(); # Condition is also met,
|
|
} # but it hasn't been even checked because above
|
|
# branch has been already matched and executed
|
|
```
|
|
|
|
### Loop statement / expression
|
|
SMNP language provides a loop statement which also acts as expression.
|
|
The statement has been totally designed from scratch and is not similar
|
|
to any known loop statements from other languages.
|
|
Loop allows you to repeat some instructions with counter set programmatically.
|
|
All loops are created through loop operator (`^`).
|
|
|
|
#### Simple loop
|
|
The simplest loop consists only of counter, loop operator and instruction or block
|
|
of instructions.
|
|
|
|
Example:
|
|
```
|
|
# the simplest loop
|
|
3 ^ print("Money "); # Money Money Money
|
|
|
|
# the same using block of code
|
|
|
|
3 ^ {
|
|
print("Money ");
|
|
}
|
|
|
|
# Output: Money Money Money
|
|
```
|
|
|
|
Of course you can use any expression as counter, like variable or function call:
|
|
```
|
|
function provideCounter(integer x) {
|
|
return x * 2;
|
|
}
|
|
|
|
provideCounter(5) ^ print("a"); # aaaaaaaaaa
|
|
```
|
|
|
|
You can define a counter variable whose value is increased with each iteration
|
|
using `as` clause (note, that values start from 0):
|
|
```
|
|
3 as i ^ print(i, " "); # 0 1 2
|
|
```
|
|
|
|
#### *while* loop
|
|
You can create a loop which is controlled by logic condition.
|
|
It can be done just putting a `bool` value as a counter.
|
|
|
|
Example:
|
|
```
|
|
end = false;
|
|
i = 0;
|
|
|
|
not end ^ {
|
|
if (i == 3) {
|
|
end = true;
|
|
}
|
|
|
|
i = i + 1;
|
|
}
|
|
|
|
println(end); # true
|
|
println(i); # 4
|
|
```
|
|
|
|
Note that condition-controlled loop doesn't support `as` clause.
|
|
|
|
#### *For-each* loop
|
|
This kind of loop works both with lists and maps.
|
|
##### List
|
|
You can put a list as a counter. In this case statement will be executed
|
|
for each element of list. You can obtain an access to element through `as` clause
|
|
like in previous examples.
|
|
|
|
Example:
|
|
```
|
|
x = [@c, @d, @e];
|
|
x ^ print("Money "); # Money Money Money
|
|
|
|
x as n ^ print(n, " "); # C D E
|
|
```
|
|
|
|
You can put additional parameter into `as` clause. In this case the first parameter
|
|
will be just iterator that is increased after each loop iteration. The second parameter
|
|
will be value of passed list. If you are using more than one parameter in `as` clause,
|
|
you have to enclose them between parentheses.
|
|
|
|
Example:
|
|
```
|
|
[@c, @d, @e] as (i, n) ^ println(i, ". ", n);
|
|
|
|
# Output:
|
|
# 0. C
|
|
# 1. D
|
|
# 2. E
|
|
```
|
|
|
|
##### Map
|
|
Map is also supported to act as an counter of loop.
|
|
In this case statement will be executed for each value of passed map.
|
|
|
|
Example:
|
|
```
|
|
x = {
|
|
a -> @c,
|
|
b -> @d,
|
|
c -> @e
|
|
};
|
|
|
|
x ^ print("Money "); # Money Money Money
|
|
```
|
|
|
|
You are also able to access keys and values of iterated map using parameters in `as` clause.
|
|
If you pass only one parameter, it will contain a value of map.
|
|
If you pass two parameters, the first one will contain a key and the second one respectively a value.
|
|
If you pass three parameters, the first one will be an iterator increased by one with all
|
|
iteration, the second one will be key and the third one will be value.
|
|
|
|
Example:
|
|
```
|
|
myMap = {
|
|
first -> true,
|
|
second -> [@c, @d, @e],
|
|
third -> 14
|
|
};
|
|
|
|
myMap as value ^ println(value);
|
|
# Output:
|
|
# true
|
|
# [C, D, E]
|
|
# 14
|
|
|
|
myMap as (key, value) ^ println(key, ": ", value);
|
|
# Output:
|
|
# first: true,
|
|
# second: [C, D, E]
|
|
# third: 14
|
|
|
|
myMap as (i, key, value) ^ println(i, ". ", key, ": ", value);
|
|
# Output:
|
|
# 0. first: true,
|
|
# 1. second: [C, D, E]
|
|
# 2. third: 14
|
|
```
|
|
|
|
#### Filters
|
|
Loops in SMNP language also support filtering.
|
|
The filtering can be done with `%` clause, which contains a condition
|
|
that must be met to execute iteration. `%` clause is placed at the very last
|
|
of loop statement.
|
|
|
|
Example:
|
|
```
|
|
10 as i ^ println(i) % mod(i, 2) == 0;
|
|
# Output:
|
|
# 0
|
|
# 2
|
|
# 4
|
|
# 6
|
|
# 8
|
|
```
|
|
Filtering can be useful with simple counting loops like above, but it is really powerful with
|
|
*for-each* loops. You can pass further only elements of list/map that met
|
|
defined conditions.
|
|
It is even more useful with special feature of loops that is covered in next section.
|
|
|
|
#### Loop expression
|
|
Really strength of designed loops relies on the fact, that all kinds of them actually can work as *expressions*.
|
|
It means that you can use any kind of loop as e.g. function argument, because they can produce a value.
|
|
They work similar to Python's list comprehension and actually produce a new list.
|
|
One important condition you have to met in order to use loop as expression is to put
|
|
expression as a loop's statement. Because of that in loop expression you can't use
|
|
block of code. The statement must be a single instruction.
|
|
|
|
Example:
|
|
```
|
|
x = [1, 2, 3, 4];
|
|
|
|
# 'y' holds numbers multipied by 2
|
|
y = x as i ^ i * 2; # y = [2, 4, 6, 8]
|
|
|
|
# 'z' holds squares of even numbers
|
|
z = x as i ^ i ** 2 % mod(i, 2) == 0; # y = [4.0, 16.0]
|
|
```
|
|
|
|
Note, that loop statement is right associative.
|
|
That means nested loop statements are being accumulated in right hand branch.
|
|
Take look at example:
|
|
```
|
|
2 ^ 4 ^ 6 ^ print();
|
|
# is exactly the same as
|
|
2 ^ (4 ^ (6 ^ print()));
|
|
```
|
|
is parsed to following abstract syntax tree:
|
|
```
|
|
^
|
|
/ \
|
|
2 ^
|
|
/ \
|
|
4 ^
|
|
/ \
|
|
6 print("a")
|
|
```
|
|
It could be a flaw if you would like to create a mapping chain using loop statements
|
|
(like streams in Java 8 or LINQ in .NET), because it requires from operator
|
|
to be left associative, so that first instruction would produce value and pass it further.
|
|
It can be of course achieved with parentheses:
|
|
```
|
|
data = ["lorem", "ipsum", "dolor", "sit", "amet"];
|
|
output = (((((data as d
|
|
^ d
|
|
% d.length > 3) as d
|
|
^ d.length) as d
|
|
^ d * 2) as d
|
|
^ d + 1) as d
|
|
^ d
|
|
% d == 11);
|
|
|
|
println(output); # [11, 11, 11]
|
|
```
|
|
As you can see it actually works but is not convenient and readable.
|
|
|
|
### Throwing errors
|
|
Even though SMNP language doesn't have any sophisticated error handling mechanism,
|
|
you are able to raise errors using `throw` statement.
|
|
The `throw` construction is inspired by Java language, however instead of
|
|
throwing exceptions SMNP language allows you only to throw string values.
|
|
When control flow meet `throw` statement, program execution is immediately interrupted
|
|
and Execution Error is raised with message passed to `throw` statement.
|
|
|
|
Example:
|
|
```
|
|
function divide(integer a, integer b) {
|
|
if (b == 0) {
|
|
throw "You are trying to divide by 0!";
|
|
}
|
|
|
|
return a / b;
|
|
}
|
|
```
|
|
If you try to invoke e.g. `divide(2, 0)` the Execution Error will be thrown
|
|
with message, that you are trying to divide by 0.
|
|
|
|
SMNP language does not support any equivalent of `try-catch` statements known from
|
|
other languages, so you are actually unable to implement more advanced multi-layer
|
|
error handling system, because the language is not aimed on building complex systems
|
|
and there is simply no need to implement sophisticated error handling system
|
|
in simple music .
|
|
|
|
|
|
### Standard library
|
|
SMNP is provided with builtin standard library which consists of
|
|
some fundamental functions and methods that increase language's functionality.
|
|
SMNP don't require you to do anything in order to use anything from its standard library.
|
|
Just put function/method name with proper arguments and that's it.
|
|
Technically SMNP's standard library (*stdlib*) consists of 2 layers: native library and language library.
|
|
|
|
#### Native library
|
|
Native library contains functions and methods that
|
|
are implemented **directly in Python**.
|
|
Generally this part of *stdlib* introduces fundamental functions
|
|
and methods that:
|
|
* enables communication between
|
|
SMNP and operating system, like:
|
|
`print`, `read`, `exit` etc.
|
|
* are related to audio module, like:
|
|
`wave`, `synth`, `wait`, `play` etc.
|
|
* are strictly bound to runtime environment, like:
|
|
`type`, `debug` etc.
|
|
* make use of Python libraries, like:
|
|
`rand`, `fft`, `plot` etc.
|
|
* are constructor-like functions, like:
|
|
`Integer`, `Map`, `Note` etc.
|
|
|
|
Native functions and methods are located in `smnp/module` module.
|
|
|
|
#### Language library
|
|
Language library contains functions and methods that are
|
|
implemented **in SMNP language itself**.
|
|
Some of SMNP assumptions points to move as many code as possible
|
|
from native library to language library, even at cost of efficiency.
|
|
This library contains such functions and methods as: `flat`, `transpose`,
|
|
`mod`, `tuplet`, `sample`, `random`, `join` and so on.
|
|
|
|
Language library is a single file named `main.mus` and located
|
|
in `smnp/library/code` module.
|
|
|
|
#### *stdlib* documentation
|
|
Documentation of both native and language library is included in
|
|
the `STDLIB.md` file of present repository.
|
|
|
|
## SMNP language interpreter
|
|
SMNP language interpreter consists of three parts composed
|
|
to pipeline:
|
|
* *tokenizer* (or *lexer*)
|
|
* *parser*
|
|
* *evaluator*
|
|
|
|
All of these components participate in processing and executing
|
|
passed code, producing output that can be consumed by next component.
|
|
|
|
### Tokenizer
|
|
Tokenizer is the first component in code processing pipeline.
|
|
Input code is directly passed to tokenizer which splits
|
|
it to several pieces called *tokens*. Each token contains of
|
|
main properties, such as *value* and related *token type* (or *tag),
|
|
for example:
|
|
* literal: `"Hello, world!"` is token with value `Hello, world!` and
|
|
token type `STRING`
|
|
* literal: `abc123` is token with value `abc123` and token type `IDENTIFIER
|
|
* etc.
|
|
Apart from mentioned data, each token also includes some metadata, like
|
|
location of value in code (both line and column).
|
|
|
|
You can check what tokens are produced for arbitrary input code
|
|
using `--tokens` flag, for example:
|
|
```
|
|
$ smnp --tokens --dry-run -c "[1, 2, 3] as i ^ println(\"Current: \" + i.toString());"
|
|
[Current(0): {OPEN_SQUARE, '[', (0, 0)}
|
|
{OPEN_SQUARE, '[', (0, 0)}, {INTEGER, '1', (0, 1)}, {COMMA, ',', (0, 2)}, {INTEGER, '2', (0, 4)}, {COMMA, ',', (0, 5)}, {INTEGER, '3', (0, 7)}, {CLOSE_SQUARE, ']', (0, 8)}, {AS, 'as', (0, 10)}, {IDENTIFIER, 'i', (0, 13)}, {CARET, '^', (0, 15)}, {IDENTIFIER, 'println', (0, 17)}, {OPEN_PAREN, '(', (0, 24)}, {STRING, 'Current: ', (0, 25)}, {PLUS, '+', (0, 37)}, {IDENTIFIER, 'i', (0, 39)}, {DOT, '.', (0, 40)}, {IDENTIFIER, 'toString', (0, 41)}, {OPEN_PAREN, '(', (0, 49)}, {CLOSE_PAREN, ')', (0, 50)}, {CLOSE_PAREN, ')', (0, 51)}, {SEMICOLON, ';', (0, 52)}]
|
|
```
|
|
|
|
Tokenizer tries to match input with all available patterns, sticking
|
|
with rule *first-match*. That means if there is more than one patterns
|
|
that match input, only first will be applied.
|
|
This is why you can't for example name your variables or functions/methods
|
|
with keywords. Take a look at the output of following command:
|
|
```
|
|
$ smnp --tokens --dry-run -c "function = 14;"
|
|
[Current(0): {FUNCTION, 'function', (0, 0)}
|
|
{FUNCTION, 'function', (0, 0)}, {ASSIGN, '=', (0, 9)}, {INTEGER, '14', (0, 11)}, {SEMICOLON, ';', (0, 13)}]
|
|
Syntax Error
|
|
[line 1, col 10]
|
|
|
|
Expected function/method name, found '='
|
|
```
|
|
The first token has type of `FUNCTION`, not `IDENTIFIER` which is expected
|
|
for assignment operation.
|
|
|
|
All tokenizer-related code is located in `smnp/token` module.
|
|
|
|
### Parser LL(1)
|
|
Parser is the next stage of code processing pipeline.
|
|
It takes input from tokenizer and tries to compose a tree (called
|
|
AST, which stands for **a**bstract **s**yntax **t**ree) basing on known rules, which are called *productions*.
|
|
As long as tokenizer defines language's *alphabet*, i.e. a set
|
|
of available terminals, parser defines *grammar* of that language.
|
|
It means that tokenizer can for example detect unknown character
|
|
or sequence of characters meanwhile parser is able to detect unknown
|
|
constructions built with known tokens.
|
|
A good example is last snippet from above section related to tokenizer:
|
|
```
|
|
$ smnp --tokens --dry-run -c "function = 14;"
|
|
[Current(0): {FUNCTION, 'function', (0, 0)}
|
|
{FUNCTION, 'function', (0, 0)}, {ASSIGN, '=', (0, 9)}, {INTEGER, '14', (0, 11)}, {SEMICOLON, ';', (0, 13)}]
|
|
Syntax Error
|
|
[line 1, col 10]
|
|
|
|
Expected function/method name, found '='
|
|
```
|
|
You can see, that tokenizer has successfully done his job,
|
|
but parser throw a syntax error saying that it does not know
|
|
any production that could (directly or indirectly) match
|
|
`FUNCTION ASSIGN INTEGER SEMICOLON` sequence.
|
|
|
|
You can check AST produced for arbitrary input code
|
|
using `--ast` flag, for example:
|
|
```
|
|
$ smnp --ast --dry-run -c "[1, 2, 3] as i ^ println(\"Current: \" + i.toString());"
|
|
Program (line 0, col 0)
|
|
└─Loop (line 1, col 1)
|
|
├─List (line 1, col 1)
|
|
│ ├─IntegerLiteral (line 1, col 2)
|
|
│ │ └'1'
|
|
│ ├─IntegerLiteral (line 1, col 5)
|
|
│ │ └'2'
|
|
│ └─IntegerLiteral (line 1, col 8)
|
|
│ └'3'
|
|
├─Operator (line 1, col 16)
|
|
│ └'^'
|
|
├─FunctionCall (line 1, col 18)
|
|
│ ├─Identifier (line 1, col 18)
|
|
│ │ └'println'
|
|
│ └─ArgumentsList (line 1, col 25)
|
|
│ └─Sum (line 1, col 38)
|
|
│ ├─StringLiteral (line 1, col 26)
|
|
│ │ └'Current: '
|
|
│ ├─Operator (line 1, col 38)
|
|
│ │ └'+'
|
|
│ └─Access (line 1, col 41)
|
|
│ ├─Identifier (line 1, col 40)
|
|
│ │ └'i'
|
|
│ ├─Operator (line 1, col 41)
|
|
│ │ └'.'
|
|
│ └─FunctionCall (line 1, col 42)
|
|
│ ├─Identifier (line 1, col 42)
|
|
│ │ └'toString'
|
|
│ └─ArgumentsList (line 1, col 50)
|
|
├─LoopParameters (line 1, col 14)
|
|
│ └─Identifier (line 1, col 14)
|
|
│ └'i'
|
|
└─NoneNode (line 0, col 0)
|
|
```
|
|
|
|
Technically SMNP does have **LL(1)** parser implemented.
|
|
The acronym means:
|
|
* input is read from **L**eft to right
|
|
* parser produces a **L**eft-to-right derivation
|
|
* parser uses one lookahead token.
|
|
Even though this kind of parsers is treated as the least sophisticated, in most cases
|
|
they do the job and are enough even for more advanced use cases.
|
|
|
|
SMNP language parser has some fundamental helper function that provides
|
|
something like construction blocks that are used in right production
|
|
rules implementations. SMNP language parser actually is a combination
|
|
of sub-parsers that are able to parse subset of language.
|
|
|
|
For example `smnp/ast/atom.py` file contains parsers related to parsing
|
|
atomic values, like literals and so on (note also that *expression* with parentheses
|
|
on both sides is treated like atom).
|
|
The file defines `AtomParser` which is actually a function that takes list
|
|
of tokens and produces AST. In this case `AtomParser` is able to parse only token
|
|
sequences mentioned before, like string literals, integer literals etc.
|
|
|
|
But `AtomParser` is used by `UnitParser` located in `smnp/ast/unit.py`.
|
|
`UnitParser` introduces another production rules, like unary minus (`-`) operator
|
|
and dot (`.`) operator (which is used to accessing fields and methods).
|
|
In the first case, production is implemented using `Parser.allOf()` helper function
|
|
which implements *and*-operation (conjunction) performed between symbols.
|
|
```python
|
|
# smnp/ast/unit.py
|
|
minusOperator = Parser.allOf(
|
|
Parser.terminal(TokenType.MINUS, createNode=Operator.withValue),
|
|
Parser.doAssert(AtomParser, "atom"),
|
|
createNode=MinusOperator.withValues,
|
|
name="minus"
|
|
)
|
|
|
|
# this implements following production rule:
|
|
# minusOperator ::= "-" atom
|
|
```
|
|
|
|
Next production rule of `UnitParser` produces `atom2` symbol using `Parser.oneOf()` helper function which
|
|
implements *or*-operation (alternative) performed between symbols:
|
|
```python
|
|
atom2 = Parser.oneOf(
|
|
minusOperator,
|
|
AtomParser,
|
|
name="atom2"
|
|
)
|
|
|
|
# which implements following production rule:
|
|
# atom2 ::= minusOperator | atom
|
|
```
|
|
|
|
The last production rule of `UnitParser` is related to `unit` symbol and implements dot operator:
|
|
```python
|
|
Parser.leftAssociativeOperatorParser(
|
|
atom2,
|
|
[TokenType.DOT],
|
|
Parser.doAssert(atom2, "atom"),
|
|
createNode=lambda left, op, right: Access.withValues(left, op, right),
|
|
name="unit"
|
|
)
|
|
|
|
# which implements following production rule:
|
|
# unit ::= atom2 | atom2 "." atom2
|
|
# (leftAssociativeOperator() is function that implements production rule of left-associative operator)
|
|
```
|
|
|
|
`UnitParser` is then used by `FactorParser` (`smnp/ast/factor.py`) which defines power operator (`**`)
|
|
and logic negation operator (`not`). `FactorParser` is used by `TermParser` (`smnp/ast/term.py`) and `TermParser` is used in turn
|
|
by `ExpressionParser` (`smnp/ast/expression.py`).
|
|
It is also worth paying attention to the impact of cascade of production rules on operators precedence.
|
|
|
|
As you can see, almost each parser is cascadingly composed from another parsers with consistently increased
|
|
supported subset of SMNP language. Thanks to the design, parsers are quite easy to debug and test.
|
|
|
|
All parser-related code is located in `smnp/ast` module.
|
|
|
|
### Evaluator
|
|
Evaluator is the last stage of SMNP language processing pipeline and also is the heart
|
|
of all SMNP tool, which takes AST as input and performs programmed operations.
|
|
Similar to implemented parser, evaluator works *recursively* because of processing tree-like
|
|
structure.
|
|
Evaluator's architecture is similar to parser's one. Evaluator consists of
|
|
smaller evaluators which are able to evaluate small part of AST's node types.
|
|
|
|
Because evaluator introduces as *runtime* term, it also works on special object
|
|
called *environment*. The *environment* object contains some runtime information,
|
|
like available functions (both coming from *stdlib* and user-defined), scopes
|
|
(stack of defined variables), call stack and some meta information, like
|
|
source of code. This object is passed through all evaluators along with AST and its
|
|
subtrees.
|
|
|
|
Example of `and` and `or` operators evaluators:
|
|
```python
|
|
# smnp/runtime/evaluators/logic.py
|
|
class AndEvaluator(Evaluator):
|
|
|
|
@classmethod
|
|
def evaluator(cls, node, environment):
|
|
left = expressionEvaluator(doAssert=True)(node.left, environment).value
|
|
right = expressionEvaluator(doAssert=True)(node.right, environment).value
|
|
return Type.bool(left.value and right.value)
|
|
|
|
|
|
class OrEvaluator(Evaluator):
|
|
|
|
@classmethod
|
|
def evaluator(cls, node, environment):
|
|
left = expressionEvaluator(doAssert=True)(node.left, environment).value
|
|
right = expressionEvaluator(doAssert=True)(node.right, environment).value
|
|
return Type.bool(left.value or right.value)
|
|
```
|
|
|
|
Above evaluators are bound to `And` and respectively `Or` AST nodes in `smnp/runtime/evaluators/expression.py` file,
|
|
which defines `ExpressionEvaluator`:
|
|
```python
|
|
result = Evaluator.oneOf(
|
|
# (...)
|
|
Evaluator.forNodes(AndEvaluator.evaluate, And),
|
|
Evaluator.forNodes(OrEvaluator.evaluate, Or),
|
|
AtomEvaluator.evaluate
|
|
)(node, environment)
|
|
```
|
|
The `ExpressionEvaluator` uses `Evaluator.oneOf()` helper function which
|
|
tries to evaluate given node using one of defined evaluators.
|
|
`Evaluator.forNodes()` helper function in turn wraps evaluator to condition
|
|
which checks if node is one of given node types that are accepted by evaluator.
|
|
|
|
`ExpressionEvaluator` among with some other evaluators is used in main evaluator
|
|
in `smnp/runtime/evaluator.py` file.
|
|
|
|
Evaluator can be disabled using `--dry-run` flag.
|
|
All evaluator-related code is located in `smnp/runtime` module.
|
|
|
|
### Interpreter
|
|
`Interpreter` actually isn't an another language processing
|
|
stage, rather it is a facade that composes each stage in one pipeline,
|
|
accepting a raw SMNP code as input. It also imports
|
|
each function and method from SMNP modules (`smnp/module` module, which is actually
|
|
a *SMNP native library*) and includes
|
|
it to passed `environment` object. As long as environment containing functions and methods
|
|
that come from *SMNP language library* is created in `smnp/main.py` file,
|
|
it is passed as argument to `_interpret()` function as `baseEnvironment` and extends
|
|
newly created `environment` object with its functions and methods. From now
|
|
`environment` object contains both *SMNP native library*'s and *SMNP language library*'s
|
|
functions and methods.
|
|
|
|
Snippet below contains `_interpret()` function that composes pipeline of stages
|
|
mentioned before:
|
|
```python
|
|
# smnp/program/interpreter.py
|
|
# (...)
|
|
from smnp.module import functions, methods
|
|
# (...)
|
|
|
|
class Interpreter:
|
|
# (...)
|
|
|
|
@staticmethod
|
|
def _interpret(lines, source, printTokens=False, printAst=False, execute=True, baseEnvironment=None):
|
|
environment = Environment([{}], functions, methods, source=source)
|
|
|
|
if baseEnvironment is not None:
|
|
environment.extend(baseEnvironment)
|
|
|
|
try:
|
|
tokens = tokenize(lines)
|
|
if printTokens:
|
|
print(tokens)
|
|
|
|
ast = parse(tokens)
|
|
if printAst:
|
|
ast.print()
|
|
|
|
if execute:
|
|
evaluate(ast, environment)
|
|
|
|
return environment
|
|
except RuntimeException as e:
|
|
e.environment = environment
|
|
e.file = environment.source
|
|
raise e
|
|
```
|
|
That's the main flow of SMNP code execution.
|
|
|
|
## Audio module
|
|
Audio module consists so far of 3 elements including 2 output modules (which
|
|
produces a song) and 1 input module (which work is based on microphone input).
|
|
|
|
### `sound` type
|
|
`sound` type was totally covered in previous chapter, so there is nothing to say more.
|
|
You are able to load music and play it via `play()` method.
|
|
Technically this type uses *SoundFile* library which is responsible for loading
|
|
and playing music, so `sound` type actually is a wrapper for Python class provided
|
|
by *SoundFile* framework.
|
|
|
|
### Synthesising module
|
|
In oppose to `sound` type, synthesising module is **designed and implemented from scratch**.
|
|
The only 3rd party code is provided with two frameworks:
|
|
* *SoundDevice* library, which actually
|
|
is an abstract layer above hardware and allows SMNP to pass custom data to sound card in order
|
|
to play music through speakers
|
|
* *Numpy* framework, which provides a special kind of list (*Numpy*'s array) that
|
|
is the only container type accepted by *SoundDevice*.
|
|
|
|
#### Synthesising process
|
|
Synthesising process consists of two stages: compiling notes and playing wave.
|
|
Depending on your needs the stages can be performed separately in different functions
|
|
or merged to just one call.
|
|
|
|
First of all you need to compile notes in order to have wave (which is of `list<float>` type) using `wave` function.
|
|
Then already compiled wave can be finally synthesised with `synth` function.
|
|
```
|
|
notes = [@c, @d, @e, @f];
|
|
compiledWave = wave(notes);
|
|
synth(compiledWave);
|
|
|
|
```
|
|
Above code is really simple, so you can get rid of `wave` function invocation
|
|
and pass notes directly to `synth` function:
|
|
```
|
|
synth([@c, @d, @e, @f]);
|
|
```
|
|
And that's it! Both above codes will play following notes:
|
|
|
|
|
|
##### Rests
|
|
Rest is nothing but `integer` placed among the notes.
|
|
Value of number determines rest's length and works similar to duration part of note literal.
|
|
For example:
|
|
* `1` - whole rest
|
|
* `2` - half rest
|
|
* `4` - quarter rest
|
|
* `8` - eighth rest
|
|
* `16` - sixteenth rest
|
|
* `32` - thirty-second rest
|
|
* `64` - sixty-fourth rest
|
|
* etc.
|
|
|
|
As long as rests are represented as integers, they don't supports dots which make them
|
|
longer with half of value, however you dot can be specified as another rest with
|
|
half value of previous one, for example: dotted half pause = `[2, 4]`.
|
|
|
|
Example of using rests:
|
|
```
|
|
notes = [@c, @d, 4, @f, @g, @a, 4, @c5];
|
|
synth(notes);
|
|
```
|
|
This code will play following notes:
|
|
|
|
|
|
##### Polyphony
|
|
You can have as many note staffs as you want and you are still able to merge them to one
|
|
wave, that can be played later.
|
|
|
|
Both `wave` function and `synth` function accepts multiple lists of notes
|
|
as arguments. If you pass more than one list, all of them will be merged
|
|
and normalised to achieve polyphonic effect.
|
|
|
|
Let's say you have following voices:
|
|
* 
|
|
* 
|
|
|
|
Notes above can be merged to one wave, as follows:
|
|
```
|
|
twinkle1 = [@c, @c, @g, @g, @a, @a, @g:2];
|
|
twinkle2 = [@c, @c, @e, @e, @f, @f, @e:2];
|
|
twinkle = wave(twinkle1, twinkle2);
|
|
synth(twinkle);
|
|
|
|
# or just
|
|
synth(twinkle1, twinkle2);
|
|
```
|
|
The result is:
|
|
|
|
|
|
**Remember**, that in order to achieve the effect you have to pass `list<note, integer>` arguments,
|
|
even if they will consist just of one element.
|
|
|
|
Example:
|
|
```
|
|
synth([@c], [@e], [@g], [@c5]);
|
|
synth(@c, @e, @g, @c5);
|
|
```
|
|
The first line represents following notes:
|
|
|
|
|
|
but the second line is not polyphonic anymore:
|
|
|
|
|
|
##### Tuplets
|
|
Tuplets can be achieved with `tuplet` function, that comes from *stdlib*.
|
|
First argument of function determines how many notes
|
|
you can put, the second one determines how many notes will be
|
|
replaced and the last argument is vararg containing desired notes.
|
|
|
|
Example:
|
|
```
|
|
notes = [@g:2, @d5:2] + tuplet(3, 2, @c5:8, @h:8, @a:8) + [@g5:2, @d5]
|
|
synth(notes)
|
|
```
|
|
the code will play following notes:
|
|
|
|
Instead of 2 eighth notes (the second argument of `tuplet` function)
|
|
we are going to have 3 eighth notes (the first argument of `tuplet` function).
|
|
|
|
Because `tuplet` function produces a list of notes, and both `synth` and
|
|
`wave` functions expect flat lists (i.e. lists that don't contain another lists)
|
|
there is need to concatenate 3 lists in order to have just one.
|
|
Another option is to include `tuplet` function to list in order to have
|
|
nested lists and then use `flat` function, as follows:
|
|
```
|
|
notes = [@g:2, @d5:2, tuplet(3, 2, @c5:8, @h:8, @a:8), @g5:2, @d5]
|
|
synth(flat(notes))
|
|
```
|
|
|
|
#### Synthesising configuration
|
|
Both `wave` and `synth` function have overloaded version that accepts
|
|
a config as first argument.
|
|
|
|
The config value is actually of `map<string><>` type and
|
|
can include following keys:
|
|
* `bpm: integer`
|
|
* `tuning: integer`
|
|
* `overtones: list<float>`
|
|
* `attack: float`
|
|
* `decay: float`
|
|
|
|
Parameters above will be covered in this section. All keys included
|
|
to config map that don't match presented parameters
|
|
will be ignored.
|
|
|
|
Remember, that the config argument is just additional argument
|
|
and are rules presented in previous section are applicable here as well.
|
|
|
|
Example:
|
|
```
|
|
w = wave({ bpm -> 270 }, @c, @d, @e, @f);
|
|
|
|
w2 = wave({ bpm -> 60, tuning -> 432 },
|
|
[@e, @f, @e, @d, @e:2, 2],
|
|
transpose(-12, [@g, @a, @g, @g, @g:2, 2]),
|
|
transpose(-12, [@c, @c, @c:4d, @h3:8, @c:2, 2])
|
|
);
|
|
```
|
|
|
|
##### Tempo
|
|
Tempo can be adjusted with `bpm` property.
|
|
BPM means beats per minute and determines (in this case) how many quarter notes
|
|
will be played during single minute.
|
|
For example:
|
|
* 60 bpm - 60 quarter notes per minute - one quarter note per second
|
|
* 120 bpm - 120 quarter notes per minute - two quarter notes per second
|
|
* and so on.
|
|
|
|
```
|
|
notes = noteRange(@c, @c5, "diatonic"); # C Major scale
|
|
synth({ bpm -> 60 }, notes); # notes will be being played during 8s
|
|
synth({ bpm -> 120 }, notes); # notes will be being played during 4s
|
|
synth({ bpm -> 240 }, notes); # notes will be being played drugin 2s
|
|
```
|
|
|
|
##### Tuning
|
|
`tuning` is the property that determines frequency of `@a` sound.
|
|
Typically it is set to 440Hz or 432Hz, but it can be any positive value.
|
|
Using this property you are able to adjust tuning of all available notes.
|
|
|
|
Example:
|
|
```
|
|
a4 = @a:128;
|
|
plot(wave({ tuning -> 440, overtones -> [1.0] }, a4));
|
|
plot(wave({ tuning -> 127, overtones -> [1.0] }, a4));
|
|
```
|
|
|
|
|
|
Plots above presents fundamental tone's sine wave of the same note: `@a`
|
|
in different tuning systems.
|
|
|
|
You can hear the difference executing following code:
|
|
```
|
|
notes = noteRange(@c, @c5, "diatonic"); # C Major scale
|
|
synth({ tuning -> 440 }, notes);
|
|
synth({ tuning -> 512 }, notes);
|
|
```
|
|
|
|
##### Overtones
|
|
Overtones allows you to specify the sound of single note being compiled.
|
|
In fact each note can be composed from sine waves with greater and greater
|
|
frequencies.
|
|
`overtones` parameter is a list of float values, that represents
|
|
a quotient of influence each overtone to output wave's amplitude.
|
|
First value at the list is related to fundamental tone. Second one
|
|
is related to first overtone (second harmonic), the third one
|
|
is related to second overtone (third harmonic) and so on.
|
|
You can read more about overtones at [Wikipedia](https://en.wikipedia.org/wiki/Overtone).
|
|
|
|
Sum of list of overtones' values must be less or equal to 1.
|
|
To disable overtone simply put `0.0` at proper place of list.
|
|
For example sound with `overtones = [0.7, 0.0, 0.3]` consists
|
|
only of fundamental tone with amplitude equal to 0.7 of total amplitude and
|
|
third harmonic with amplitude equal to 0.3 of total amplitude. No other overtones
|
|
are enabled.
|
|
|
|
Examples (with related plots):
|
|
|
|
1st example (1 overtone - ideal pitchfork sound)
|
|
```
|
|
# v 1st
|
|
w = wave({ overtones -> [1.0] }, @a:64) # a = 440 Hz
|
|
plot(w)
|
|
plot(fft(w))
|
|
```
|
|
|
|
|
|
|
|
|
|
2nd example (2 overtones)
|
|
```
|
|
# v 1st v 3rd
|
|
w = wave({ overtones -> [0.7, 0.0, 0.3] }, @a:64)
|
|
plot(w)
|
|
plot(fft(w))
|
|
```
|
|
|
|
|
|
|
|
3rd example (3 overtones)
|
|
```
|
|
# v 1st v 3rd v 14th
|
|
w = wave({ overtones -> [0.5, 0.0, 0.3] + (10 ^ 0.0) + [0.2] }, @a:64)
|
|
plot(w)
|
|
plot(fft(w))
|
|
```
|
|
|
|
|
|
|
|
##### Decay
|
|
`decay` parameter defines the tail of sound. Value of the parameter
|
|
determines how fast the sound is going to be "blanked".
|
|
The greater value of `decay` parameter, the sound will be blanked faster.
|
|
If `decay` parameter is set to 0, sound will not change its magnitude anymore.
|
|
|
|
Example (with proper plots):
|
|
```
|
|
a4 = @a:16;
|
|
plot(wave({ decay -> 0, overtones -> [1.0] }, a4));
|
|
plot(wave({ decay -> 0.5, overtones -> [1.0] }, a4));
|
|
plot(wave({ decay -> 1, overtones -> [1.0] }, a4));
|
|
plot(wave({ decay -> 5, overtones -> [1.0] }, a4));
|
|
plot(wave({ decay -> 10, overtones -> [1.0] }, a4));
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### Attack
|
|
`attack` parameter is the last one supported by config map
|
|
and in oppose to `decay` determines how fast the sound is going to reach
|
|
full magnitude.
|
|
The greater value of `attack`, the sound will reach full magnitude faster.
|
|
If `attack` parameter is set to 0, the effect will be disabled and full
|
|
magnitude will be reached immediately.
|
|
|
|
Example (with proper plots):
|
|
```
|
|
a4 = @a:16;
|
|
plot(wave({ attack -> 0, decay -> 0, overtones -> [1.0] }, a4));
|
|
plot(wave({ attack -> 1, decay -> 0, overtones -> [1.0] }, a4));
|
|
plot(wave({ attack -> 5, decay -> 0, overtones -> [1.0] }, a4));
|
|
plot(wave({ attack -> 10, decay -> 0, overtones -> [1.0] }, a4));
|
|
plot(wave({ attack -> 100, decay -> 0, overtones -> [1.0] }, a4));
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### Mixing parameters
|
|
You are able to mix parameters and achieve really interesting results
|
|
to emulate for example piano, guitar, string ensemble etc.
|
|
|
|
For example, you can achieve this sound's shape:
|
|
|
|
using following code:
|
|
```
|
|
config = {
|
|
attack -> 2,
|
|
decay -> 7,
|
|
overtones -> [0.5, 0.0, 0.0, 0.0, 0.3, 0.0, 0.2]
|
|
};
|
|
|
|
plot(wave(config, @a:64));
|
|
|
|
synth(config, [@c:1, @d:1, @e:1, @f:1], [2, @c5:1, @h:2, @c:1, @a:1]);
|
|
```
|
|
It sounds really magically, isn't it?
|
|
Feel free to mix parameters in order to achieve desired sound
|
|
and enjoy it!
|
|
|
|
##### Default values
|
|
If you don't pass any of supported parameters or even use
|
|
the simplest signature of `wave` or `synth` function, following default
|
|
values will be assigned to each parameter:
|
|
* `bpm = 120`
|
|
* `tuning = 440`
|
|
* `overtones = [0.4, 0.3, 0.1, 0.1, 0.1]`
|
|
* `decay = 4`
|
|
* `attack = 100`
|
|
|
|
which causes following sound's shape:
|
|
```
|
|
plot(wave(@a:64))
|
|
```
|
|
|
|
|
|
### Listening module
|
|
Listening module is the only implemented module that processes input
|
|
coming from microphone.
|
|
Moreover the module contains only one function which is `wait`.
|
|
The function accepts 2 integer arguments: `soundLevel` and `silenceLevel` and is useful to ear training.
|
|
The goal of `wait` function is to hang program execution and wait
|
|
for incoming sound. Only when the sound sounds and then stops,
|
|
the program's execution will be resumed.
|
|
|
|
Function can be in three states. Let's call them:
|
|
* `WAIT_FOR_SOUND`
|
|
* `WAIT_FOR_SILENCE`
|
|
* `RESUME`.
|
|
|
|
Now it is possible to show how it works using finite states machine:
|
|
|
|
|
|
In other words, `wait` function waits for sound, which means
|
|
it hangs program execution and waits for exceeding `soundLevel` parameter by input level,
|
|
which is the first argument of `wait` function.
|
|
After that it waits for sound's stop (i.e. input level must be less than `silenceLevel`, which is
|
|
the second argument of `wait` function).
|
|
Only then `wait` function ends its work and resumes program's execution.
|
|
|
|
If you are not sure about what `soundLevel` or `silenceLevel` values you need to use,
|
|
you can run SMNP program with `-m` flag in order to test in real time what kind of noise produces what level.
|
|
|
|
Instead of calling function with two arguments, you can invoke it without any argument.
|
|
In that case:
|
|
```
|
|
wait()
|
|
```
|
|
is equivalent of
|
|
```
|
|
wait(300, 10)
|
|
```
|
|
|
|
## Command-line interface
|
|
SMNP is provided as command-line tool and so far doesn't support
|
|
any graphic interface.
|
|
The simplest way to use SMNP is to type `smnp <file>`, where `<file>`
|
|
is a file containing SMNP language code.
|
|
You can put more files than one, just remember to split them with
|
|
spaces.
|
|
You are also able to execute SMNP language inline, which can be useful
|
|
in some kinds of batch scripts.
|
|
It can be done using `-c` option, like on following example:
|
|
```
|
|
$ smnp -c "println(\"Hello, world!\")"
|
|
Hello, world!
|
|
$
|
|
```
|
|
Remember to escape all quotes if you are typing string literals
|
|
in this mode.
|
|
|
|
Apart from this options mentioned so far, SMNP provides you another ones,
|
|
which you can list using `smnp -h` command.
|
|
All of them are also covered below:
|
|
* `-c <code>` - allows you to execute code passed as argument instead
|
|
of reading it from file
|
|
* `-m` - allows you to test input level coming from microphone
|
|
* `-h` - displays simple manual of SMNP usage with all options and
|
|
flags described
|
|
* `-v` - displays version of SMNP
|
|
|
|
Options planned to be implemented:
|
|
* `-C <config>` (not implemented yet) - allows you to override
|
|
default file that contains common configuration of SMNP tool
|
|
* `-P <key>=<value>` (not implemented yet) - allows you to pass
|
|
properties that you will be able to obtain from code
|
|
|
|
Because SMNP acts also as educational tool on field of parsing formal
|
|
languages, there are also implemented some flags allowing you
|
|
to see what is going on at each language processing stage:
|
|
* `--tokens` - prints tokenizer's output for passed code
|
|
* `--ast` - *pretty-prints* abstract syntax tree as parser's output for passed code
|
|
* `--dry-run` - runs language-processing tools without involving evaluator
|
|
|
|
## Installation
|
|
To install SMNP:
|
|
1. Make sure you have already installed *PortAudio* in your OS (it is required by Audio Module
|
|
to send data frames to your sound device)
|
|
2. Clone this repository and enter to it
|
|
3. Run `pip install .` inside root repository folder
|