|
Next revision
|
Previous revision
|
manual:chapter7:userlibs [2021/10/05 02:12]
jojo1973 created |
manual:chapter7:userlibs [2021/10/12 07:08]
jojo1973 [Creating a new library] |
| <code> | <code> |
| { | { |
| { <Ident> <NArgs> <AllowInSymb> <HelpText> } | { |
| { <Ident> <NArgs> <AllowInSymb> <HelpText> } | <Ident> |
| | <NArgs> |
| | <AllowInSymb> |
| | <HelpText> |
| | } |
| ... | ... |
| } | } |
| |
| === $MENU === | === $MENU === |
| This is an optional variable: the ''[[manual:chapter6:libptr:cmd_crlib|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 nevertheless exist (an empty string ''""'' can be used in this case). | This is an optional variable: the ''[[manual:chapter6:libptr:cmd_crlib|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 [[manual:chapter7:custmenu|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 cannot be omitted: an empty string ''""'' can be used in this case. |
| |
| === $IGNORE === | === $IGNORE === |
| * quoted identifiers or other forms of calling programs will **not be recognized** by ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]''. For example, ''« 'MyMatrix' RCL INV »'' will do the same as before when executed outside the library, but ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' won't look for ''MyMatrix'', and won't add it to the library: the explicit use of ''[[manual:chapter6:dirs:cmd_rcl|RCL]]'' indicates the intent of reading the current directory, rather than recalling an internal library object/program;\\ \\ | * quoted identifiers or other forms of calling programs will **not be recognized** by ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]''. For example, ''« 'MyMatrix' RCL INV »'' will do the same as before when executed outside the library, but ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' won't look for ''MyMatrix'', and won't add it to the library: the explicit use of ''[[manual:chapter6:dirs:cmd_rcl|RCL]]'' indicates the intent of reading the current directory, rather than recalling an internal library object/program;\\ \\ |
| * write your code as you would use it from the source directory, remembering that if your code stores something temporarily in the directory and uses it by name using an unquoted identifier, you should ''[[manual:chapter6:dirs:cmd_purge|PURGE]]'' it before calling ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' or it will be included with the library. As an alternative, you can put its name in the ''$IGNORE'' list, and ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' will not include it.\\ \\ | * write your code as you would use it from the source directory, remembering that if your code stores something temporarily in the directory and uses it by name using an unquoted identifier, you should ''[[manual:chapter6:dirs:cmd_purge|PURGE]]'' it before calling ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' or it will be included with the library. As an alternative, you can put its name in the ''$IGNORE'' list, and ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' will not include it.\\ \\ |
| * Private library settings can be stored and recalled using ''[[manual:chapter6:libptr:cmd_libsto|LIBSTO]]'' and ''[[manual:chapter6:libptr:cmd_librcl|LIBRCL]]''. These two commands will work the same as ''[[manual:chapter6:dirs:cmd_sto|STO]]'' and ''[[manual:chapter6:dirs:cmd_rcl|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 ''[[manual:chapter6:libptr:cmd_libclear|LIBCLEAR]]'' command. Data stored with ''[[manual:chapter6:libptr:cmd_libsto|LIBSTO]]'' can only be recalled with ''[[manual:chapter6:libptr:cmd_librcl|LIBRCL]]'': using the unquoted name won't work since the variable is not in the current directory or local variable environment.\\ \\ | * private library settings can be stored and recalled using ''[[manual:chapter6:libptr:cmd_libsto|LIBSTO]]'' and ''[[manual:chapter6:libptr:cmd_librcl|LIBRCL]]''. These two commands will work the same as ''[[manual:chapter6:dirs:cmd_sto|STO]]'' and ''[[manual:chapter6:dirs:cmd_rcl|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 ''[[manual:chapter6:libptr:cmd_libclear|LIBCLEAR]]'' command. Data stored with ''[[manual:chapter6:libptr:cmd_libsto|LIBSTO]]'' can only be recalled with ''[[manual:chapter6:libptr:cmd_librcl|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 ''[[manual:chapter6:libptr:cmd_detach|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 ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' will not be able to scan the names to include the subroutine.\\ \\ | * after testing a library, remember to ''[[manual:chapter6:libptr:cmd_detach|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 ''[[manual:chapter6:libptr:cmd_crlib|CRLIB]]'' will not be able to scan the names to include the subroutine.\\ \\ |
| * When extending a library with new commands, always add entries **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''. | * when extending a library with new commands, always add entries **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''. |
| |