User created libraries

Libraries are a way to package and distribute a group of programs or data for others to use. They can be accessed from the Lib menu, which shows all currently installed libraries. Initially, the Libs menu is empty until libraries are installed.

Installing/removing a library

Libraries are regular RPL objects and therefore can be transferred to the calculator via the USB port or SD card. To enable the functionality of a library on the system, put the library object on the stack and use the ATTACH command (can be found on the main menu under submenu System, Lib, not to be confused with Libs which shows the installed libraries).

If the ATTACH command succeeds, it will leave on the stack a 4-letter library ID, and a string with the library description. The library ID is a unique name the developer assigns to the library, and is how the library shows up in the Libs menu. From that moment on, any commands exposed by the library will become available to use in programs or directly from the corresponding submenu in the Libs menu.

To remove a library that was previously installed, use the command DETACH. The command takes a library ID in the form of a 4-letter identifier, it can be retrieved directly from the Libs menu using RShold-[menu key] while in Alpha mode. To confirm that a library was successfully detached, check that its library ID no longer appears in the Libs menu.


Creating user libraries

User libraries are created by putting in a separate directory all the programs and data the library needs to carry. Some additional data is necessary and has to be provided in specially named variables that will be analyzed in detail next. Once all the information is there, the command CRLIB executed from within the library directory will produce a proper library object and leave it on the stack. The original source directory is left unmodified.

Special variables

$LIBID Contains the library ID that will identify the library. The library ID is an identifier up to 4 letters or numbers, with the first character being a letter. The only allowed characters are A-Z, a-z and 0-9, if any other characters are included or if the length exceeds 4 characters CRLIB will issue an invalid library ID error.

$TITLE Contains a string with a title/description or copyright message of the library. It has no purpose other than being shown to the user when the library is attached, or when the help is invoked on the Libs menu by long-pressing on the library name.

$VISIBLE Consists of a list with information about the commands that will be exposed to the user. Any commands not in this list will not be visible to the user, and unless called from one of the visible commands, they won't be bundled with the library either. The list has to follow a specific format:

{ { IDENT NARGS ALLOWINSYMB HELPTEXT } { IDENT NARGS ALLOWINSYMB HELPTEXT } … }

Where IDENT is the name of the command to be made visible, this is both the name of the variable containing the command in the directory, and the name of the command as it will be seen by the user of the library. NARGS and ALLOWINSYMB are integer numbers. The former is the number of arguments that the command takes from the stack, and the latter is a true/false value (1 or 0) indicating whether that command will be allowed to be used in symbolic expressions or not. All user commands (when allowed by setting this number to 1), will be accepted as a function call inside expressions, and the number of arguments will be checked against the NARGS number. Finally, HELPTEXT is a string to be used as help when the user long-presses the name of the command in the menu. The string should be formatted so the text is in 3 lines, with the first 2 describing the command and the third line shows a stack diagram (preferably following the same guidelines as used in the system menus for consistency). The $VISIBLE must therefore be a list of lists, where each sublist has exactly 4 elements: one ident, two integers and one string. Any deviation from this format will cause CRLIB to issue an Invalid $VISIBLE list.

$MENU (optional) The CRLIB command will automatically create a menu with all the visible commands in the same order as listed in $VISIBLE. If the library requires other types of menu, a complete menu definition can be included in $MENU. If a custom $MENU is given, the HELPTEXT field given in $VISIBLE is simply ignored (the help must be provided as part of the custom menu), but must exist (an empty string “” can be used in this case).

$IGNORE (optional) In some cases there might be data or programs in the library directory that should not be included with the library, even though they might be referenced by the library commands (this is uncommon but could happen). This optional list of identifiers tells CRLIB to never bundle this variable with the library.

Using CRLIB

The CRLIB command works in a complex way, and understanding how it works helps the developer plan ahead the organization of the library to make sure things work well. The most important points that need to be considered when writing a library are:

Sample library "Hello world!"

To create the library, first create an empty directory: 'helloLIB' CRDIR and go into it. This library will have a single command HWORLD that puts the message “Hello world!” on the stack.

Create the variables needed inside the directory:

Variable Content
HWORLD « “Hello ” WORLD + »
WORLD “world!”
$LIBID 'MyHW'
$TITLE “My Hello World Library!”
$VISIBLE { { 'HWORLD' 0 0 “Shows a nice↲greeting.↲ → ” } }

Finally, use CRLIB to create the library, then ATTACH to attach it. From the main menu, Libs will now show an item MyHW. Long pressing the item will show the library title. Going into the menu we should see the HWORLD command, long pressing it will show the help that was provided.

Notice that in this case, the WORLD string was included in the library because it was referenced by the main program HWORLD, but it is not visible to the user. From now on, compiling a program that contains HWORLD will use the installed library command, rather than an identifier. Programs compiled before the library was attached will have an identifier instead.