INCLUDE documentation
From DocBase
Include is a REBOL function working as a REBOL script preprocessor and evaluator. It is not an "alternative module system", in fact, it is orthogonal to any such system, meaning, that it can work together with such a system.
Contents
|
Design features
- An improved do:
- include can preprocess and evaluate any script (the script does not have to contain any prebol directives).
- Processes prebol directives to facilitate SDK debugging.
- Uses include-path to search for the scripts - resembles paths of many operating systems; include-path can contain URLs, not just local directories.
- Has the ability (optional) to prevent scripts from being re-included (included more than once).
- Processes ordinary scripts with REBOL header.
- Processes prefaced REBOL scripts, i.e. REBOL scripts with preface preceding REBOL header (see [1]).
- Processes embedded REBOL scripts, i.e. scripts embedded in text.
- An improved loader and preprocessor:
- include/only just loads and preprocesses a script, yielding a REBOL block.
- include/link saves the preprocessed script to a specified file.
- Uses include-path like above.
- A "don't re-include" option is available.
- Processes all prebol directives and is compatible with SDK.
- It is possible to include small parts of scripts, like binary data, images or strings.
- Context encapsulation is available using
make object!ormake module!method.
Description
The preprocessing phase is used to build the script, i.e. essentially to include some parts. Moreover, it enables the user to evaluate any REBOL expression(s).
Preprocessing directives
#include - include a script (file or URL) here #include-check - include a script (file or URL) here, avoid duplicities #do - do the code during preprocessing, include the result here #either - conditionally include one of two blocks #if - conditionally include a block #include-string - include a string #include-binary - include binary data #include-files - include a block of files from the given path comment - marks a (possibly multiline) on-demand strippable comment
Global words used
include, include-path, keep-comments (this is used only potentially, no definition is required)
Comment usage
The usage of the comment word as a directive means, that it does not behave as a function, but rather as a keyword. That means, that a redefinition of it during run-time does not have any effect, if it has already been processed in the preprocessing stage.
Comments are normally stripped off by the preprocessor. If the keep-comments word is set when a comment is encountered, the comment is kept in the code.
Usage examples
The call, equivalent to prebol processing %somefile.r and storing the result of the preprocessing to %outfile.r, would look like:
include/link %somefile.r %outfile.r
To change the include-path:
append include-path url-or-directory
The include call corresponding to the #include-check directive is include/check, which preprocesses and runs the script only if it hasn't done so before:
include/check %somefile.r
The distinction between preprocessing directives and "normal" include usage is best described on simple examples:
The first example uses include, not the preprocessing directives:
REBOL [
File: %script-builder.r
]
; create a new "standard" script from the script base
verbose: false
include/link %script-base.r %standard-script.r
; now create a verbose version
verbose: true
include/link %script-base.r %verbose-script.r
To create the two versions of the script containing everything they need to run, it is sufficient to do:
include %script-builder.r
, which takes care of creating both script versions.
The %script-base.r file can look e.g. as follows:
REBOL [
File: %script-base.r
]
#either [verbose] [debug: :print] [debug: none]
#include-check %part1.r
#include-check %part2.r
...
Context encapsulation
It is possible to encapsulate contexts as follows:
REBOL [
Title: "my script"
]
make object! [#include %your-script.r]
make module! [[module spec goes here] [#include %his-script.r]]
How to's
How to write a script detecting whether it has been preprocessed
When a script is running, you may need to find out, whether it has been preprocessed or not. Here is how:
REBOL [
Author: "Ladislav Mecir"
Purpose: {Script detecting whether it has been preprocessed}
]
either (#do [false]) [
print "script wasn't preprocessed"
] [
print "script was preprocessed by PREREBOL or INCLUDE"
]
How to write a part of a script that you don't want to be preprocessed
Sometimes you want a part of the script to remain untouched by the preprocessor. This is a way how:
REBOL [
Author: "Ladislav Mecir"
Purpose: {Script containing code that is not preprocessed}
]
#do [[
; this part will not be preprocessed
prin "part1: "
print either (#do [false]) ["not preprocessed"] ["preprocessed"]
]]
; this part will be preprocessed
prin "part2: "
print either (#do [false]) ["not preprocessed"] ["preprocessed"]
How to write a script compatible with both do and include
The %include.r script may serve as an example of a script containing the preprocessor directives. Still, you may want to write such a script so, that its behaviour is the same whether it has been run by do or include.
Combining the tricks from the previous sections:
REBOL [
Author: "Ladislav Mecir"
Purpose: {Script compatible with both DO and INCLUDE}
]
do if (#do [false]) [func [a b] [do first b]] #do [[
; here we can put any code with preprocessor directives
; without worrying whether the user ran the script using DO or INCLUDE:
print mold #include
; etc.
]]
How to create a MS Windows Explorer association for include
To create a MS Windows Explorer association, so you can right-click on a .r file to run include on it:
- Download the
%include.rscript. - Create a script file including any script file
- This is an example file (use your own directory paths):
REBOL [
Title: "Incl"
File: %incl.r
Author: "Ladislav Mecir"
Date: 8-Apr-2006/20:06:47+2:00
Purpose: {Includes first argument file}
]
; define the INCLUDE function
do %include.r
; append the SDK source directory to the INCLUDE-PATH
append include-path %/c/rebol/sdk-2-6-2/source/
; finally include the argument script
include to-rebol-file system/script/args
- Add a new association for .r files
How to add the new association for .r files in Windows XP or older
Run the MS Windows Explorer and click on Tools/Options in menu. Next, click on the "File Types" tab and find the .r file type associations. Click on the "Advanced" button and add a new action. Call the new action Include and the application associated with the new action may be e.g.:
C:\Rebol\sdk-2-6-2\tools\rebface.exe -s "C:\Documents and Settings\ladislav\Application Data\rebol\incl.r" "%1"
(Adjust your directory appropriately). Next you can decide whether to make the Include action default. If you make it default, you can just double-click (or left-click if you set your Explorer for one click as I did) on a .r file to include it. Otherwise you can right-click the file in Explorer and pick the Include action from the quick menu.
How to add the new association for .r files in Windows 7 (or Vista)
- Run the Windows Control Panel in Small Icons View mode.
- Click the "Default Programs" icon.
- Click on the "Associate a file type or protocol with a program" link.
- Under the left "Name" column, select the
.rfile extension type - Click on the "Change Program" button
- Choose the program to use (rebol.exe)
- Run the regedit.exe program
- Find the rebol.exe key
- Under the shell subkey add a new Include key
- Under the Include key add a new command subkey
- Change the command to be something like
E:\Ladislav\Rebol\rebol.exe -s E:\Ladislav\Rebol\Data\incl.r %1(do not forget to use your directory paths)
Now, after right-clicking a .r file in the Windows Explorer, you will see a new "Include" option, which you can use
Availability
Include is available from http://www.fm.vslib.cz/~ladislav/rebol/include.r, where you can find also the R3 version.
See also
This article describes, how INCLUDE was ported to R3.
