escript(3)

💖 escript — the Erlang module definition ✨

okay bestie, gather round 🫶 this is escript, an Erlang module (manual section 3, iykyk), and it's the one that gives you create and extract so you can make escripts and inspect escripts. Little icons of the Erlang world, truly.

---

🌸 DESCRIPTION 🌸

ngl the actual details of how to use escripts live in the escript program documentation — go read that for the full lore. This page is just the module functions. 💅

---

🎀 DATA TYPES 🎀

• comment() :: string().
• emu_args() :: string(). — literally any arguments that should be passed to erl when starting. that's it, that's the vibe.
• extract_option() :: compile_source | {section, [section_name()]}.
• section() ::

shebang |
{shebang, shebang() | default | undefined} |
comment |
{comment, comment() | default | undefined} |
{emu_args, emu_args() | undefined} |
{source, file:filename() | binary()} |
{beam, file:filename() | binary()} |
{archive, zip:filename() | binary()} |
{archive, [zip_file()], [zip:create_option()]}.

• section_name() :: shebang | comment | emu_args | body.
• shebang() :: string(). — this one is the initial #! line. iconic. for example:

#!/usr/bin/env escript

• zip_file() ::

zip:filename() |
{zip:filename(), binary()} |
{zip:filename(), binary(), file:file_info()}.

---

✨ FUNCTIONS ✨

🌈 create/2

create(file:filename() | binary(), [section()]) ->
                ok | {ok, binary()} | {error, term()}.

so this one creates an escript from a list of sections. the main character of the module fr fr 👑

The sections can be specified in any order. An escript begins with an optional Header followed by a mandatory Body. If the header is present, it does always begin with a shebang, possibly followed by a comment and emu_args. The shebang defaults to "/usr/bin/env escript". The comment defaults to "This is an -*- erlang -*- file". The created escript can either be returned as a binary or written to file.

As an example of how the function can be used, we create an interpreted escript that uses emu_args to set some emulator flag. In this case, it happens to set number of schedulers with +S3. We also extract the different sections from the newly created script:

> Source = "%% Demo\nmain(_Args) ->\n    io:format(\"~p\",[erlang:system_info(schedulers)]).\n".
"%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(schedulers)).\n"
> io:format("~s\n", [Source]).
%% Demo
main(_Args) ->
    io:format(erlang:system_info(schedulers)).

ok
> {ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "+S3"},
                                      {source, list_to_binary(Source)}]).
{ok,<<"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!+S3"...>>}
> file:write_file("demo.escript", Bin).
ok
> os:cmd("escript demo.escript").
"3"
> escript:extract("demo.escript", []).
{ok,[{shebang,default}, {comment,default}, {emu_args,"+S3"},
     {source,<<"%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(schedu"...>>}]}

An escript without header can be created as follows:

> file:write_file("demo.erl",
                  ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).
ok
> {ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).
{ok,demo,
    <<70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0,
      79,0,0,0,9,4,100,...>>}
> escript:create("demo.beam", [{beam, BeamCode}]).
ok
> escript:extract("demo.beam", []).
{ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined},
     {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116,
             111,109,0,0,0,83,0,0,0,9,...>>}]}
> os:cmd("escript demo.beam").
"true"

Here we create an archive script containing both Erlang code and Beam code, then we iterate over all files in the archive and collect their contents and some information about them:

> {ok, SourceCode} = file:read_file("demo.erl").
{ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}
> escript:create("demo.escript",
                 [shebang,
                  {archive, [{"demo.erl", SourceCode},
                             {"demo.beam", BeamCode}], []}]).
ok
> {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined},
     {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
{ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined},
     {{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
                152,61,93,107,0,0,0,118,0,...>>}]}
> file:write_file("demo.zip", ArchiveBin).
ok
> zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").
{ok,[{"demo.beam",
      {file_info,748,regular,read_write,
                 {{2010,3,2},{0,59,22}},
                 {{2010,3,2},{0,59,22}},
                 {{2010,3,2},{0,59,22}},
                 54,1,0,0,0,0,0},
      <<70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0,
        83,0,0,...>>},
     {"demo.erl",
      {file_info,118,regular,read_write,
                 {{2010,3,2},{0,59,22}},
                 {{2010,3,2},{0,59,22}},
                 {{2010,3,2},{0,59,22}},
                 54,1,0,0,0,0,0},
      <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}

---

🦋 extract/2

extract(file:filename(), [extract_option()]) ->
                 {ok, [section()]} | {error, term()}.

Parses an escript and extracts its sections. Bestie this is literally the reverse of create/2 — the un-doing, the remix, the receipts 🧾

All sections are returned even if they do not exist in the escript. If a particular section happens to have the same value as the default value, the extracted value is set to the atom default. If a section is missing, the extracted value is set to the atom undefined.

Option compile_source only affects the result if the escript contains source code. In this case the Erlang code is automatically compiled and {source, BeamCode} is returned instead of {source, SourceCode}.

Example:

> escript:create("demo.escript",
                 [shebang, {archive, [{"demo.erl", SourceCode},
                                      {"demo.beam", BeamCode}], []}]).
ok
> {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined},
     {archive, ArchiveBin}]} =
          escript:extract("demo.escript", []).
{ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
                152,61,93,107,0,0,0,118,0,...>>}
     {emu_args,undefined}]}

---

🍓 script_name/0

script_name() -> string().

Returns the name of the escript that is executed. 🏷️

⚠️ okay so heads up: if the function is invoked outside the context of an escript, the behavior is undefined. not a vibe. don't do it.

---

👑 SEE ALSO 👑

no cap, there's no SEE ALSO section on this page — that's the whole thing, bestie 💜

---

this manual page was served to you by Ericsson AB, covering stdlib 8.0.4, filed under escript(3) — and yes, that's the date-and-version energy, so mwah, stan, periodt 💅✨🎀