____ ____ ____ ____ ||n |||i |||m |||f || ||__|||__|||__|||__|| |/__\|/__\|/__\|/__\|
Modules in nimf are files that are built to be used by other code, rather than executed as standalone programs. They could also include code meant to be used in interactive mode (rather than file mode or run mode).
The standard library, at time of writing, consists of six modules. To use the code that they contain, you will need to use a special word that loads the module: `inline`.
For example, to load the `text` module you would run (or include in your own file) the following:
" text " inline
After you do so, all of the words, variables, and enums will be available to the code you are writing.
If you attempt to inline the file again, you will be notified that the file has already been inlined. This message is not an error, and does not clear the stack.
Inlining has a few caveats to know about. The first is that the word `inline` must have a newline after it (or before any other words appear). This is a bug in the current system that will hopefully be remedied in future releases.
The second is that modules can inline other modules. When this happens, all of the code becomes available to the global scope. So it you inline the `text` module like was shown above, you may not notice that the `text` module also inlines the `std` module and the `num` module. In theory that means that you do not need to inline them in your code. As good practice, and for clarity of intention, you should still do so. Unlike when you inline a file in interactive mode, when a module inlines another module, it does not print the warning about attempting to inline a module that has already been inlined. It is happy enough that the code is there and it just moves on with its loading in silence.
The nimf system knows to look for modules in a few key places and will load the first version of a module that it can find. It will look for modules in these filepaths, in order:
If you develop a module and want to include a Makefile or instructions on how to install it, the recommendation is to have it install to one of the last three. The last one is good for full system installs, but often requires administrator privileges.
A module can contain words, variables, and enums. It should not execute any code other than what is necessary to properly set up variables (`var`, `svar`, `allot`). This is not a hard rule, but it is polite to not run code on people's systems without them explicitly calling it (at least when you purport to be a module/library).
Modules should have, by convention, the file suffix `.nh` (nimf header). This is another indicator to other developers that the file is meant to be inlined, and not run as an independent program.
It is good practice to put a comment at the top of the file explaining what the module does and what the prefered words are for interacting with it.
Modules should "namespace" their words whenever possible in order to prevent naming collisions. For example, words in the `num` module are prefixed with `num.`, like `num.negative?`. Modules can also have private words. A private word is named like so: `num.private.negation-helper`. That is not a real word, but it shows the format: [module].private.[word-name]. Private words are not intended for users or other developers to interact with, but are used within the module. Words that follow the private word naming scheme do not appear when a user calls the word `words`. They technically can still be called, but by convention should not be.
The last word in a module should always be `module-end`. This lets the interpreter know that the module has been read and it can switch out of inline mode.
________________________________________________