Chapter 7 7. Libraries and Modules

7.1 Basic library

There are some functions and classes that can be used directly in the standard library. They provide basic services for Berry programs, so they are also called basic libraries. The functions and classes in the basic library are visible in the global scope (belonging to the built-in scope), so they can be used anywhere. Do not define variables with the same name as the functions or classes in the base library. Doing so will make it impossible to reference the functions and classes in the base library.

7.1.1 Built-in function

`print` function

Example

print(...)

Description

This function prints the input parameters to the standard output device. The function can accept any type and any number of parameters. All types will print their value directly, and for an instance, this function will check whether the instance has a tostring() method, and if there is, print the return value of the instance calling the tostring() method, otherwise it will print the address of the instance.

print('Hello World!') # Hello World!
print([1, 2, '3']) # [1, 2, '3']
print(print) # <function: 0x561092293780>

`input` function

Example

input()
input(prompt)

Description

input The function is used to input a line of character string from the standard input device. This function can use the prompt parameter as an input prompt, and the prompt parameter must be of string type. After calling the input function, characters will be read from the keyboard buffer until a newline character is encountered.

input('please enter a string:') # please enter a string:

input The function does not return until the “Enter” key is pressed, so the program "stuck" is not an error.

`type` function

Example

type(value)

value: Input parameter (expect to get its type).
return value: A string describing the parameter type.

Description

This function receives a parameter of any type and returns the type of the parameter. The return value is a string describing the type of the parameter. Table below shows the return values corresponding to the main parameter types:

Parameter Type	return value	Parameter Type	return value
Nil	`’nil’`	Integer	`’int’`
Real	`’real’`	Boolean	`’bool’`
Function	`’function’`	Class	`’class’`
String	`’string’`	Instance	`’instance’`
native pointer	`’ptr’`

type(0) #'int'
type(0.5) #'real'
type('hello') #'string'
type(print) #'function'

`classname` function

Example

classname(object)

Description

This function returns the class name (string) of the parameter. Therefore the parameter must be a class or instance, and other types of parameters will return nil.

classname(list) #'list'
classname(list()) #'list'
classname({}) #'map'
classname(0) # nil

`classof` function

Example

classof(object)

Description

Returns the class of an instance object. The parameter object must be an instance. If the function is successfully called, it will return the class to which the instance belongs, otherwise it will return nil.

classof(list) # nil
classof(list()) # <class: list>
classof({}) # <class: map>
classof(0) # nil

`str` function

Example

str(value)

Description

This function converts the parameters into strings and returns. str Functions can accept any type of parameters and convert them. When the parameter type is an instance, it will check whether the instance has a tostring() method, if there is, the return value of the method will be used, otherwise the address of the instance will be converted into a string.

str(0) # '0'
str(nil) #'nil'
str(list) #'list'
str([0, 1, 2]) #'[0, 1, 2]'

`number` function

number(value)

Description

This function converts the input string or number into a numeric type and returns. If the input parameter is an integer or real number, it returns directly. If it is a character string, try to convert the character string to a numeric value in decimal format. The integer or real number will be automatically judged during the conversion. Other types return nil.

Example

number(5) # 5
number('45.6') # 45.6
number('50') # 50
number(list) # nil

`int` function

int(value)

Description

This function converts the input string or number into an integer and returns it. If the input parameter is an integer, return directly, if it is a real number, discard the decimal part. If it is a string, try to convert the string to an integer in decimal. Other types return nil.

Example

int(5) # 5
int(45.6) # 45
int('50') # 50
int(list) # nil

`real` function

real(value)

Description

This function converts the input string or number into a real number and returns. If the input parameter is a real number, it will return directly, if it is an integer, it will be converted to a real number. If it is a string, try to convert the string to a real number in decimal. Other types return nil.

Example

real(5) # 5, type(real(5)) →'real'
real(45.6) # 45.6
real('50.5') # 50.5
real(list) # nil

`size` function

size(value)

Description

This function returns the size of the input string. If the input parameter is not a string, 0 is returned. The length of the string is calculated in bytes. This function also works for list and map instances and returns the number of elements.

Example

size(10) # 0
size('s') # 1
size('string') # 6
size([1,2]) # 2
size({"a":1}) # 1

`super` function

super(object)

Description

This function returns the parent object of the instance. When you instantiate a derived class, it will also instantiate its base class. The super function is required to access the instance of the base class (that is, the parent object).

Example

class mylist: list end
l = mylist() # classname(l) -->'mylist'
sl = super(l) # classname(sl) -->'list'

`assert` function

assert(expression)
assert(expression, message)

Description

This function is used to implement the assertion function. assert The function accepts a parameter. When the value of the parameter is false or nil, the function will trigger an assertion error, otherwise the function will not have any effect. It should be noted that even if the parameter is a value equivalent to false in logical operations (for example, 0), it will not trigger an assertion error. The parameter message is optional and must be a string. If this parameter is used, the text information given in message will be output when an assertion error occurs, otherwise the default “Assert Failed” message will be output.

Example

assert(false) # assert failed!
assert(nil) # assert failed!
assert() # assert failed!
assert(0) # assert failed!
assert(false,'user assert message.') # user assert message.
assert(true) # pass

`compile` function

compile(string)
compile(string, 'string')
compile(filename, 'file')

Description

This function compiles the Berry source code into a function. The source code can be a string or a text file. compile The first parameter of the function is a string, and the second parameter is a string ’string’ or ’file’. When the second parameter is ’string’ or there is no second parameter, the compile function will compile the first parameter as the source code. When the second parameter is ’file’, the compile function will compile the file corresponding to the first parameter. If the compilation is successful, compile will return the compiled function, otherwise it will return nil.

Example

compile('print(\'Hello World!\')')() # Hello World!
compile('test.be','file')

`list` Class

list is a built-in type, which is a sequential storage container that supports subscript reading and writing. list Similar to arrays in other programming languages. Obtaining an instance of the list class can be constructed using a pair of square brackets: [] will generate an empty list instance, and [expr, expr, ...] will generate a list instance with several elements. It can also be instantiated by calling the list class: executing list() will get an empty list instance, and list(expr, expr, ...) will return an instance with several elements.

`list` method (Constructor)

Initialize the list container. This method can accept 0 to multiple parameters. The list instance generated when multiple parameters are passed will have these parameters as elements, and the arrangement order of the elements is consistent with the arrangement order of the parameters.

`tostring` method

Serialize the list instance to a string and return it. For example, the result of executing [1, [], 1.5].tostring() is ’[1, [], 1.5]’. If the list container refers to itself, the corresponding position will use an ellipsis instead of the specific value:

l = [1, 2]
l[0] = l
print(l) # [[...], 2]

`push` method

Append an element to the end of the list container. The prototype of this method is push(value), the parameter value is the value to be appended, and the appended value is stored at the end of the list container. The append operation increases the number of elements in the list container by 1. You can append any type of value to the list instance.

`insert` method

Insert an element at the specified position of the list container. The prototype of this method is insert(index, value), the parameter index is the position to be inserted, and value is the value to be inserted. After inserting an element at the position index, all the elements that originally started from this position will move backward by one element. The insert operation increases the number of elements in the list container by 1. You can insert any type of value into the list container.

Suppose that the value of a list instance l is [0, 1, 2], and we insert a string ’string’ at position 1, and we need to call l.insert(1, ’string’). Finally, the new list value is [0, ’string’, 1, 2].

If the number of elements in a list container is S, the value range of the insertion position is {i ∈ ℤ : − S ≤ i < S}. When the insertion position is positive, index backward from the head of the list container, otherwise index forward from the end of the list container.

`remove` method

Remove an element from the container. The prototype of this method is remove(index), and the parameter index is the position of the element to be removed. After the element is removed, the element behind the removed element will move forward by one element, and the number of elements in the container will be reduced by 1. Like the insert method, the remove method can also use positive or negative indexes.

`item` method

Get an element in the list container. The prototype of this method is item(index), the parameter index is the index of the element to be obtained, and the return value of the method is the element at the index position. list The container supports multiple indexing methods:

Integer index: The index value can be a positive integer or a negative integer (the same as the index method in insert). At this time, the return value of item is the element at the index position. If the index position exceeds the number of elements in the container or is before the 0th element, the item method will return nil.
list Index: Using a list of integers as an index, item returns a list, and each element in the return value list is an element corresponding to each integer index in the parameter list. The value of the expression [3, 2, 1].item([0, 2]) is [3, 1]. If an element type in the parameter list is not an integer, then the value at that position in the return value list is nil.
range Index: Using an integer range as an index, item returns a list. The returned value stores the indexed elements from list from the lower limit to the upper limit of the parameter range. If the index exceeds the index range of the indexed list, the return value list will use nil to fill the position beyond the index.

`setitem` method

Set the value of the specified position in the container. The prototype of this method is setitem(index, value), index is the position of the element to be written, and value is the value to be written. index is the integer index value of the writing position. Index positions outside the index range of the container will cause setitem to fail to execute.

`size` method

Returns the number of elements in the container, which is the length of the container. The prototype of this method is size().

`resize` method

Reset list the length of the container. The prototype of this method is resize(count), and the parameter count is the new length of the container. When using resize to increase the length of the container, the new element will be initialized to nil. Using resize to reduce the length of the container will discard some elements at the end of the container. E.g:

l = [1, 2, 3]
l.resize(5) # Expansion, l == [1, 2, 3, nil, nil]
l.resize(2) # Reduce, l == [1, 2]

`iter` method

Returns an iterator for traversing the current list container.

`find` method

Similar to item or list[idx]. The only difference is if the index is out of range, find return nil instead or raising an exception.

`reverse` method

Changes the list in-place and reverses the order of elements. Also returns the resulting list.

`map` Class

map Class is a built-in class type used to provide an unordered container of key-value pairs. Inside the Berry interpreter, map uses the Hash table to implement. You can use curly brace pairs to construct a map container. Using an empty curly brace pair {} will generate an empty map instance. If you need to construct a non-empty map instance, use a colon to separate the key and value, and use a semicolon to separate multiple key-value pairs. For example, {0: 1, 2: 3} has two key-value pairs (0,1) and (2,3). You can also get an empty map instance by calling the map class.

`map` method (Constructor)

Initialize the map container, this method does not accept parameters. Executing map() will get an empty map instance.

`tostring` method

Serialize map as a string and return. The serialized string is similar to literal writing. For example, the result of executing ’str’: 1, 0: 2 is "’str’: 1, 0: 2". If the map container refers to itself, the corresponding position will use an ellipsis instead of the specific value:

m = {'map': nil,'text':'hello'}
m['map'] = m
print(m) # {'text':'hello','map': {...}}

`insert` method

Insert a key-value pair in the map container. The prototype of this method is insert(key, value), the parameter key is the key to be inserted, and value is the value to be inserted. If the key map to be inserted exists in the container, the original key-value pair will be updated.

`remove` method

Remove a key-value pair from the map container. The prototype of this method is remove(key), and the parameter key is the key of the key-value pair to be deleted.

`item` method

Get a value in the map container. The prototype of this method is item(key), the parameter key is the key of the value to be obtained, and the return value of the method is the value corresponding to the key.

`setitem` method

Set the value corresponding to the specified key in the container. The prototype of this method is setitem(key, value), key is the key of the key-value pair to be written, and value is the value to be written. If there is no key-value pair with the key key in the container, the setitem method will fail.

`size` method

Return the number of key-value pairs of the map container, which is the length of the container. The prototype of this method is size().

`contains` method

Returns boolean true if a matching key-value pair is found in the map container, otherwise false. The prototype of this method is contains(key).

`find` method

Returns the value corresponding to the specified key in the container. The prototype of this method is find(key) or find(key, defaultvalue), key is the key of the key-value pair to be accessed, and defaultvalue is the default value returned if the key is not found. If no default value is specified, nil is returned instead.

`range` Class

range The class is used to represent an integer closed interval. Use the binary operator .. to construct an instance of range. The left and right operands of the operator are required to be integers. For example, 0..10 means the integer interval [0,10] ∩ ℤ.

There are typically two ways to traverse a list:

l = [1,2,3,4]
for e:l print(e) end # 1/2/3/4
for i:0..size(l)-1 print(l[i]) end # 1/2/3/4

`bytes` Class

bytes object are represented as arrays of Hex bytes. bytes constructor takes a string of Hex and builds the in-memory buffer.

Example:

b = bytes()
print(b)   # bytes('')
b = bytes("1155AA")  # sequence of bytes 0x11 0x55 0xAA
size(b)  # 3 = 3 bytes
b[0]     # 17 (0x11)
b[0] = 16  # assign first byte
print(b)   # bytes('1055AA')

`bytes` method (Constructor)

Initialize a bytes array. There are several options.

Option 1: empty value

bytes() creates a new empty bytes array. size(bytes()) == 0.

There is no limit in the size of a bytes array, except the available memory. An internal buffer is allocated and reallocated in case the previous one was too small. The initial buffer is 36 bytes, but you can pre-allocated a larger (or smaller) buffer if you know in advance the size needed.

Similarly the buffer is automatically shrunk if it is used less than its needed size.

b = bytes(4096)   # pre-allocated 4096 bytes

Option 2: initial value

If first argument is a string it is parsed as a list of Hex values. You can add an optional second argument to pre-allocate a bigger buffer.

b = bytes("BEEF0000")
print(b)   # bytes('beef0000')
b = bytes("112233", 128)   # pre-allocate 128 bytes internally
print(b)   # bytes('112233')

Option 3: fixed size

If the size provided is negative, the array size is fixed and cannot be lowered nor raised.

b = bytes(-8)
print(b)   # bytes('0000000000000000')

b = bytes("AA", -4)
print(b)   # bytes('AA000000')

b = bytes("1122334455", -4)
attribute_error: bytes object size if fixed and cannot be resized

Option 3: memory mapping

Caution, use with great care

In this mode, the bytes array is mapped to a specific region in memory. You must provide the base address as comptr and the size. Size is always fixed whether it is positive or negative. This feature is dangerous since you can access any memory location, causing a crash if the location is protected or invalid. Use with care.

Example:

import introspect
def f() return 0 end

addr = introspect.toptr(f)
print(addr)   # <ptr: 0x3ffeaf88>

b = bytes(addr, 8)
print(b)   # bytes('F8EAFE3F24000000')
# this example shows the first 8 bytes of the function object in memory

`size` method

Returns the number of bytes in the bytes array

b = bytes("1122334455")
b.size()   # 5
size(b)    # 5

`tostring` method

Shows a human readable form of the bytes array in hex. By default, it shows only the first 32 characters. You can request more characters by adding an int argument with the maximum number of bytes you want to convert. tostring is internally used when you print an object. print(b) is equivalent to print(b.tostring()). It is different from asstring which turns a bytes array to the equivalent low-level string object without any encoding.

b = bytes("1122334455")
b.tostring()   # 'bytes(\'1122334455\')'

b = bytes()
b.resize(64)   # resize to 64 bytes
b.tostring()   # 'bytes(\'0000000000000000000000000000000000000000000000000000000000000000...\')'
b.tostring(500) # 'bytes(\'00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\')'

`clear` method

Sets back the bytes array to empty

b = bytes("1122")
b.clear()
print(b)   # bytes()

`resize` method

Shrink or expand the bytes array to match the specified size. If expanded, NULL (0x00) bytes are added at the end of the buffer.

b = bytes("11223344")
b.resize(6)
print(b)   # bytes('112233440000')
b.resize(2)
print(b)   # bytes('1122')

Concatenation `+` and `..` methods

You can use + to concatenate two bytes list, creating a new bytes object. .. changes the list in place and can be used to add an int (1 bytes) or a bytes object

b = bytes("1122")
c = bytes("3344")
d = b + c           # b and c are unchanged
print(d)            # bytes('11223344')
print(b)            # bytes('1122')
print(c)            # bytes('3344')

e = b..c            # now b is changed
print(e)            # bytes('11223344')
print(b)            # bytes('11223344')
print(c)            # bytes('3344')

bytes access `[]` method

You can access individual bytes as integers, to read and write. Values not in the range 0..255 are silently choped.

b = bytes("010203")
print(b[0])         # 1

# negative indices count from the end
print(b[-1])        # 3

# out of bounds generate an exception
print(b[5])         # index_error: bytes index out of range

b[0] = -1
print(b)            # bytes('FF0203')

b[1] = 256
print(b)            # bytes('FF0003')

range access `[]` method

You can use the [] accessor with a range to get an sub-list of bytes. If an index is negative, it is taken from the end of the array.

This construct cannot be used a an lvalue, i.e. you can't splice like b[1..2] = bytes("0011") # not allowed.

b = bytes("001122334455")
print(b[1..2])      # bytes('1122')

# remove first 2 bytes
print(b[2..-1])     # bytes('22334455')

# remove last 2 bytes
print(b[0..-3])     # bytes('00112233')

# overshooting is allowed
print(b[4..10])     # bytes('4455')

# inversed indices return an empty array
print(b[5..4])      # bytes('')

The standard item and setitem methods are implemented, and transparently mapped to [] operator.

`copy` method

Creates a fresh new copy of the bytes object. A new memory buffer is allocated and data is duplicated.

b = bytes("1122")
print(b)          # bytes('1122')

c = b.copy()
print(c)          # bytes('1122')

b.clear()
print(b)          # bytes('')
print(c)          # bytes('1122')bytes('1122')

`get, geti` methods

Read a 1/2/4 bytes value from any offset in the bytes array. The standard mode is little endian, if you specify a negative size it enables big endian. get returns unsigned values, while geti returns signed values.

b.get(<offset>, <size>) -> bytes object

If the offset is out of range, 0 is returned (no exception raised).

Example:

b = bytes("010203040506")
print(b.get(2,2))         # 1027 - 0x0403 read 2 bytes little endian
print(b.get(2,-2))        #  772 - 0x0304 read 2 bytes big endian

print(b.get(2,4))         # 100992003 - 0x06050403 - little endian
print(b.get(2,-4))        #  50595078 - 0x03040506 - big endian

b = bytes("FEFF")
print(b.get(0, 2))        # 65534 - 0xFFFE
print(b.geti(0, 2))       # -2 - 0xFFFE

`set, seti` methods

Similar to get and geti, allows to set a 1/2/4 bytes value at any offset. seti uses signed integers, set unsigned (actually it does not make a difference).

If the offset is out of range, no change is done (no exception raised).

bytes.set(<offset>, <value>, <size>)

`add` method

This methods adds value of 1/2/4 bytes (little endian or big endian) at the end of the buffer. If size is negative, the value is treated as big endian.

b.add(<value>, <size>)

Example:

b = bytes("0011")
b.add(0x22, 1)
print(b)             # bytes('001122')
b.add(0x2233, 2)
print(b)             # bytes('0011223322')
b.add(0x22334455, 4)
print(b)             # bytes('001122332255443322')
b.add(0x00)
print(b)             # bytes('00112233225544332200')
b.clear()
b.add(0x0102, -2)
print(b)             # bytes('0102')
b.add(0x01020304, -4)
print(b)             # bytes('010201020304')

`asstring` method

Converts a bytes buffer to a string. The buffer is converted as-is without any encoding considerations. If the buffer contains NULL characters, the string will be truncated.

b=bytes("3344")
print(b.asstring())   # '3D'

`fromstring` method

Converts a bytes buffer to a string. The buffer is converted as-is without any encoding considerations. If the buffer contains NULL characters, the string will be truncated.

b=bytes().fromstring("Hello")
print(b)              # bytes('48656C6C6F')

bits manipulation `setbits, getbits` methods

You can read and write at sub-byte level, specifying from which bit to which bit. The offset is in bits, not bytes. Add the number of bytes * 8.

b.setbits(<offset_bits>, <len_bits>, <value>)
b.getbits(<offset_bits>, <len_bits>)

base64 encode `tob64` method

Converts a bytes array to a base64 string.

b = bytes('deadbeef0011')
s = b.tob64()
print(s)               # 3q2+7wAR

base64 decode `fromb64` method

Converts a base64 string into a bytes array.

s = '3q2+7wAR'
b = bytes().fromb64(s)
print(b)               # bytes('DEADBEEF0011')

Expansion Modules

JSON Module

JSON is a lightweight data exchange format. It is a subset of JavaScript. It uses a text format that is completely independent of the programming language to represent data. Berry provides a JSON module to provide support for JSON data. The JSON module only contains two functions load and dump, which are used to parse JSON strings and multiply Berry objects and serialize a Berry object into JSON text.

`load` function

load(text)

Description

This function is used to convert the input JSON text into a Berry object and return it. The conversion rules are shown in Table 1.1. If there is a syntax error in the JSON text, the function will return nil.

JSON type	Berry type
`null`	`nil`
`number`	`integer` or `real`
`string`	`string`
`array`	`list`
`object`	`map`

JSON type to Berry type conversion rules

Example

import json
json.load('0') # 0
json.load('[{"name": "liu", "age": 13}, 10.0]') # [{'name':'liu','age': 13}, 10]

`dump` function

dump(object, ['format'])

Description

This function is used to serialize the Berry object into JSON text. The conversion rules for serialization are shown in Table 1.2.

Berry type	JSON type
`nil`	`null`
`integer`	`number`
`real`	`number`
`list`	`array`
`map`	`object`
`map`Key of	`string`
other	`string`

Berry type to JSON type conversion rules

Example

import json
json.dump('string') #'"string"'
json.dump('string') #'"string"'
json.dump({0:'item 0','list': [0, 1, 2]}) #'{"0":"item 0","list":[0,1,2]}'
json.dump({0:'item 0','list': [0, 1, 2],'func': print},'format')
#-
{
    "0": "item 0",
    "list": [
        0,
        1,
        2
    ],
    "func": "<function: 00410310>"
}
-#

Math Module

This module is used to provide support for mathematical functions, such as commonly used trigonometric functions and square root functions. To use the math module, first use the import math statement to import. All examples in this section assume that the module has been imported correctly.

`pi` constant

The approximate value of Pi π, a real number type, approximately equal to 3.141592654.

Example

math.pi # 3.14159

`abs` function

abs(value)

Description

This function returns the absolute value of the parameter, which can be an integer or a real number. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. abs The return type of the function is a real number.

Example

math.abs(-1) # 1
math.abs(1.5) # 1.5

`ceil` function

ceil(value)

Description

This function returns the rounded up value of the parameter, that is, the smallest integer value greater than or equal to the parameter. The parameter can be an integer or a real number. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. ceil The return type of the function is a real number.

Example

math.ceil(-1.2) # -1
math.ceil(1.5) # 2

`floor` function

floor(value)

Description

This function returns the rounded down value of the parameter, which is not greater than the maximum integer value of the parameter. The parameter can be an integer or a real number. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. floor The return type of the function is a real number.

Example

math.floor(-1.2) # -2
math.floor(1.5) # 1

`sin` function

sin(value)

Description

This function returns the sine function value of the parameter. The parameter can be an integer or a real number, and the unit is radians. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. sin The return type of the function is a real number.

Example

math.sin(1) # 0.841471
math.sin(math.pi * 0.5) # 1

`cos` function

cos(value)

Description

This function returns the value of the cosine function of the parameter. The parameter can be an integer or a real number in radians. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. cos The return type of the function is a real number.

Example

math.cos(1) # 0.540302
math.cos(math.pi) # -1

`tan` function

tan(value)

Description

This function returns the value of the tangent function of the parameter. The parameter can be an integer or a real number, in radians. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. tan The return type of the function is a real number.

Example

math.tan(1) # 1.55741
math.tan(math.pi / 4) # 1

`asin` function

asin(value)

Description

This function returns the arc sine function value of the parameter. The parameter can be an integer or a real number. The value range is [−1,1]. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. asin The return type of the function is a real number and the unit is radians.

Example

math.asin(1) # 1.5708
math.asin(0.5) * 180 / math.pi # 30

`acos` function

acos(value)

Description

This function returns the arc cosine function value of the parameter. The parameter can be an integer or a real number. The value range is [−1,1]. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. acos The return type of the function is a real number and the unit is radians.

Example

math.acos(1) # 0
math.acos(0) # 1.5708

`atan` function

atan(value)

Description

This function returns the arctangent function value of the parameter. The parameter can be an integer or a real number. The value range is [−∞,+∞]. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. atan The return type of the function is a real number and the unit is radians.

Example

math.atan(1) * 180 / math.pi # 45

`sinh` function

sinh(value)

Description

This function returns the hyperbolic sine function value of the parameter. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. sinh The return type of the function is a real number.

Example

math.sinh(1) # 1.1752

`cosh` function

cosh(value)

Description

This function returns the hyperbolic cosine function value of the parameter. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. cosh The return type of the function is a real number.

Example

math.cosh(1) # 1.54308

`tanh` function

tanh(value)

Description

This function returns the hyperbolic tangent function value of the parameter. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. tanh The return type of the function is a real number.

Example

math.tanh(1) # 0.761594

`sqrt` function

sqrt(value)

Description

This function returns the square root of the argument. The parameter of this function cannot be negative. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. sqrt The return type of the function is a real number.

Example

math.sqrt(2) # 1.41421

`exp` function

exp(value)

Description

This function returns the value of the parameter’s exponential function based on the natural constant e. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. exp The return type of the function is a real number.

Example

math.exp(1) # 2.71828

`log` function

log(value)

Description

This function returns the natural logarithm of the argument. The parameter must be a positive number. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. log The return type of the function is a real number.

Example

math.log(2.718282) # 1

`log10` function

log10(value)

Description

This function returns the logarithm of the parameter to the base 10. The parameter must be a positive number. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. log10 The return type of the function is a real number.

Example

math.log10(10) # 1

`deg` function

deg(value)

Description

This function is used to convert radians to angles. The unit of the parameter is radians. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. deg The return type of the function is a real number and the unit is an angle.

Example

math.deg(math.pi) # 180

`rad` function

rad(value)

Description

This function is used to convert angles to radians. The unit of the parameter is angle. If there are no parameters, the function returns 0, if there are multiple parameters, only the first parameter is processed. rad The return type of the function is a real number and the unit is radians.

Example

math.rad(180) # 3.14159

`pow` function

pow(x, y)

Description

The return value of this function is the result of the expression x^y, which is the parameter x to the y power. If the parameters are not complete, the function returns 0, if there are extra parameters, only the first two parameters are processed. pow The return type of the function is a real number.

Example

math.pow(2, 3) # 8

`srand` function

srand(value)

Description

This function is used to set the seed of the random number generator. The type of the parameter should be an integer.

Example

math.srand(2)

`rand` function

rand()

Description

This function is used to get a random integer.

Example

math.rand()

Time Module

This module is used to provide time-related functions.

`time` function

time()

Description

Returns the current timestamp. The timestamp is the time elapsed since Unix Epoch (1st January 1970 00:00:00 UTC), in seconds.

`dump` function

dump(ts)

Description

The input timestamp ts is converted into a time map, and the key-value correspondence is shown in Table below:

key	value	key	value	key	value
`’year’`	Year (from 1900)	`’month’`	Month (1-12)	`’day’`	Day (1-31)
`’hour’`	Hour (0-23)	`’min’`	Points (0-59)	`’sec’`	Seconds (0-59)
`’weekday’`	Week (1-7)

time.dump The key-value relationship of the function return value

`clock` function

clock()

Description

This function returns the elapsed time from the start of execution of the interpreter to when the function is called in seconds. The return value of this function is of type real, and its timing accuracy is determined by the specific platform.

String Module

The String module provides string processing functions.

To use the string module, first use the import string statement to import. All examples in this section assume that the module has been imported correctly.

`count` function

string.count(s, sub[, begin[, end]])

Count the number of occurrences of the sub string in the string s. Search from the position between begin and end of s (default is 0 and size(s)).

`split` function

string.split(s, pos)

Split the string s into two substrings at position pos, and returns the list of those strings.

string.split(s, sep[, num])

Splits the string s into substrings wherever sep occurs, and returns the list of those strings. Split at most num times (default is string.count(s, sep)).

`find` function

string.find(s, sub[, begin[, end]])

Check whether the string s contains the substring sub. If the begin and end (default is 0 and size(s)) are specified, they will be searched in this range.

`hex` function

hex(number)

Convert number to hexadecimal string.

`byte` function

byte(s)

Get the code value of the first byte of the string s.

`char` function

char(number)

Convert the number used as the code to a character.

`format` function

string.format(fmt[, args])

Returns a formatted string. The pattern starting with '%' in the formatting template fmt will be replaced by the value of [args]: %[flags][fieldwidth][.precision]type

Type	Description
%d	Decimal integer
%o	Octal integer
%x	Hexadecimal integer lowercase
%X	Hexadecimal integer uppercase
%x	Octal integer lowercase
%X	Octal integer uppercase
%f	Floating-point in the form [-]nnnn.nnnn
%e %E	Floating-point in exp. form [-]n.nnnn e [+\|-]nnn, uppercase if %E
%g %G	Floating-point as %f if −4 < exp. ≤ precision, else as %e; uppercase if %G
%c	Character having the code passed as integer
%s	String with no embedded zeros
%q	String between double quotes, with special characters escaped
%%	The '%' character (escaped)

Type	Description
-	Left-justifies, default is right-justify
+	Prepends sign (applies to numbers)
(space)	Prepends sign if negative, else space
#	Adds "0x" before %x, force decimal point; for %e, %f, leaves trailing zeros for %g

Field width and precision	Description
n	Puts at least n characters, pad with blanks
0n	Puts at least n characters, left-pad with zeros
.n	Use at least n digits for integers, rounds to n decimals for floating-point or no more than n chars. for strings

Module `os`

The OS module provides system-related functions, such as file and path-related functions. These functions are platform-related. Currently, Windows VC and POSIX style codes are implemented in the Berry interpreter. If it runs on other platforms, the functions in the OS module are not guaranteed to be provided.

TODO

Module `global`

Module global provides a way to access global variables via a module. The Berry compiler checks that a global exists when compiling code. However there are cases when globals are created dynamically by code and are not yet known at compile time. Using the module global gives complete freedom to access statically or dynamically global variables.

Accessing a global is simplay made with global.<name> for reading and writing. You can also use the special syntax global.(name) if name is a variable containing the name of the global as string.

Example:

> import global
> a = 1
> global.a
1
>
> b
syntax_error: stdin:1: 'b' undeclared (first use in this function)
> global.b = 2
> b
2
> global.b
2
> var name = "b"
> global.(name)
2

Calling global() returns the list of all global names currently defined (builtins are not included).

> import global
> a = 1
> global.b = 2
> global()
['_argv', 'b', 'global', 'a']

global.contains(<name)> -> bool provides an easy way to know if a global name is already defined.

> import global
> global.contains("g")
false
> g = 1
> global.contains("g")
true

Module `introspect`

Module introspect provides primitives to dynamically access variables or modules. Use with import introspect.

introspect.members(object: class or module or instance or nil) -> list returns the list of names of members for the class, instance or module. Keep in mind that it does not include potential virtual members created via member and setmember.

introspect.members() returns the list of global variables (not including builtins) and is equivalent to global()

introspect.get(object: class or instance or module, name:string) -> any and introspect.set(object: class or instance or module, name:string, value:any) -> nil allows to read and write any member by name.

introspect.get(o, "a") is equivalent ot o.a, introspect.set(o, "a", 1) is equivalent to o.a = 1. There is also an alternative syntax: o.("a") is equivalent to o.a and o.("a) = 1 is equivalent to o.a = 1.

introspect.module(name:string) -> any is equivalent to import name except that it does not create the global or local variable, but returns the module. This is the only way to load a module with a dynamic name, import name only takes a static name.

introspect.toptr(addr:int) -> comptr converts an integer to a comptr pointer. introspect.fromptr(addr:comptr) -> int does the reverse and converts a pointer to an int. Warning: use with care. On platforms where int and void* don't have the same size, these functions will most certainly give unusable results.

introspect.ismethod(f:function) -> bool checks if the provided function is a method of an instance (taking self as first argument), or a plain function. This is mainly use to prevent a common mistake of passing an instance method as callbakc, where you should use a closure capturing the instance like / -> self.do().

Module `solidify`

This module allows to solidify Berry bytecode into flash. This allows to save RAM since the code is in Flash, makes it a good alternative to native C functions.

See 8.4 Solidification

Chapter 7

7. Libraries and Modules

7.1 Basic library

7.1.1 Built-in function

print function

input function

type function

classname function

classof function

str function

number function

int function

real function

size function

super function

assert function

compile function

list Class

list method (Constructor)

tostring method

push method

insert method

remove method

item method

setitem method

size method

resize method

iter method

find method

reverse method

map Class

map method (Constructor)

tostring method

insert method

remove method

item method

setitem method

size method

contains method

find method

range Class

bytes Class

bytes method (Constructor)

size method

tostring method

clear method

resize method

Concatenation + and .. methods

bytes access [] method

range access [] method

copy method

get, geti methods

set, seti methods

add method

asstring method

fromstring method

bits manipulation setbits, getbits methods

base64 encode tob64 method

base64 decode fromb64 method

Expansion Modules

JSON Module

load function

dump function

Math Module

pi constant

abs function

ceil function

floor function

sin function

cos function

tan function

asin function

acos function

atan function

sinh function

cosh function

tanh function

sqrt function

exp function

log function

`print` function

`input` function

`type` function

`classname` function

`classof` function

`str` function

`number` function

`int` function

`real` function

`size` function

`super` function

`assert` function

`compile` function

`list` Class

`list` method (Constructor)

`tostring` method

`push` method

`insert` method

`remove` method

`item` method

`setitem` method

`size` method

`resize` method

`iter` method

`find` method

`reverse` method

`map` Class

`map` method (Constructor)

`tostring` method

`insert` method

`remove` method

`item` method

`setitem` method

`size` method

`contains` method

`find` method

`range` Class

`bytes` Class

`bytes` method (Constructor)

`size` method

`tostring` method

`clear` method

`resize` method

Concatenation `+` and `..` methods

bytes access `[]` method

range access `[]` method

`copy` method

`get, geti` methods

`set, seti` methods

`add` method

`asstring` method

`fromstring` method

bits manipulation `setbits, getbits` methods

base64 encode `tob64` method

base64 decode `fromb64` method

`load` function

`dump` function

`pi` constant

`abs` function

`ceil` function

`floor` function

`sin` function

`cos` function

`tan` function

`asin` function

`acos` function

`atan` function

`sinh` function

`cosh` function

`tanh` function

`sqrt` function

`exp` function

`log` function

`log10` function

`deg` function

`rad` function

`pow` function

`srand` function

`rand` function

`time` function