From c8b8adca5d7096d8a29e75cef50718419e5f5101 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Pi=C4=85tkowski?= Date: Sun, 8 Jan 2023 14:14:47 +0100 Subject: [PATCH] function documentation part 2 --- musique/interpreter/builtin_functions.cc | 157 ++++++++++++++++++++++- 1 file changed, 151 insertions(+), 6 deletions(-) diff --git a/musique/interpreter/builtin_functions.cc b/musique/interpreter/builtin_functions.cc index 97afacf..991e9a5 100644 --- a/musique/interpreter/builtin_functions.cc +++ b/musique/interpreter/builtin_functions.cc @@ -370,6 +370,12 @@ static std::optional action_play(Interpreter &i, Value v) return {}; } +//: Funkcja `play` odgrywa zadaną nutę lub sekwencję. +//: +//: # Przykład +//: ``` +//: > play chord c e g +//: ``` /// Play notes template> static inline Result builtin_play(Interpreter &interpreter, Container args) @@ -395,6 +401,12 @@ static inline Result 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 builtin_par(Interpreter &interpreter, std::vector args) { Try(ensure_midi_connection_available(interpreter, "par")); @@ -430,6 +442,14 @@ static Result builtin_par(Interpreter &interpreter, std::vector 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 builtin_sim(Interpreter &interpreter, std::vector 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 builtin_primes(Interpreter&, std::vector args) { @@ -607,6 +634,16 @@ static Result builtin_primes(Interpreter&, std::vector args) }; } +//: Funkcja `nprimes` zwraca zadaną liczbę kolejnych liczb pierwszych. +//: +//: # Przykład +//: ``` +//: > for (nprimes 4) (say) +//: 2 +//: 3 +//: 5 +//: 7 +//: ``` /// Iterate over container static Result builtin_for(Interpreter &i, std::vector args) { @@ -627,6 +664,12 @@ static Result builtin_for(Interpreter &i, std::vector args) } } +//: Funkcja `fold` TODO. +//: +//: # Przykład +//: ``` +//: TODO +//: ``` /// Fold container static Result builtin_fold(Interpreter &interpreter, std::vector args) { constexpr auto guard = Guard<2> { @@ -653,6 +696,14 @@ static Result builtin_fold(Interpreter &interpreter, std::vector 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 builtin_map(Interpreter &interpreter, std::vector args) { static constexpr auto guard = Guard<2> { @@ -684,6 +735,12 @@ static Result builtin_map(Interpreter &interpreter, std::vector 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 builtin_scan(Interpreter &interpreter, std::vector args) { @@ -706,6 +763,19 @@ static Result builtin_scan(Interpreter &interpreter, std::vector 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 builtin_if(Interpreter &i, std::span args) { static constexpr auto guard = Guard<2> { @@ -737,6 +807,18 @@ static Result builtin_if(Interpreter &i, std::span 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 builtin_while(Interpreter &i, std::span args) { static constexpr auto guard = Guard<2> { @@ -760,6 +842,12 @@ static Result builtin_while(Interpreter &i, std::span 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 builtin_try(Interpreter &interpreter, std::vector args) { @@ -790,6 +878,16 @@ static Result builtin_try(Interpreter &interpreter, std::vector 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 builtin_update(Interpreter &i, std::vector args) { @@ -820,6 +918,15 @@ static Result builtin_update(Interpreter &i, std::vector 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 builtin_typeof(Interpreter&, std::vector args) { @@ -858,6 +965,15 @@ Result 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 builtin_set_len(Interpreter &interpreter, std::vector args) { @@ -887,6 +1003,15 @@ static Result builtin_set_len(Interpreter &interpreter, std::vector 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 builtin_set_oct(Interpreter &interpreter, std::vector args) { @@ -928,7 +1053,9 @@ static Result builtin_duration(Interpreter &interpreter, std::vectorlength; + if (note.length) { + total += *note.length; + } } })); } @@ -1103,7 +1230,7 @@ static Result builtin_partition(Interpreter &i, std::vector 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 builtin_rotate(Interpreter &i, std::vector 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 builtin_unique(Interpreter &i, std::vector args) { @@ -1153,6 +1287,13 @@ static Result builtin_unique(Interpreter &i, std::vector 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 builtin_uniq(Interpreter &i, std::vector args) { @@ -1170,6 +1311,13 @@ static Result builtin_uniq(Interpreter &i, std::vector args) return result; } +//: Funkcja `hash` zwraca wynik działania funkcji skrótu. +//: +//: # Przykład +//: ``` +//: > hash 4 +//: 177902120014 +//: ``` static Result builtin_hash(Interpreter&, std::vector args) { return Number( @@ -1179,8 +1327,6 @@ static Result builtin_hash(Interpreter&, std::vector 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 builtin_hash(Interpreter&, std::vector args) //: > chord c# e a# //: chord (c#, e, a#) //: ``` +/// Build chord from arguments static Result builtin_chord(Interpreter &i, std::vector args) { Chord chord; @@ -1215,7 +1362,6 @@ static Result builtin_note_on(Interpreter &interpreter, std::vectorfill(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 builtin_note_off(Interpreter &interpreter, std::vectorfill(note); interpreter.midi_connection->send_note_off(chan.as_int(), *note.into_midi_note(), 127); } - return Value{}; } return Error {