documentation.md

Ape Documentation

APE IS UNDER ACTIVE DEVELOPMENT SO EVERYTHING HERE CAN BE WRONG OR OUT OF DATE.
IF IN DOUBT, CHECK THE SOURCE CODE.

Table of Contents

1. Error handling
2. Builtins

1. Error handling

During program execution runtime errors can occur (for instance if wrong number of arguments is passed to a function). They can be handled with recover statement that works similar to catch statement in other languages with few important differences:

• It needs to be declard before a runtime error it handles might occur
• It cannot be nested
• It's only valid within functions and must end with a return statement

For instance, let's say there's a function foo() that calls bar() and then baz().

fn foo() {
    recover (e) { // e is a runtime error wrapped in error
        println(e)
        return 0
    }
    bar() // if it fails foo() will return 0

    recover (e) {
        println(e)
        return 1
    }
    baz() // if it fails foo() will return 1

    return 2
}

Runtime crashes can be caused by calling crash("msg") function, however, if it's something expected that can be handled by caller, it's better to return an error value.

const err = error("something bad happened")
if (is_error(err)) {
    println(err)
}

2. Builtins

len(string | array | map) -> number

  var aStr = "a string"
  var aArr = [1, 2, 3]
  var aMap = { "1": 1, "2": 2 }

  len(aStr) // 8
  len(aArr) // 3
  len(aMap) // 2

first(array) -> object

  var aArr = [1, 2, 3]

  first(aArr) // 1

last(array) -> object

  var aArr = [1, 2, 3]

  last(aArr) // 3

rest(array) -> array

  var aArr = [1, 2, 3, 4, 5, 6, 7]
  var bArr = []

  rest(aArr) // [2, 3, 4, 5, 6, 7]
  rest(bArr) // null

reverse(array | string) -> array | string

  var aArr = [1, 2, 3]
  var aStr = "abc"

  reverse(aArr) // [3, 2, 1]
  reverse(aStr) // "cba"

array(number) -> array
array(number, object) -> array

  var aArr = array(3) // [null, null, null]
  var bArr = array(3, "a") // ["a", "a", "a"]
  var cArr = array(3, {}) // [{}, {}, {}]

append(array, object) -> number

  var aArr = [1]

  append(aArr, 1) // 2
  append(aArr, "a") // 3

println(object, ...) -> null

  var aMap = { "a": 1, "b": 2 }

  // appends newline
  println("a") // "a"
  println(aMap) // { "a": 1, "b": 2 }

print(object, ...) -> null

  var aMap = { "a": 1, "b": 2 }

  println("a") // "a"
  println(aMap) // { "a": 1, "b": 2 }

write_file(string, string) -> number

  var path = "./ex.txt"
  var data = "A string in a text file"

  write_file(path, data) // 22

read_file(string) -> string

  var path = "./ex.txt"

  read_file(path) // "A string in a text file"

to_str(string | number | bool | null | map | array) -> string

  var aVal = true

  to_str(aVal) // "true"

char_to_str(number) -> string

  char_to_str('a') // "a"

range(number) -> array
range(number, number) -> array
range(number, number, number) -> array

  var aStart = 2
  var aEnd = 10
  var aStep = 2

  range(aEnd) // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
  range(aStart, aEnd) // [2, 3, 4, 5, 6, 7, 8, 9]
  range(aStart, aEnd, aStep) // [2, 4, 6, 8]

keys(map) -> array

  var aMap = { "a": 1, "b": 2 }

  keys(aMap) // ["a", "b"]

values(map) -> array

  var aMap = { "a": 1, "b": 2 }

  values(aMap) // [1, 2]

copy(object) -> object

  var aMap = { "a": 1, "b": 2 }
  var bMap = null

  bMap = copy(aMap) // { "a": 1, "b": 2 }

deep_copy(object) -> object

  var aMap = { "a": 1, "b": 2, "c": { "a": 1, "b": 2, "c": { "a": 1 } } }
  var bMap = null

  bMap = deep_copy(aMap) // { "a": 1, "b": 2, "c": { "a": 1, "b": 2, "c": { "a": 1 } } }

concat(array | string, object) -> number | string

  var aArr = [1, 2]
  var aStr = "ab"
  var bStr = ""

  concat(aArr, [3]) // aArr [1, 2, [3]] -> 3
  concat(aArr, "c") // type error!

  bStr = concat(aStr, "c") // "abc"
  // aStr == "ab"

assert(bool) -> bool

  assert((1 == 1)) // true
  assert(1 == 2)) // false

  assert((1+2)) // error!

remove(array, object) -> bool

  var aArr = [1, 2, 3, true]

  remove(aArr, 3) // true
  remove(aArr, 3) // false

remove_at(array, number) -> bool

  var aArr = [1, 2, 3, true]

  remove_at(aArr, 2) // true
  remove_at(aArr, 2) // true

error(string | null) -> error

  error("an error")
  error()

random(number, number) -> number

  random(1, 5)
  random(10, 2) // error!

Type Checks

---

is_string(object) -> bool

is_array(object) -> bool

is_map(object) -> bool

is_number(obejct) -> bool

is_bool(object) -> bool

is_null(object) -> bool

is_function(object) -> bool

is_external(object) -> bool

is_error(object) -> bool

Math

---

sqrt(number) -> number

pow(number, number) -> number

  pow(2, 2) // 4

sin(number) -> number

cos(number) -> number

tan(number) -> number

log(number) -> number

ceil(number) -> number

floor(number) -> number

abs(number) -> number