From 02fd959e58d7b249b7bec7fc7859c8b860166972 Mon Sep 17 00:00:00 2001 From: aNNiMON Date: Mon, 27 Nov 2023 19:55:11 +0200 Subject: [PATCH] Add new functions documentation --- docs/src/modules/functional.yml | 180 ++++++++++++------ docs/src/modules/std.yml | 52 ++++- .../resources/modules/functional/groupby.own | 13 ++ 3 files changed, 185 insertions(+), 60 deletions(-) diff --git a/docs/src/modules/functional.yml b/docs/src/modules/functional.yml index 4ee5f3b..c0b554f 100644 --- a/docs/src/modules/functional.yml +++ b/docs/src/modules/functional.yml @@ -10,11 +10,11 @@ constants: desc: "function which returns passed argument" desc_ru: "функция, которая возвращает переданный в неё аргумент" functions: - - name: "chain" + - name: chain args: "data, functions..." desc: "" desc_ru: "" - - name: "combine" + - name: combine args: "functions..." desc: "combines functions" desc_ru: "комбинирует функции (композиция)" @@ -55,7 +55,7 @@ functions: nums = [1,2,3,4,5] print filter(nums, def(x) = x % 2 == 0) // [2, 4] - - name: "flatmap" + - name: flatmap args: "array, mapper" desc: "converts each element of an array to other array" desc_ru: "преобразует каждый элемент массива в массив элементов" @@ -69,7 +69,7 @@ functions: arr[i] = x return arr }) // [1, 2, 2, 3, 3, 3, 4, 4, 4, 4] - - name: "foreach" + - name: foreach args: "data, consumer" desc: "invokes function `consumer` for each element of array or map `data`\n\nIf `data` - массив, то в функции consumer необходим один параметр, если объект - два (ключ и значение)." desc_ru: "для каждого элемента в массиве или объекте `data` вызывает функцию `consumer`\n\nЕсли `data` - массив, то в функции `consumer` необходим один параметр, если объект - два (ключ и значение)." @@ -80,7 +80,7 @@ functions: foreach({"key": 1, "key2": "text"}, def(key, value) { print key + ": " + value }) - - name: "map" + - name: map args: "data, mapper..." desc: "converts elements of array or map. If `data` is array - `mapper` converts his elements, if `data` is object - you need to pass `keyMapper` - converts keys and `valueMapper` - converts values" desc_ru: "преобразует элементы массива или объекта.\n\nЕсли `data` - массив, то функция `mapper` преобразует значения, если объект - необходимо передать две функции: `keyMapper` - преобразует ключи и `valueMapper` - преобразует значения" @@ -89,7 +89,7 @@ functions: nums = [3,4,5] print map(nums, def(x) = x * x) // [9, 16, 25] - - name: "reduce" + - name: reduce args: "data, identity, accumulator" desc: "converts elements of an array or a map to one value, e.g. sum of elements or concatenation string. `accumulator` takes one argument for array and two arguments for object (key and value)." desc_ru: "преобразует элементы массива или объекта в одно значение, например сумма элементов или объединение в строку.\n\nЕсли `data` - массив, то в функции `accumulator` необходим один параметр, если объект - два (ключ и значение)" @@ -98,10 +98,10 @@ functions: nums = [1,2,3,4,5] print reduce(nums, 0, def(x, y) = x + y) // 15 - - name: "sortby" + - name: sortby args: "array, function" - desc: "sorts elements of an array or an object by `function` result" - desc_ru: "сортирует элементы массива по данным в функции `function`" + desc: "sorts elements of an array or a map by `function` result" + desc_ru: "сортирует элементы массива или объекта по данным в функции `function`" example: |- use functional @@ -111,51 +111,125 @@ functions: {"k1": 4, "k2": "z"}, {"k1": 5, "k2": "p"}, ] - print sortby(data, def(v) = v.k1) // [{k1=2, k2=x}, {k1=4, k2=z}, {k1=5, k2=p}, {k1=7, k2=d}] - print sortby(data, def(v) = v.k2) // [{k1=7, k2=d}, {k1=5, k2=p}, {k1=2, k2=x}, {k1=4, k2=z}] - - name: "stream" - args: "data" - desc: |- - creates stream from data and returns StreamValue + println sortby(data, def(v) = v.k1) // [{k1=2, k2=x}, {k1=4, k2=z}, {k1=5, k2=p}, {k1=7, k2=d}] + println sortby(data, def(v) = v.k2) // [{k1=7, k2=d}, {k1=5, k2=p}, {k1=2, k2=x}, {k1=4, k2=z}] + - name: groupby + args: "data, function" + desc: "groups elements of an array or a map by `function` result" + desc_ru: "группирует элементы массива или объекта на основе результата функции `function`" + since: 2.0.0 + example: |- + use functional - StreamValue functions: - - `filter(func)` - filters elements - - `map(func)` - converts each element - - `flatMap(func)` - converts each element to array - - `sorted(func)` - sorts elements with comparator function - - `sortBy(func)` - applies function, then sorts elements - - `takeWhile(func)` - takes elements while predicate function returns true - - `dropWhile(func)` - skips elements while predicate function returns true - - `peek(func)` - executes function for each element and returns stream - - `skip(count)` - skips count elements - - `limit(count)` - limits elements size - - `custom(func)` - performs custom operation - - `reduce(func)` - converts elements to one value - - `forEach(func)` - executes function for each element - - `joining(delimiter = "", prefix = "", suffix = "")` - joins elements into a string - - `toArray()` - returns array of elements - - `count()` - returns count of elements - desc_ru: |- - создаёт stream из данных и возвращает StreamValue - - Функции StreamValue: - - `filter(func)` - фильтрует элементы - - `map(func)` - преобразует каждый элемент - - `flatMap(func)` - преобразует каждый элемент в массив - - `sorted(func)` - сортирует элементы в соответствии с функцией-компаратором - - `sortBy(func)` - применяет функцию, затем сортирует элементы - - `takeWhile(func)` - собирает элементы пока функция-предикат возвращает true - - `dropWhile(func)` - пропускает элементы пока функция-предикат возвращает true - - `peek(func)` - вызывает функцию для каждого элемента и возвращает stream - - `skip(count)` - пропускает указанное количество элементов - - `limit(count)` - ограничивает количество элементов - - `custom(func)` - выполняет пользовательскую операцию над данными - - `reduce(func)` - преобразует элементы в одно значение - - `forEach(func)` - вызывает функцию для каждого элемента - - `joining(delimiter = "", prefix = "", suffix = "")` - склеивает элементы в строку - - `toArray()` - возвращает массив элементов - - `count()` - возвращает количество элементов + data = [ + {"k1": 2, "k2": "x"}, + {"k1": 4, "k2": "z"}, + {"k1": 5, "k2": "p"}, + ] + println groupby(data, def(e) = e.k1) // {"2"=[{k1=2, k2=x}], "4"=[{k1=4, k2=z}], "5"=[{k2=p, k1=5}]} + println groupby(data, def(e) = e.k2) // {"x"=[{k1=2, k2=x}], "z"=[{k1=4, k2=z}], "p"=[{k2=p, k1=5}]} + - name: stream + args: data + desc: creates stream from data and returns `StreamValue` + desc_ru: создаёт stream из данных и возвращает `StreamValue` - name: takewhile args: 'data, predicate' desc: 'takes elements while predicate function returns true' - desc_ru: 'собирает элементы пока функция-предикат возвращает true' \ No newline at end of file + desc_ru: 'собирает элементы пока функция-предикат возвращает true' +types: + - name: StreamValue + functions: + - name: filter + args: func + desc: filters elements based on predicate function result (true - remain, false - drop) + desc_ru: фильтрует элементы на основе результата функции-предиката (true - оставить, false - убрать) + - name: filterNot + args: func + desc: filters elements based on negated predicate function result (false - remain, true - drop) + desc_ru: фильтрует элементы на основе обратного результата функции-предиката (false - оставить, true - убрать) + since: 2.0.0 + - name: map + args: func + desc: converts each element + desc_ru: преобразует каждый элемент + - name: flatMap + args: func + desc: converts each element to array + desc_ru: преобразует каждый элемент в массив + - name: sorted + args: func + desc: sorts elements with comparator function + desc_ru: сортирует элементы в соответствии с функцией-компаратором + - name: sortBy + args: func + desc: applies function, then sorts elements + desc_ru: применяет функцию, затем сортирует элементы + - name: groupBy + args: func + desc: groups elements based on function result + desc_ru: группирует элементы на основе результата выполнения функции + since: 2.0.0 + - name: takeWhile + args: func + desc: takes elements while predicate function returns true + desc_ru: собирает элементы пока функция-предикат возвращает true + - name: dropWhile + args: func + desc: skips elements while predicate function returns true, returns remaining elements + desc_ru: пропускает элементы пока функция-предикат возвращает true + - name: peek + args: func + desc: executes function for each element and returns stream + desc_ru: вызывает функцию для каждого элемента и возвращает stream + - name: skip + args: count + desc: skips `count` elements + desc_ru: пропускает указанное количество элементов + - name: limit + args: count + desc: limits elements size + desc_ru: ограничивает количество элементов + - name: custom + args: func + desc: performs custom operation + desc_ru: выполняет пользовательскую операцию над данными + example: |- + use std, functional + + println stream([1, 2, 3, 4]) + .custom(::reverse) + .toArray() + + def reverse(container) { + size = length(container) + result = newarray(size) + for i : range(size) { + result[size - i - 1] = container[i] + } + return result + } + - name: reduce + args: func + desc: converts elements to one value + desc_ru: преобразует элементы в одно значение + - name: forEach + args: func + desc: executes function for each element + desc_ru: вызывает функцию для каждого элемента + - name: forEachIndexed + args: func + desc: executes function for each element and its index + desc_ru: вызывает функцию для каждого элемента и его порядкового номера + since: 2.0.0 + - name: joining + args: delimiter = "", prefix = "", suffix = "" + desc: joins elements into a string + desc_ru: склеивает элементы в строку + - name: toArray + args: "" + desc: returns array of elements + desc_ru: возвращает массив элементов + - name: count + args: "" + desc: returns the elements count + desc_ru: возвращает количество элементов diff --git a/docs/src/modules/std.yml b/docs/src/modules/std.yml index 18afef7..92abeba 100644 --- a/docs/src/modules/std.yml +++ b/docs/src/modules/std.yml @@ -11,7 +11,7 @@ constants: - name: OwnLang typeName: map type: 4 - value: "{PLATFORM=android/desktop, VERSION=1.5.0_000000, VERSION_MAJOR=1, VERSION_MINOR=5, VERSION_PATCH=0}" + value: "{PLATFORM=android/desktop, VERSION=2.0.1_000000, VERSION_MAJOR=2, VERSION_MINOR=0, VERSION_PATCH=1}" since: 1.4.0 functions: - name: arrayCombine @@ -76,11 +76,39 @@ functions: echo(1, "abc") // выведет строку "1 abc" в консоль echo(1, 2, 3, 4, 5, "a", "b") // выведет строку "1 2 3 4 5 a b" в консоль" + - name: exit + args: status + desc: terminates an application with provided status code. Non-zero values indicates abnormal termination + desc_ru: завершает работу приложения с заданным кодом. Ненулевое значение означает завершение с ошибкой + since: 2.0.0 + example: |- + use std + + println "Bye!" + exit(0) + example_ru: |- + use std + + println "До свидания!" + exit(0) - name: getBytes args: input, charset = "UTF-8" desc: returns byte array of the string in the given charset desc_ru: возвращает массив байт строки в заданной кодировке since: 1.5.0 + - name: getenv + args: key, defaultValue = "" + desc: returns the value of the specified environment variable if it's exists, returns `defaultValue` otherwise + desc_ru: возвращает значение указанной переменной среды, если такова существует. В противном случае возвращает `defaultValue` + since: 2.0.0 + example: |- + use std + println getenv("JAVA_HOME") + - name: getprop + args: key, defaultValue = "" + desc: returns the value of the system property if it's exists, returns `defaultValue` otherwise + desc_ru: возвращает значение системного свойства, если оно существует. В противном случае возвращает `defaultValue` + since: 2.0.0 - name: indexOf args: "input, what, index = 0" desc: "finds first occurrence of `what` in string `input`, starting at position `index`" @@ -97,6 +125,11 @@ functions: args: "x" desc: "returns length of string, array/map size or number of function arguments" desc_ru: "возвращает длину строки, размер массива/объекта или количество аргументов функции в зависимости от типа аргумента x" + - name: nanotime + args: "" + desc: returns VM time source in nanoseconds for elapsed time purposes + desc_ru: возвращает время виртуальной машины в наносекундах, для отсчёта затраченного времени + since: 2.0.0 - name: newarray args: "size..." desc: "creates array with `size`.\n`newarray(x)` - creates 1D array, `newarray(x,y)` - creates 2D array" @@ -107,13 +140,18 @@ functions: println newarray(4) // [0, 0, 0, 0] println newarray(2, 3) // [[0, 0, 0], [0, 0, 0]] - name: parseInt - args: "str, radix" - desc: parses string into integer in the `radix` - desc_ru: парсит строку в целое число с указанным основанием + args: str, radix + desc: parses the input string into an integer with `radix` base + desc_ru: преобразует строку в целое число с указанным основанием - name: parseLong - args: "str, radix" - desc: parses string into long in the `radix` - desc_ru: парсит строку в длинное целое число с указанным основанием + args: str, radix + desc: parses the input string into a long integer with `radix` base + desc_ru: преобразует строку в длинное целое число с указанным основанием + - name: parseDouble + args: str + desc: parses the input string into a double + desc_ru: преобразует строку в вещественное число типа double + since: 2.0.0 - name: rand args: "from = 0, to = .." desc: |- diff --git a/ownlang-parser/src/test/resources/modules/functional/groupby.own b/ownlang-parser/src/test/resources/modules/functional/groupby.own index 49a3237..6330312 100644 --- a/ownlang-parser/src/test/resources/modules/functional/groupby.own +++ b/ownlang-parser/src/test/resources/modules/functional/groupby.own @@ -1,5 +1,17 @@ use std, functional +def testGroupByKeys() { + data = [ + {"k1": 1, "k2": "a"}, + {"k1": 2, "k2": "b"}, + {"k1": 3, "k2": "c"}, + ] + result = groupby(data, def(e) = e.k2) + assertEquals([{"k1": 1, "k2": "a"}], result.a) + assertEquals([{"k1": 2, "k2": "b"}], result.b) + assertEquals([{"k1": 3, "k2": "c"}], result.c) +} + def testArraysGroupBy() { arr = [1, 2, 3, 4, 1, 2, 3, 1, 2, 3] result = groupby(arr, def(v) = v % 2 == 0) @@ -13,3 +25,4 @@ def testMapsGroupBy() { assertEquals({"test1": 234, "test2": 345, "test3": 456}, result[true]) assertEquals({"abc": 123, "def": 567}, result[false]) } +