Man Linux: Main Page and Category List

NAME

       escript - Erlang scripting support

DESCRIPTION

       escript  provides  support  for  running  short Erlang programs without
       having to compile them first and an easy way to  retrieve  the  command
       line arguments.

EXPORTS

       script-name script-arg1 script-arg2...
       escript escript-flags script-name script-arg1 script-arg2...

              escript runs a script written in Erlang.

              Here follows an example.

              $ cat factorial
              #!/usr/bin/env escript
              %% -*- erlang -*-
              %%! -smp enable -sname factorial -mnesia debug verbose
              main([String]) ->
                  try
               11N = list_to_integer(String),
               11F = fac(N),
               11io:format("factorial ~w = ~w", [N,F])
                  catch
               11_:_ ->
               11    usage()
                  end;
              main(_) ->
                  usage().

              usage() ->
                  io:format("usage: factorial integer"),
                  halt(1).

              fac(0) -> 1;
              fac(N) -> N * fac(N-1).
              $ factorial 5
              factorial 5 = 120
              $ factorial
              usage: factorial integer
              $ factorial five
              usage: factorial integer

              The  header  of  the Erlang script in the example differs from a
              normal Erlang module. The first  line  is  intended  to  be  the
              interpreter  line,  which invokes escript. However if you invoke
              the escript like this

              $ escript factorial 5

              the contents of the first line does not matter,  but  it  cannot
              contain Erlang code as it will be ignored.

              The  second  line in the example, contains an optional directive
              to the Emacs editor which causes it to enter the major mode  for
              editing Erlang source files. If the directive is present it must
              be located on the second line.

              On the third line (or second line depending on the  presence  of
              the  Emacs  directive),  it is possible to give arguments to the
              emulator, such as

              %%! -smp enable -sname factorial -mnesia debug verbose

              Such an argument line must start with %%! and the  rest  of  the
              line will interpreted as arguments to the emulator.

              If  you  know  the location of the escript executable, the first
              line can directly give the path to escript. For instance:

              #!/usr/local/bin/escript

              As any other kind of scripts, Erlang scripts will  not  work  on
              Unix  platforms  if the execution bit for the script file is not
              set. (Use chmod +x script-name to turn on the execution bit.)

              The rest of the Erlang script file  may  either  contain  Erlang
              source code, an inlined beam file or an inlined archive file.

              An  Erlang  script file must always contain the function main/1.
              When the script is run, the main/1 function will be called  with
              a list of strings representing the arguments given to the script
              (not changed or interpreted in any way).

              If the main/1 function in the script returns  successfully,  the
              exit  status  for  the  script  will  be  0.  If an exception is
              generated during execution, a short message will be printed  and
              the script terminated with exit status 127.

              To  return your own non-zero exit code, call halt(ExitCode); for
              instance:

              halt(1).

              Call escript:script_name/0 from your to script to  retrieve  the
              pathname of the script (the pathname is usually, but not always,
              absolute).

              If the file contains source code (as in the example  above),  it
              will  be  processed by the preprocessor epp. This means that you
              for example may use pre-defined macros (such as ?MODULE) as well
              as  include  directives  like  the  -include_lib  directive. For
              instance, use

              -include_lib("kernel/include/file.hrl").

              to include the record definitions for the records  used  by  the
              file:read_link_info/1 function.

              The   script   will   be  checked  for  syntactic  and  semantic
              correctness before being run. If there  are  warnings  (such  as
              unused  variables),  they  will  be  printed and the script will
              still be run. If there are errors, they will be printed and  the
              script will not be run and its exit status will be 127.

              Both  the  module  declaration and the export declaration of the
              main/1 function are optional.

              By default, the script will be interpreted. You can force it  to
              be  compiled  by  including  the following line somewhere in the
              script file:

              -mode(compile).

              Execution of interpreted code is slower than compiled  code.  If
              much  of the execution takes place in interpreted code it may be
              worthwhile to compile it, even  though  the  compilation  itself
              will take a little while.

              As  mentioned  earlier,  it  is  possible to have a script which
              contains precompiled beam code. In  a  precompiled  script,  the
              interpretation  of the script header is exactly the same as in a
              script containing source code. That means that you  can  make  a
              beam  file  executable  by  prepending  the  file with the lines
              starting with #! and  %%!  mentioned  above.  In  a  precompiled
              script, the function main/1 must be exported.

              As  yet  another  option it is possible to have an entire Erlang
              archive in the script. In a archive script,  the  interpretation
              of  the  script  header  is  exactly  the  same  as  in a script
              containing source code. That means that you can make an  archive
              file  executable  by prepending the file with the lines starting
              with #! and %%! mentioned  above.  In  an  archive  script,  the
              function main/1 must be exported. By default the main/1 function
              in the module with the same name as the basename of the  escript
              file will be invoked. This behavior can be overridden by setting
              the flag -escript main Module as one of the emulator flags.  The
              Module must be the name of a module which has an exported main/1
              function. See code(3erl) for more information about archives and
              code loading.

              In  many  cases  it  is  very convenient to have a header in the
              escript, especially on Unix platforms. But the header is in fact
              optional.  This  means that you directly can "execute" an Erlang
              module, beam file or archive file without adding any  header  to
              them. But then you have to invoke the script like this:

              $ escript factorial.erl 5
              factorial 5 = 120
              $ escript factorial.beam 5
              factorial 5 = 120
              $ escript factorial.zip 5
              factorial 5 = 120

OPTIONS ACCEPTED BY ESCRIPT

         -c  Compile   the  escript  regardless  of  the  value  of  the  mode
             attribute.

         -d  Debug the escript. Starts the debugger, loads the module
                   containing the  main/1 function into the debugger, sets a
                   breakpoint in  main/1 and invokes  main/1. If the
                   module is precompiled, it must be explicitly compiled  with
             the
                    debug_info option.

         -i  Interpret  the  escript  regardless  of  the  value  of  the mode
             attribute.

         -s  Only perform a syntactic and semantic check of the script file.
                    Warnings and errors (if any) are written to  the  standard
             output, but
                    the  script  will not be run. The exit status will be 0 if
             there were
                    no errors, and 127 otherwise.