s416496/musique
1
0
Fork 0
Code Issues 3 Pull Requests 1 Projects Releases Wiki Activity

function documentation part 2

Browse Source
This commit is contained in:
Mateusz Piątkowski 2023-01-08 14:14:47 +01:00
parent 986545b2ec
commit c8b8adca5d
1 changed files with 151 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
musique/interpreter/builtin_functions.cc
View File

@ -370,6 +370,12 @@ static std::optional<Error> action_play(Interpreter &i, Value v)
return {};
}
//: Funkcja `play` odgrywa zadaną nutę lub sekwencję.
//:
//: # Przykład
//: ```
//: > play chord c e g
//: ```
/// Play notes
template<With_Index_Operator Container = std::vector<Value>>
static inline Result<Value> builtin_play(Interpreter &interpreter, Container args)
@ -395,6 +401,12 @@ static inline Result<Value> builtin_play(Interpreter &interpreter, Container arg
return {};
}
//: Funkcja `par` odgrywa pierwszy element przez sumę długości pozostałych elementów. Odegranie pierwszego elementu wraz z pozostałymi następuje współbieżnie.
//:
//: # Przykład
//: ```
//: > par c (1/2) b b e
//: ```
/// Play first argument while playing all others
static Result<Value> builtin_par(Interpreter &interpreter, std::vector<Value> args) {
Try(ensure_midi_connection_available(interpreter, "par"));
@ -430,6 +442,14 @@ static Result<Value> builtin_par(Interpreter &interpreter, std::vector<Value> ar
return result;
}
//: Funkcja `sim` odgrywa zadane sekwencje symultanicznie.
//:
//: # Przykład
//: ```
//: > A := c e g d
//: > B := f f a a
//: > sim A B
//: ```
/// Plays each argument simultaneously
static Result<Value> builtin_sim(Interpreter &interpreter, std::vector<Value> args)
{
@ -558,6 +578,13 @@ static inline size_t upper_sieve_bound_to_yield_n_primes(size_t n_primes)
return std::ceil(x);
}
//: Funkcja `nprimes` zwraca zadaną liczbę kolejnych liczb pierwszych.
//:
//: # Przykład
//: ```
//: > nprimes 4
//: (2, 3, 5, 7)
//: ```
/// Generate n primes
static Result<Value> builtin_primes(Interpreter&, std::vector<Value> args)
{
@ -607,6 +634,16 @@ static Result<Value> builtin_primes(Interpreter&, std::vector<Value> args)
};
}
//: Funkcja `nprimes` zwraca zadaną liczbę kolejnych liczb pierwszych.
//:
//: # Przykład
//: ```
//: > for (nprimes 4) (say)
//: 2
//: 3
//: 5
//: 7
//: ```
/// Iterate over container
static Result<Value> builtin_for(Interpreter &i, std::vector<Value> args)
{
@ -627,6 +664,12 @@ static Result<Value> builtin_for(Interpreter &i, std::vector<Value> args)
}
}
//: Funkcja `fold` TODO.
//:
//: # Przykład
//: ```
//: TODO
//: ```
/// Fold container
static Result<Value> builtin_fold(Interpreter &interpreter, std::vector<Value> args) {
constexpr auto guard = Guard<2> {
@ -653,6 +696,14 @@ static Result<Value> builtin_fold(Interpreter &interpreter, std::vector<Value> a
return guard.yield_error();
}
//: Funkcja `map` aplikuje zadaną funkcję do każdego argumentu.
//:
//: # Przykład
//: ```
//: > map up (nprimes 3)
//: ((0, 1), (0, 1, 2), (0, 1, 2, 3, 4))
//: ```
static Result<Value> builtin_map(Interpreter &interpreter, std::vector<Value> args)
{
static constexpr auto guard = Guard<2> {
@ -684,6 +735,12 @@ static Result<Value> builtin_map(Interpreter &interpreter, std::vector<Value> ar
return result;
}
//: Funkcja `scan` oblicza sumę prefiksową (dodaje do siebie wszystkie liczby od 1 do danej liczby).
//:
//: # Przykład
//: ```
//:
//: ```
/// Scan computes inclusive prefix sum
static Result<Value> builtin_scan(Interpreter &interpreter, std::vector<Value> args)
{
@ -706,6 +763,19 @@ static Result<Value> builtin_scan(Interpreter &interpreter, std::vector<Value> a
};
}
//: Funkcja `if` wykonuje określony blok po spełnieniu warunku, alternatywnie wykonuje inny blok kodu w przeciwnym wypadku.
//:
//: # Przykład
//: ```
//: > if true (say 42)
//: 42
//: > if false (say 42)
//: >
//: > if true (say 42) (say 0)
//: 42
//: > if false (say 42) (say 0)
//: 0
//: ```
/// Execute blocks depending on condition
static Result<Value> builtin_if(Interpreter &i, std::span<Ast> args) {
static constexpr auto guard = Guard<2> {
@ -737,6 +807,18 @@ static Result<Value> builtin_if(Interpreter &i, std::span<Ast> args) {
return Value{};
}
//: Funkcja `while` wykonuje określony blok dopóki warunek jest spełniony.
//:
//: # Przykład
//: ```
//: > i := 0
//: > while (i < 10) (say i, i += 2)
//: 0
//: 2
//: 4
//: 6
//: 8
//: ```
/// Loop block depending on condition
static Result<Value> builtin_while(Interpreter &i, std::span<Ast> args) {
static constexpr auto guard = Guard<2> {
@ -760,6 +842,12 @@ static Result<Value> builtin_while(Interpreter &i, std::span<Ast> args) {
return Value{};
}
//: Funkcja `try` przystępuje do wykonania bloków kodu, a jeżeli którykolwiek z nich zakończy się niepowodzeniem, wykonuje ostatni. Jeżeli ostatni też zakończy się niepowodzeniem, to trudno.
//:
//: # Przykład
//: ```
//: TODO
//: ```
/// Try executing all but last block and if it fails execute last one
static Result<Value> builtin_try(Interpreter &interpreter, std::vector<Value> args)
{
@ -790,6 +878,16 @@ static Result<Value> builtin_try(Interpreter &interpreter, std::vector<Value> ar
return success;
}
//: Funkcja `update` aktualizuje dany element listy na nową wartość.
//:
//: # Przykład
//: ```
//: > A := down 5
//: > A
//: (4, 3, 2, 1, 0)
//: > update A 3 7
//: (4, 3, 2, 7, 0)
//: ```
/// Update value inside of array
static Result<Value> builtin_update(Interpreter &i, std::vector<Value> args)
{
@ -820,6 +918,15 @@ static Result<Value> builtin_update(Interpreter &i, std::vector<Value> args)
return guard.yield_error();
}
//: Funkcja `typeof` zwraca typ zmiennej.
//: # Przykład
//: ```
//: > A := down 5
//: > A
//: (4, 3, 2, 1, 0)
//: > typeof A
//: array
//: ```
/// Return typeof variable
static Result<Value> builtin_typeof(Interpreter&, std::vector<Value> args)
{
@ -858,6 +965,15 @@ Result<Value> traverse(Interpreter &interpreter, Value &&value, auto &&lambda)
return value;
}
//: Funkcja `set_len` przydziela wszystkim elementom listy zadaną długość.
//: # Przykład
//: ```
//: > A := c d e f
//: > A
//: (c, d, e, f)
//: > set_len (1/8) A
//: (c 1/8, d 1/8, e 1/8, f 1/8)
//: ```
/// Set length (first argument) to all other arguments preserving their shape
static Result<Value> builtin_set_len(Interpreter &interpreter, std::vector<Value> args)
{
@ -887,6 +1003,15 @@ static Result<Value> builtin_set_len(Interpreter &interpreter, std::vector<Value
};
}
//: Funkcja `set_oct` przydziela wszystkim elementom listy zadaną wysokość.
//: # Przykład
//: ```
//: > A := c d e f
//: > A
//: (c, d, e, f)
//: > set_oct 5 A
//: (c5, d5, e5, f5)
//: ```
/// Set octave (first argument) to all other arguments preserving their shape
static Result<Value> builtin_set_oct(Interpreter &interpreter, std::vector<Value> args)
{
@ -928,7 +1053,9 @@ static Result<Value> builtin_duration(Interpreter &interpreter, std::vector<Valu
for (auto &arg : args) {
Try(traverse(interpreter, std::move(arg), [&](Chord &c) {
for (Note &note : c.notes) {
total += note.length ? *note.length : interpreter.current_context->length;
if (note.length) {
total += *note.length;
}
}
}));
}
@ -1103,7 +1230,7 @@ static Result<Value> builtin_partition(Interpreter &i, std::vector<Value> args)
}};
}
//: Funkcja `rotate` przenosi na koniec listy zadaną ilość elementów
//: Funkcja `rotate` przenosi na koniec listy zadaną ilość elementów.
//:
//: # Przykład
//: ```
@ -1137,6 +1264,13 @@ static Result<Value> builtin_rotate(Interpreter &i, std::vector<Value> args)
return guard.yield_error();
}
//: Funkcja `unique` zwraca listę argumentów z wyłączeniem powtórzeń.
//:
//: # Przykład
//: ```
//: > unique 1 2 3 2 2 3 4
//: (1, 2, 3, 4)
//: ```
/// Returns unique collection of arguments
static Result<Value> builtin_unique(Interpreter &i, std::vector<Value> args)
{
@ -1153,6 +1287,13 @@ static Result<Value> builtin_unique(Interpreter &i, std::vector<Value> args)
return result;
}
//: Funkcja `uniq` usuwa z listy argumentów następujące po sobie powtórzenia elementów.
//:
//: # Przykład
//: ```
//: > uniq 1 2 3 2 2 2 2 2 2 3 4
//: (1, 2, 3, 2, 3, 4)
//: ```
/// Returns arguments with all successive copies eliminated
static Result<Value> builtin_uniq(Interpreter &i, std::vector<Value> args)
{
@ -1170,6 +1311,13 @@ static Result<Value> builtin_uniq(Interpreter &i, std::vector<Value> args)
return result;
}
//: Funkcja `hash` zwraca wynik działania funkcji skrótu.
//:
//: # Przykład
//: ```
//: > hash 4
//: 177902120014
//: ```
static Result<Value> builtin_hash(Interpreter&, std::vector<Value> args)
{
return Number(
@ -1179,8 +1327,6 @@ static Result<Value> builtin_hash(Interpreter&, std::vector<Value> args)
);
}
/// Build chord from arguments
//: Funkcja `chord` zwraca akord złożony z nut podanych jako argumenty.
//:
//: # Przykład
@ -1188,6 +1334,7 @@ static Result<Value> builtin_hash(Interpreter&, std::vector<Value> args)
//: > chord c# e a#
//: chord (c#, e, a#)
//: ```
/// Build chord from arguments
static Result<Value> builtin_chord(Interpreter &i, std::vector<Value> args)
{
Chord chord;
@ -1215,7 +1362,6 @@ static Result<Value> builtin_note_on(Interpreter &interpreter, std::vector<Value
note = interpreter.current_context->fill(note);
interpreter.midi_connection->send_note_on(chan.as_int(), *note.into_midi_note(), vel.as_int());
}
return Value{};
}
return Error {
@ -1253,7 +1399,6 @@ static Result<Value> builtin_note_off(Interpreter &interpreter, std::vector<Valu
note = interpreter.current_context->fill(note);
interpreter.midi_connection->send_note_off(chan.as_int(), *note.into_midi_note(), 127);
}
return Value{};
}
return Error {