Provided by: falconpl_0.9.6.9-git20120606-2_amd64 bug

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 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 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 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 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/.