Asp Scripting Platform

Asp Library Reference

Introduction

This document provides details about various libraries that are available for systems using Asp. The libraries are all gathered into a single repository for distribution. However, availability of specific libraries in a given application is at the discretion of the application developer.

Portions of some of the libraries are implemented as Asp modules. These are typically installed in the asp‑lib directory underneath a standard location for include files, e.g., /usr/include/asp‑lib or similar on Linux systems. This directory must be included in the ASP_INCLUDE environment variable so that aspc will find the modules when they are imported.

A note to application developers

When incorporating script-callable functions into an application, the developer has choices for how the functions will be made available to scripts. By using include in the application specification file (*.asps), the functions appear in the sys module and can be called by either specifying its name alone or preceding the name with sys.. If import is used instead, the functions appear in the specified module, the name of which is either the base name of the spec file or the as name). In this case, the module name must be used to access the function.

When incorporating the libraries described in this document into applications, it is highly recommended that developers import them. Doing so will provide a common experience to script writers moving between applications.

The libraries

The following sections cover each library and are presented in alphabetical order by library name. Examples assume that the library has been made available as a module by the given name, requiring an import statement to use the functions in a script. Consult application documentation for any variations on this assumption.

`codec`

The codec library defines functions for encoding and decoding values to/from strings containing their binary equivalent. This functionality is useful for exchanging data with other systems, whether that is via files, communication links, or other means.

When encoding and decoding to/from binary representations of numeric values, the order of the bytes is important. As such, there are big-endian and little-endian versions of the functions that handle the conversions between numeric values and multi-byte strings. For integer values, there is also a distinction between signed and unsigned values in order to facilitate range checking. The list of available functions is as follows.

Endian	Signed	Unsigned	N/A
Big	`encode_i16be(x)` `decode_i16be(s)`	`encode_u16be(x)` `decode_u16be(s)`	`encode_f32be(x)` `decode_f32be(s)`
Big	`encode_i32be(x)` `decode_i32be(s)`	`encode_u16be(x)` `decode_u16be(s)`	`encode_f64be(x)` `decode_f64be(s)`
Little	`encode_i16le(x)` `decode_i16le(s)`	`encode_u16le(x)` `decode_u16le(s)`	`encode_f32le(x)` `decode_f32le(s)`
Little	`encode_i32le(x)` `decode_i32le(s)`	`encode_u16le(x)` `decode_u16le(s)`	`encode_f64le(x)` `decode_f64le(s)`
N/A	`encode_i8(x)` `decode_i8(s)`	`encode_u8(x)` `decode_u8(s)`	`encode_str(s, len, fill='\0')` `decode_str(s)`

The functions that encode integer values (encode_i… and encode_u…) perform range checking on the given values, ending the script with an error if the value is out of range. Therefore, it is highly recommended that scripts ensure integer values are in their valid ranges prior to calling an encode_… function. Note that since Asp does not directly support unsigned 32‑bit integers, there are no encode/decode functions for this type, and the signed 32‑bit integer versions need not perform any range checking. Likewise, functions that handle floating-point values (encode_f…) perform no range checking either.

Decode functions all require a string argument of the applicable size: 1 byte for decode_…8…, 2 bytes for decode_…16…, etc., causing the script to end in error if a field of unexpected type or length is given.

To round out the library, support for encoding arbitrary-length strings into fixed-length fields is also provided. When encoding, if the source string is longer than the field (denoted by the len parameter), truncation occurs. If the source string is shorter than the field, the remainder of the field is filled with the specified fill character, which must be a single-byte string. When decoding a string field, the resulting string will be the same length as the field unless the field contains a null character ('\0'), in which case characters are extracted up to but not including the null.

`crc`

The crc library provides generic functions for computing a Cyclic Redundancy Code (CRC) for a given string of bytes using a specified algorithm. Like the codec library, the crc library can be used for communication with other systems, especially in cases where the communication is unreliable or should be checked for integrity.

CRC algorithms are specified via a set of six parameters: width (in bits^*), polynominal specification (an integer value, usually expressed in hexadecimal), initial value, pre- and post-reflection indicators (Booleans), and an integer value to exclusive-OR with before producing the final result. Documentation of a CRC tool, and CRC algorithms in general, can be found at https://reveng.sourceforge.io, including a catalogue of commonly used algorithms.

Before generating a CRC value from a string, a CRC specification must be created using the make_spec function, which takes six arguments (as described above), and returns an opaque object to be used in subsequent calls to other functions. As of this writing, the returned object is a tuple of values, but this representation should not be relied upon, as it is subject to change in future versions. Here is an example of creating a spec for the CRC used by the XMODEM protocol.

import crc
xmodem_spec = crc.make_spec(16, 0x1021, 0, False, False, 0)

Once a specification object is created, the CRC of a string can be computed easily using the calc function, which accepts the spec and a string, s, as arguments, and returns the CRC value as an integer. If the CRC value needs to be included in a message for communicating with another system, it must be encoded, with, for example, one of the encoding functions available in the codec library.

text = '123456789'
crc_value = crc.calc(xmodem_spec, text)

In the above example, crc_value would be assigned the 16‑bit CRC value of 0x31C3.

Often, the message for which a CRC value is sought is broken up into different parts. If this is the case, three routines are available for computing a CRC piecemeal: start, add, and finish. The start function takes a spec (as returned by make_spec) and returns another opaque object representing a calculation session, which is passed to the add and finish functions. The add function takes both the spec and the session as arguments, plus a string, s, to contribute to the computation. It may be called multiple times to incorporate all the fragments of the message, but the fragments must be added in the order in which they appear in the overall message. When all the message's content has been added to the session, the final CRC value can be computed by passing both the spec and session to the finish function and using the returned integer value as described above for the calc function. The following example defines a function that accepts two portions of a message (header and body) and returns the common CRC32/ISO-HDLC value. Note that computing the CRC piecemeal avoids the need to append all the pieces together.

import crc
hdlc_spec = crc.make_spec \
    (32, 0x04C11DB7, 0xFFFFFFFF, True, True, 0xFFFFFFFF)
def construct_message(header, body):
    session = crc.start(hdlc_spec)
    crc.add(hdlc_spec, session, header)
    crc.add(hdlc_spec, session, body)
    return crc.finish(hdlc_spec, session)

^* While the C implementation supports up to 64-bit CRCs, Asp's integers are only 32 bits in size, so only CRCs up to 32 bits in length are supported.

`sort`

The sort library includes two functions: sort and sorted. Both accept a compare argument which is a function that accepts two arguments and returns an integer value based on how they compare relative to each other. To affect an ascending sort order, the comparison function should return a negative value if the first argument is less than the second, a positive value if the first argument is greater than the second, and zero if they are considered equal.

The sort function accepts, as its first argument, a list. When called, the items in the list are sorted in place, thus modifying the list. Here is an example usage using a list of integer values.

import sort
def compare_ints(a, b):
    return a - b
items = [42, -7, 3, 6]
sort.sort(items, compare_ints)
print(items)

The output of the above program would be as follows.

[-7, 3, 6, 42]

If it is undesirable to modify the original list, or if the items are not in a list, as long as the items are iterable, the sorted function can be used to return a list of the items in sorted order.

For example, to sort the characters within a string is possible even though strings are immutable. Here is an example.

import sort
import string
def compare(a, b):
    return a <=> b
s = 'the quick brown fox jumps over the lazy dog'
print('%r' % (string.join(sort.sorted(s, compare)),))

Because the sorted function returns a list of single-byte strings, this example script uses the string library's join function to reform the output into a single string, as the output confirms.

'        abcdeeefghhijklmnoooopqrrsttuuvwxyz'

The implementation uses the insertion sort algorithm which provides a stable sort, keeping elements that compare equal (according to the comparison function) in their original relative order.

`string`

The string library contains many functions for manipulating strings. It is designed after the methods provided by Python's string type, str. Since Asp does not support classes and methods, the string to be operated on is normally given as the first argument to all applicable functions, the one notable exception being the join function.

For the most part, the functions behave in a manner identical to that of the corresponding Python method, so Python's documentation^* should suffice for usage. Differences between the Asp and Python versions are discussed below.

A few of Python's string methods accept start and end arguments to specify a contiguous slice within the string under consideration. The functions in this library do not support these arguments because it is simple enough for the caller to slice the string beforehand.

Several of Python's string methods have no equivalent function in this library. The reason is because they only make sense in the context of the Unicode character set of which Python strings are composed. Recall that Asp strings are sequences of 8‑bit bytes (usually interpreted as ASCII).

Some of Python's character classification functions are not implemented because they apply to Unicode. Other character classification functions have been added beyond what Python offers; the implementations of these functions use the equivalent C character classification function.

The following table lists all of the string methods/functions available in Python and Asp, in alphabetical order, indicating which of the two languages provide it.

Python string method	Asp function	Notes
`str.capitalize()`	N/A
`str.casefold()`	N/A	For Asp's non-Unicode strings, `lower` provides the same functionality.
`str.center(width[, fillchar])`	`center(str, width, fillchar=' ')`
N/A	`checktrans(table)`	Returns a Boolean indicating whether the given translation table is valid for use with `translate`. This function is used internally by both `translate` and `maketrans` to validate a table. Note that passing an invalid translation table to either `translate` or `maketrans` will end a script with an error.
`str.count(sub[, start[, end]])`	`count(str, sub)`
`str.encode(encoding='utf-8', errors='strict')`	N/A	For non-Unicode translations, use `maketrans` and `translate`.
`str.endswith(suffix[, start[, end]])`	`endswith(str, suffix)`
`str.expandtabs(tabsize=8)`	`expandtabs(str, tabsize=8)`
`str.find(sub[, start[, end]])`	`find(str, sub)`
`str.format(args, *kwargs)`	N/A	In Asp, formatting is provided by the `%` operator.
`str.format_map(mapping, /)`	N/A	In Asp, formatting is provided by the `%` operator.
`str.index(sub[, start[, end]])`	N/A	Similar functionality that does not end the script with an error is provided by the `find` function.
`str.isalnum()`	`isalnum(str)`
`str.isalpha()`	`isalpha(str)`
`str.isascii()`	`isascii(str)`
N/A	`isblank(str)`	Returns `True` if all characters in the string are blank characters according to C's `isblank` function, and there is at least one character, `False` otherwise.
N/A	`iscntrl(str)`	Returns `True` if all characters in the string are control characters according to C's `iscntrl` function, and there is at least one character, `False` otherwise.
`str.isdecimal()`	N/A	For Asp's non-Unicode strings, `isdigit` provides the same functionality.
`str.isdigit()`	`isdigit(str)`
N/A	`isgraph(str)`	Returns `True` if all characters in the string have a graphical representation according to C's `isgraph` function, and there is at least one character, `False` otherwise.
`str.isidentifier()`	N/A	Since Asp does not provide code introspection, the usefulness of this function is doubtful.
`str.islower()`	`islower(str)`
`str.isnumeric()`	N/A	For Asp's non-Unicode strings, `isdigit` provides the same functionality.
`str.isprintable()`	`isprintable(str)`
N/A	`ispunct(str)`	Returns `True` if all characters in the string are punctuation characters according to C's `ispunct` function, and there is at least one character, `False` otherwise.
`str.isspace()`	`isspace(str)`
`str.istitle()`	N/A
`str.isupper()`	`isupper(str)`
N/A	`isxdigit(str)`	Returns `True` if all characters in the string are hexadecimal digit characters according to C's `isxdigit` function, and there is at least one character, `False` otherwise.
`str.join(iterable)`	`join(iterable, sep='')`	In the Asp version, the separator is specified as an optional second parameter, defaulting to an empty string.
`str.ljust(width[, fillchar])`	`ljust(str, width, fillchar=' ')`
`str.lower()`	`lower(str)`
`str.lstrip([chars])`	`lstrip(str, chars=None)`
`static str.maketrans(x[, y[, z]])`	`maketrans(*args)`	The Python version of this function is static, so the Asp version accepts the exact same arguments as Python's method, except that in the Asp version, they are unnamed. Instead of creating a map with integer Unicode code points as the keys, Asp's version uses single-byte strings instead. The `checktrans` function may be used to validate the table when calling with a single argument.
`str.partition(sep)`	`partition(str, sep)`
`str.removeprefix(prefix, /)`	`removeprefix(str, prefix)`
`str.removesuffix(prefix, /)`	`removesuffix(str, prefix)`
`str.replace(old, new, count=-1)`	`replace(str, old, new, count=-1)`
`str.rfind(sub[, start[, end]])`	`rfind(str, sub)`
`str.rindex(sub[, start[, end]])`	N/A	Similar functionality that does not end the script with an error is provided by the `rfind` function.
`str.rjust(width[, fillchar])`	`rjust(str, width, fillchar=' ')`
`str.rpartition(sep)`	`rpartition(str, sep)`
`str.rsplit(sep=None, maxsplit=-1)`	`rsplit(str, sep=None, maxsplit=-1)`
`str.rstrip([chars])`	`rstrip(str, chars=None)`
`str.split(sep=None, maxsplit=-1)`	`split(str, sep=None, maxsplit=-1)`
`str.splitlines(keepends=False)`	`splitlines(str, keepends=False, ends=None)`	The Asp version of this function adds an optional `ends` parameter that specifies an iterable of line endings. If all desired line endings are single bytes, because strings are iterable, a string of line endings may be given. If one or more desired line endings are multi-byte, provide a list or tuple of strings, ensuring that longer strings are placed before shorter ones so that the longest match for a line ending will be found. If `ends` is left unspecified, or `None` is given, the default set is used, which is identical to the ones used in Python, less the multi-byte Unicode line ending characters.
`str.startswith(prefix[, start[, end]])`	`startswith(str, prefix)`
`str.strip([chars])`	`strip(str, chars=None)`
`str.swapcase()`	N/A
`str.title()`	N/A
`str.translate(table)`	`translate(str, table)`	See `maketrans` for a description of the translation table.
`str.upper()`	`upper(str)`
`str.zfill(width)`	`zfill(str, width)`

^* Last known location: https://docs.python.org/3/library/stdtypes.html#string-methods.

A note to application developers

The string library is provided in two parts: the C implementation and a script module. The C implementation handles character classifications; its interface is provided in string-class.asps. It should be imported into the application specification using the following statement.

import 'string-class' as string_class

The reason for this is because the Asp script module part of this library, string.asp, imports this module by the name string_class.