falcon(1)                                                       Falcon User Manuals                                                      falcon(1)

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 con-
       taining 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  envi-
       ronment 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 loaded, 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.

       -i     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 FAL-
              CON_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 and 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  tem-
              plate 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  Docu-
       mentation License, version 1.2, can be found in /usr/share/common-licenses/.

Falcon toolset                                                      April 2007                                                           falcon(1)