NAME
falcon - The Falcon Programming Language command line interpreter
SYNOPSIS
falcon [options] [main_script] [script_options]
DESCRIPTION
The falcon command line interpreter is used to launch, compile,
assemble or debug scripts written in the Falcon Programming Language.
The command line interpreter pushes the core module and the rtl module
in the script load table, so they are available by default to all the
scripts.
The default operation is that of launching the given script, or read it
from the standard input if the script name is not given. By default,
falcon saves also the compiled module of the script in the same
directory where it is found, changing the extension to ".fam".
The main_script can be a "logical" module name, a relative path or an
absolute path. In case it’s a logical module name, that is, a script
name without extension nor leading path, it is searched through the
load path. The default load path is determined by the compilation
options of the interpreter, and usually it includes the current
directory. The environment variable FALCON_LOAD_PATH and the command
line option -L can change the default module search path.
When the main module is found, its path is added to the module search
path; in other words, there isn’t any need to specify the path
containing the main module to have other modules in its same directory
to get loaded. The main module and other source Falcon module it loads
can be stored in a directory that is not listed in the module search
path; indicating an absolute or relative path as the main_script
parameter will add that path on top of the active search path.
If not differently specified, falcon will search for .fam modules newer
than the relative .fal source scripts and will load those ones instead
of compiling the sources.
Options past the script name will be directly passed in the args[]
global variable of the script.
The interpreter is compatible with the UNIX script execution directive
"#!". A main script can have on the very first line of the code the
directive
#!/path/to/falcon
to declare to the shell that the falcon command line is to be loaded.
If falcon command line interpreter is also in the system PATH
environment variable, which is usually the case of a normal
installation, then the interpreter directive may also be simply
#!/bin/env falcon
It is then simply necessary to make the main script executable with
chmod 744 script_name
to be able to call the script directly.
Scripts executed in this way will add their path to the falcon module
load path as soon as they are loade, so other modules referenced by
them will be searched in the directory where they resides before being
searched elsewhere.
Options to the falcon compiler may be passed normally by writing them
after the execution directive in the main script.
Since version 0.8.12, the falcon command line interpreter has also an
interactive mode which accepts statements and provide results as the
expressions are evaluated.
OPTIONS
-c Compile but do not execute. This makes falcon to compile the
given module into a .fam file and then terminate. By default,
the .fam file is written to a file with the same name as the
input one, with the .fam extension.
-C Check for memory leaks in VM execution. Like the -M option of
faltest, this function sets the falcon engine memory allocators
to slower functions that checks for memory to be allocated and
deallocated correctly during the execution of a module. If the
script is executed, before Falcon exits it writes a small report
to the standard output.
-d <directive>=<value>
Sets the given directive to the desired value. Compilation
directives and their values are the ones that scripts can set
through the directive statement.
-D <constant>=<value>
Sets the given constant to the desired value. Constants are made
available at compile time, and can be employed in macro and meta
compilation.
-e <enc>
Set given encoding as default for VM I/O. Unless the scripts
select a different I/O encoding, the streams that are provided
to the falcon VM (like the output stream for printf) are encoded
using the given ISO encoding. This overrides the default
encoding that is detected by reading the environment settings.
In example, if your system uses iso-8859-1 encoding by default,
but you want your script to read and write utf-8 files, use the
option -e utf-8
The -e option also determines the default encoding of the source
files. To override this, use -E
-E <enc>
Set source script encoding. As -e , but this determines only the
encoding used by falcon when loading the source scripts. This
options overrides -e values, so it can be used to set the script
encoding when they have to read and write from different
encodings.
-f Force recompilation of modules even when .fam are found.
-h or -?
Prints a brief help on stdout and exits.
-h or -?
Interactive mode. Falcon interpreter reads language statements
from a prompt and present evaluation results to the user.
-l <lang_code>
Select a different language code for internationalized programs.
This option loads an alternate string table for all the modules
loaded. If the table doesn’t exist or if the modules doesn’t
have a .ftr file containing the translation, the operation
silently files and the original strings are used instead.
Language codes should be in the international ISO format of five
characters with a language name, an underscore and the regional
code, like in en_US
-L <path>
Changes the default load path. This overrides both the internal
built in settings and the contents of environment variable
FALCON_LOAD_PATH. Each directory in the path should be separated
by ";" and use forward slashes, like this:
falcon -L
-m Use temporary files for intermediate steps. By default
compilation is completely performed in memory; this option makes
falcon to use temporary files instead.
-M Do NOT save the compiled modules in ’.fam’ files.
-o <fn>
Redirects output to <fn>. This is useful to control the output
of falcon when using options as -c, -a, -S etc. If <fn> is a
dash (-) the output is sent to stdout.
-p <module>
Preloads the given module as if it were loaded by the main
script.
-P Ignore default load paths and uses only the paths set via the -L
switch.
-r Ignore source files and only use available .fam. This does not
affects the main script; use the -x option if also the main
script is a pre-compiled .fam module and source script must be
ignored.
-S Produce an assembly output. Writes an assembly representation of
the given script to the standard output aznd the exit. Use -o to
change file destination.
-t Generates a syntactic tree of the source and writes it to the
standard output, then exits. The syntactic tree is a
representation of the script that is known by the compiler and
used by the generators to create the final code. This option is
useful when debugging the compiler and to test for the correct
working of optimization algorithm.
-T Force input parsing as .ftd (Falcon Template Document).
Normally, only files ending with ".ftd" (case sensitive) are
parsed as template document; when this switch is selected, the
input is treated as a template document regardless of its name.
-v Prints copyright notice and version and exits.
-w After execution, requires the user to confirm program
termination by pressing <enter>. This helps in point & click
environments, where Falcon window is closed as soon as the
program terminates.
-x Executes a pre-compiled .fam module.
-y Creates a template file for internationalization. This option
creates a single .ftt file from a single source, .fam module or
binary module. By default, the name of the template is the same
as the module plus ".temp.ftt" added at the end; it is possible
to change the destination template file using the -o option.
FILES
/usr/lib/libfalcon_engine.so
Default location of the Falcon Engine loadable module.
/usr/lib/falcon
Default directory containing Falcon binary modules.
ENVIRONMENT
FALCON_LOAD_PATH
Default search path for modules loaded by the scripts.
FALCON_SRC_ENCODING
Default encoding for the source scripts loaded by falcon (when
different from the system default).
FALCON_VM_ENCODING
Default encoding for the VM I/O streams (when different from
system default).
AUTHOR
Giancarlo Niccolai <gc@falconpl.org>
SEE ALSO
falrun(1) faldisass(1) fallc.fal(1)
LICENSE
This document is released under the "GNU Free Documentation License,
version 1.2". On Debian systems, the complete text of the Free
Documentation License, version 1.2, can be found in
/usr/share/common-licenses/.