lfe

.\" Automatically generated by Pandoc 3.5
.\"
.TH "lfe_io" "3" "2008\-2024" ""
.SH NAME
lfe_io \- Lisp Flavoured Erlang (LFE) io functions
.SH SYNOPSIS
This module provides a standard set of io functions for LFE.
In the following description, many functions have an optional parameter
IoDevice.
If included, it must be the pid of a process which handles the IO
protocols such as the IoDevice returned by file:open/2.
.PP
Two functions in this module are used to generateœ aesthetically
attractive representations of abstract forms, which are suitable for
printing.
These functions return (possibly deep) lists of characters and generate
an error if the form is wrong.
.SH DATA TYPES
\f[B]\f[CB]chars() = [char() | chars()]\f[B]\f[R]
.PP
\f[B]\f[CB]prompt() = atom() | unicode:chardata()\f[B]\f[R]
.PP
\f[B]\f[CB]filesexpr() = {Sexpr,Line}\f[B]\f[R]
.PP
This is the format returned by \f[CR]lfe_io:parse_file/1\f[R] and is
used by the compiler to give better error information.
.SH EXPORTS
\f[B]\f[CB]get_line() \-> Data | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
\f[B]\f[CB]get_line(Prompt) \-> Data | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
\f[B]\f[CB]get_line(IoDevice, Prompt) \-> Data | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
Reads a line from the standard input (\f[CR]IoDevice\f[R]), prompting it
with prompt (\f[CR]Prompt\f[R]).
Note that this call guarantees that the input is saved in the input
history.
.PP
\f[B]\f[CB]read() \-> {ok, Sexpr} | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
\f[B]\f[CB]read(Prompt) \-> {ok, Sexpr} | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
\f[B]\f[CB]read(IoDevice, Prompt) \-> {ok, Sexpr} | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
Read an s\-expr from the standard input (\f[CR]IoDevice\f[R]) with a
prompt (\f[CR]Prompt\f[R]).
Note that this is not line\-oriented in that it stops as soon as it has
consumed enough characters.
.PP
\f[B]\f[CB]read_line() \-> {ok, Sexpr} | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
\f[B]\f[CB]read_line(Prompt) \-> {ok, Sexpr} | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
\f[B]\f[CB]read_line(IoDevice, Prompt) \-> {ok, Sexpr} | {error, ErrorInfo} | eof\f[B]\f[R]
.PP
Read the first s\-expr from the standard input (\f[CR]IoDevice\f[R])
with a prompt (\f[CR]Prompt\f[R]).
Note that this is line\-oriented in that it reads whole lines discarding
left\-over characters in the last line.
.PP
\f[B]\f[CB]read_string(String) \-> {ok, [Sexpr]} | {error, ErrorInfo}\f[B]\f[R]
.PP
Read all the s\-exprs from \f[CR]String\f[R].
.PP
\f[B]\f[CB]print(Sexpr) \-> ok\f[B]\f[R]
.PP
\f[B]\f[CB]print(IoDevice, Sexpr) \-> ok\f[B]\f[R]
.PP
Print the s\-expr \f[CR]Sexpr\f[R] to the standard output
(\f[CR]IoDevice\f[R]).
.PP
\f[B]\f[CB]print1(Sexpr) \-> DeepCharList\f[B]\f[R]
.PP
Return the list of characters which represent the s\-expr
\f[CR]Sexpr\f[R].
.PP
\f[B]\f[CB]prettyprint(Sexpr) \-> ok\f[B]\f[R]
.PP
\f[B]\f[CB]prettyprint(IoDevice, Sexpr) \-> ok\f[B]\f[R]
.PP
Pretty print the s\-expr \f[CR]Sexpr\f[R] to the standard output
(\f[CR]IoDevice\f[R]).
.PP
\f[B]\f[CB]prettyprint1(Sexpr) \-> DeepCharList\f[B]\f[R]
.PP
\f[B]\f[CB]prettyprint1(Sexpr, Depth) \-> DeepCharList\f[B]\f[R]
.PP
\f[B]\f[CB]prettyprint1(Sexpr, Depth, Indentation) \-> DeepCharList\f[B]\f[R]
.PP
\f[B]\f[CB]prettyprint1(Sexpr, Depth, Indentation, LineLength) \-> DeepCharList\f[B]\f[R]
.PP
Return the list of characters which represents the prettyprinted s\-expr
\f[CR]Sexpr\f[R].
Default values for \f[CR]Depth\f[R] is 30, \f[CR]Indentation\f[R] is 0
and \f[CR]LineLength\f[R] is 80.
.PP
\f[B]\f[CB]format(Format, Args) \-> ok\f[B]\f[R]
.PP
\f[B]\f[CB]format(IoDevice, Format, Args) \-> ok\f[B]\f[R]
.PP
\f[B]fwrite(Format, Args) \-> ok\f[R]
.PP
\f[B]\f[CB]fwrite(IoDevice, Format, Args) \-> ok\f[B]\f[R]
.PP
Print formatted output.
The following commands are valid in the format string:
.IP \[bu] 2
\f[B]\f[CB]\[ti]w, \[ti]W     \-\f[B]\f[R] print LFE terms
.IP \[bu] 2
\f[B]\f[CB]\[ti]p, \[ti]P     \-\f[B]\f[R] prettyprint LFE terms
.IP \[bu] 2
\f[B]\f[CB]\[ti]s         \-\f[B]\f[R] print a string
.IP \[bu] 2
\f[B]\f[CB]\[ti]e, \[ti]f, \[ti]g \-\f[B]\f[R] print floats
.IP \[bu] 2
\f[B]\f[CB]\[ti]b, \[ti]B     \-\f[B]\f[R] based integers
.IP \[bu] 2
\f[B]\f[CB]\[ti]x, \[ti]X     \-\f[B]\f[R] based integers with a prefix
.IP \[bu] 2
\f[B]\f[CB]\[ti]+, \[ti]#     \-\f[B]\f[R] based integers in vanilla
erlang format
.IP \[bu] 2
\f[B]\f[CB]\[ti]\[ti]         \-\f[B]\f[R] prints \f[CR]\[ti]\f[R]
.IP \[bu] 2
\f[B]\f[CB]\[ti]c, \[ti]n, \[ti]i\f[B]\f[R]
.PP
Currently they behave as for vanilla erlang except that
\f[CR]\[ti]w\f[R], \f[CR]\[ti]W\f[R], \f[CR]\[ti]p\f[R],
\f[CR]\[ti]P\f[R] print the terms as LFE sexprs.
.PP
\f[B]\f[CB]format1(Format, Args) \-> DeepCharList\f[B]\f[R]
.PP
\f[B]\f[CB]fwrite1(Format, Args) \-> DeepCharList\f[B]\f[R]
.PP
Return the formatted output with same arguments as
\f[CR]format\f[R]/\f[CR]fwrite\f[R].
.PP
\f[B]\f[CB]read_file(FileName|Fd) \-> {ok,[Sexpr]} | {error,ErrorInfo}\f[B]\f[R]
.PP
\f[B]\f[CB]read_file(FileName|Fd, Line) \-> {ok, [Sexpr]} | {error, ErrorInfo}\f[B]\f[R]
.PP
Read the file \f[CR]Filename\f[R] or the already opened file\[cq]s file
descriptor \f[CR]Fd\f[R] returning a list of s\-exprs.
.PP
\f[B]\f[CB]parse_file(FileName|Fd) \-> {ok, [FileSexpr]} | {error, ErrorInfo}\f[B]\f[R]
.PP
\f[B]\f[CB]parse_file(FileName|Fd, Line) \-> {ok, [FileSexpr]} | {error, ErrorInfo}\f[B]\f[R]
.PP
where
.PP
\f[B]\f[CB]FileSexpr = filesexpr()\f[B]\f[R]
.PP
Read the file \f[CR]Filename\f[R] or the already opened file\[cq]s file
descriptor \f[CR]Fd\f[R] returning a list of pairs containing s\-expr
and line number of the start of the s\-expr.
.PP
\f[B]\f[CB]scan_sexpr(Cont, Chars) \-> {done, Ret, RestChars} | {more, Cont1}\f[B]\f[R]
.PP
\f[B]\f[CB]scan_sexpr(Cont, Chars, Line) \-> {done, Ret, RestChars} | {more, Cont1}\f[B]\f[R]
.PP
This is a re\-entrant call which scans tokens from the input and returns
a parsed sepxr.
If there are enough characters to parse a sexpr or it detects and error
then it returns \f[CR]{done,...}\f[R] otherwise it returns
\f[CR]{more,Cont}\f[R] where \f[CR]Cont\f[R] is used in the next call to
\f[CR]scan_sexpr\f[R] with more characters to try and parse a sexpr.
This is continued until a sexpr has been parsed.
\f[CR]Cont\f[R] is initially \f[CR][]\f[R].
.PP
It is not designed to be called directly by an application but used
through the i/o system where it can typically be called in an
application by:
.PP
\f[CR]io:request(In, {get_until,unicode,Prompt,Module,scan_sexpr,[Line]})\f[R]
.SH ERROR INFORMATION
The \f[CR]ErrorInfo\f[R] mentioned above is the standard
\f[CR]ErrorInfo\f[R] structure which is returned from all IO modules.
It has the following format:
.PP
\f[B]\f[CB]{ErrorLine, Module, ErrorDescriptor}\f[B]\f[R]
.PP
A string describing the error is obtained with the following call:
.IP
.EX
apply(Module, format_error, ErrorDescriptor)
.EE
.SH AUTHORS
Robert Virding.