1falcon(1) Falcon User Manuals falcon(1)
2
3
4
6 falcon - The Falcon Programming Language command line interpreter
7
8
10 falcon [options] [main_script] [script_options]
11
12
14 The falcon command line interpreter is used to launch, compile, assem‐
15 ble or debug scripts written in the Falcon Programming Language. The
16 command line interpreter pushes the core module and the rtl module in
17 the script load table, so they are available by default to all the
18 scripts.
19
20 The default operation is that of launching the given script, or read it
21 from the standard input if the script name is not given. By default,
22 falcon saves also the compiled module of the script in the same direc‐
23 tory where it is found, changing the extension to ".fam".
24
25 The main_script can be a "logical" module name, a relative path or an
26 absolute path. In case it's a logical module name, that is, a script
27 name without extension nor leading path, it is searched through the
28 load path. The default load path is determined by the compilation
29 options of the interpreter, and usually it includes the current direc‐
30 tory. The environment variable FALCON_LOAD_PATH and the command line
31 option -L can change the default module search path.
32
33 When the main module is found, its path is added to the module search
34 path; in other words, there isn't any need to specify the path contain‐
35 ing the main module to have other modules in its same directory to get
36 loaded. The main module and other source Falcon module it loads can be
37 stored in a directory that is not listed in the module search path;
38 indicating an absolute or relative path as the main_script parameter
39 will add that path on top of the active search path.
40
41 If not differently specified, falcon will search for and will load
42 those ones instead of compiling the sources.
43
44 Options past the script name will be directly passed in the args[]
45 global variable of the script.
46
47 The interpreter is compatible with the UNIX script execution directive
48 "#!". A main script can have on the very first line of the code the
49 directive
50
51 #!/path/to/falcon
52
53 to declare to the shell that the falcon command line is to be loaded.
54 If falcon command line interpreter is also in the system PATH environ‐
55 ment variable, which is usually the case of a normal installation, then
56 the interpreter directive may also be simply
57
58 #!falcon
59
60 It is then simply necessary to make the main script executable with
61
62 chmod 744 script_name
63
64 to be able to call the script directly.
65
66 Scripts executed in this way will add their path to the falcon module
67 load path as soon as they are loade, so other modules referenced by
68 them will be searched in the directory where they resides before being
69 searched elsewhere.
70
71 Options to the falcon compiler may be passed normally by writing them
72 after the execution directive in the main script.
73
74
76 -a Assembles the given script. The resulting module is not exe‐
77 cuted; this options causes Falcon to just assemble the module
78 and exit. By default, the output module is written in a file
79 with the same name of the input file with the ".fam" extension.
80
81 -c Compile but do not execute. This makes falcon to compile the
82 given module into a .fam file and then terminate. By default,
83 the .fam file is written to a file with the same name as the
84 input one, with the .fam extension.
85
86 -C Check for memory leaks in VM execution. Like the -M option of
87 faltest, this function sets the falcon engine memory allocators
88 to slower functions that checks for memory to be allocated and
89 deallocated correctly during the execution of a module. If the
90 script is executed, before Falcon exits it writes a small report
91 to the standard output.
92
93 -D <directive>=<value>
94 Sets the given directive to the desired value. Compilation
95 directives and their values are the ones that scripts can set
96 through the directive statement.
97
98 -e <enc>
99 Set given encoding as default for VM I/O. Unless the scripts
100 select a different I/O encoding, the streams that are provided
101 to the falcon VM (like the output stream for printf) are encoded
102 using the given ISO encoding. This overrides the default encod‐
103 ing that is detected by reading the environment settings. In
104 example, if your system uses iso-8859-1 encoding by default, but
105 you want your script to read and write utf-8 files, use the
106 option
107
108 -e utf-8
109
110 The -e option also determines the default encoding of the source
111 files. To override this, use -E
112
113 -E <enc>
114 Set source script encoding. As -e , but this determines only the
115 encoding used by falcon when loading the source scripts. This
116 options overrides -e values, so it can be used to set the script
117 encoding when they have to read and write from different encod‐
118 ings.
119
120 -f Force recompilation of modules even when .fam are found.
121
122 -h or -?
123 Prints a brief help on stdout and exits.
124
125 -L <path>
126 Changes the default load path. This overrides both the internal
127 built in settings and the contents of environment variable FAL‐
128 CON_LOAD_PATH. Each directory in the path should be separated by
129 ";" and use forward slashes, like this:
130
131 falcon -L ./;/usr/share/falcon_mod;./myapp
132
133
134 -m Use temporary files for intermediate steps. By default compila‐
135 tion is completely performed in memory; this option makes falcon
136 to use temporary files instead.
137
138 -M Do NOT save the compiled modules in '.fam' files.
139
140
141 -o <fn>
142 Redirects output to <fn>. This is useful to control the output
143 of falcon when using options as -c, -a, -S etc. If <fn> is a
144 dash (-) the output is sent to stdout.
145
146 -p <module>
147 Preloads the given module as if it were loaded by the main
148 script.
149
150 -r Ignore source files and only use available .fam. This does not
151 affects the main script; use the -x option if also the main
152 script is a pre-compiled .fam module and source script must be
153 ignored.
154
155 -s compile via assembly
156 Instead of compiling the source and generate a virtual machine
157 code directly, falcon compiles all the sources into an interme‐
158 diate assembly representation, and then it compiles the given
159 assembly. Usually, you won't use this option unless you are
160 debugging the assembly generator.
161
162 -S Produce an assembly output. Writes an assembly representation of
163 the given script to the standard output aznd the exit. Use -o to
164 change file destination.
165
166 -t Generates a syntactic tree of the source and writes it to the
167 standard output, then exits. The syntactic tree is a representa‐
168 tion of the script that is known by the compiler and used by the
169 generators to create the final code. This option is useful when
170 debugging the compiler and to test for the correct working of
171 optimization algorithm.
172
173 -T Force input parsing as .ftd (Falcon Template Document). Nor‐
174 mally, only files ending with ".ftd" (case sensitive) are parsed
175 as template document; when this switch is selected, the input is
176 treated as a template document regardless of its name.
177
178 -v Prints copyright notice and version and exits.
179
180 -x Executes a pre-compiled .fam module.
181
182 -w After execution, requires the user to confirm program termina‐
183 tion by pressing <enter>. This helps in point & click environ‐
184 ments, where Falcon window is closed as soon as the program ter‐
185 minates.
186
187
189 /usr/lib/libfalcon_engine.so
190 Default location of the Falcon Engine loadable module.
191
192 /usr/lib/falcon
193 Default directory containing Falcon binary modules.
194
195
197 FALCON_LOAD_PATH
198 Default search path for modules loaded by the scripts.
199
200
201 FALCON_SRC_ENCODING
202 Default encoding for the source scripts loaded by falcon (when
203 different from the system default).
204
205
206 FALCON_VM_ENCODING
207 Default encoding for the VM I/O streams (when different from
208 system default).
209
210
212 Giancarlo Niccolai <gc@falconpl.org>
213
214
216 flcrun(1) flcdisass(1)
217
218
220 This document is released under the "GNU Free Documentation License,
221 version 1.2". On Debian systems, the complete text of the Free Docu‐
222 mentation License, version 1.2, can be found in /usr/share/com‐
223 mon-licenses/.
224
225
226
227
228Falcon toolset April 2007 falcon(1)