Differences

This shows you the differences between two versions of the page.

--- manual:chapter4:libs [2018/03/02 09:00]
claudio
+++ manual:chapter4:libs [2018/03/02 09:46]
claudio [Creating user libraries]
@@ Line 17: / Line 17: @@
 === Special variables ===
-''$LIBID'' Contains the library ID that will identify the library. The library ID is an identifier up to 4 letters or numbers. The only allowed characters are A-Z, a-z and 0-9, if any other characters are included or if the length esxceeds 4 characters ''CRLIB'' will issue an invalid library ID error.
+''$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.
@@ Line 45: / Line 45: @@
   * Always store private library settings using ''LIBSTO'' and ''LIBRCL''. These two commands will work the same as ''STO'' and ''RCL'' when called from the source directory, but when executed from within a library command, they will store/recall content from a special hidden directory that is private to the library. Each library can store arbitrary data in this private directory. Data is persistent and can only be erased by calling the ''LIBCLEAR'' command. Data stored with ''LIBSTO'' can only be recalled with ''LIBRCL'', using the unquoted name won't work since the variable is not in the current directory or local variable environment.
+  * After testing a library, remember to ''DETACH'' it before trying to edit its code in the source directory. Remember that the variables are named exactly like the library commands, and if the library is attached, those names will be compiled to call the installed library, rather than the intended name identifier. This will not be visible to the user, the code will look identical but ''CRLIB'' will not be able to scan the names to include the subroutine.
+  * When creating new versions of a library, always add commands **at the end** of the ''$VISIBLE'' list. People using your library will have their own programs compiled with library pointers, which internally use the library ID and the index into the ''$VISIBLE'' list to refer to your commands. If the order of the commands change on the new version, user programs compiled for previous versions of the library will call the wrong command. If desired, create a custom ''$MENU'' to organize the commands in a different order as ''$VISIBLE''.
+=== 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.
 ----