Add new functions documentation

Author: aNNiMON

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
-      
-      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
+      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:
-        - `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'
+    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: возвращает количество элементов

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: |-

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])
 }
+