<sect1><title>Input and Output</title>
<para>
Input and output in Nickle are mostly accomplished through the File builtin namespace; some top-level builtins refer to those functions.
Nickle's input and output are modeled, as much of the language is, on C, but many changes have been made.
</para>

<sect2><title>Opening and closing files</title>
<para>
The functions in the File namespace use the <literal>file</literal> primitive type to describe filehandles.
Three are predefined, with their usual meanings: <literal>stdin</literal>, <literal>stdout</literal>, and <literal>stderr</literal>.
For many functions in File, there is a top-level builtin which assumes one of these standard streams.
Other files may be read and written by opening them:
</para>
<synopsis>
file open(string path, string mode)
</synopsis>
<para>
The first string gives the path to the file to be opened; the second is one of:
</para>
<itemizedlist>
<listitem><para>"r" to open read-only, starting at the beginning of the file.</para></listitem>
<listitem><para>"r+" to open read-write, starting at the beginning of the file.</para></listitem>
<listitem><para>"w" to create or truncate the file and open write-only.</para></listitem>
<listitem><para>"w+" to create or truncate the file and open read-write.</para></listitem>
<listitem><para>"a" to open write-only, appending to the end of the file.</para></listitem>
<listitem><para>"a+" to open read-write, appending to the end of the file.</para></listitem>
</itemizedlist>
<para>
If successful, a filehandle will be returned that can then be used.
</para>
<para>
Nickle can also open pipes to other programs, reading or writing to their stdouts or stdins; these are also treated as <literal>file</literal>s, and the difference is transparent to the functions that manipulate them.
Pipes are opened with <literal>pipe</literal> rather than <literal>open</literal>; otherwise they are treated identically to flat files.
</para>
<synopsis>
file pipe(string path, string[*] argv, string mode)
</synopsis>
<para>
The first string refers to the program to be run; <literal>argv</literal> is an array of the arguments to pass to it.
By convention, <literal>argv[0]</literal> should be the name of the program.
Finally, <literal>mode</literal> is one of those for <literal>open</literal>; reading from the pipe reads from the program's stdout, and writing to the pipe writes to the program's stdin.
For example,
<informalexample><screen>
$ nickle
> string[*] args = {"-a"};
> file ls = File::pipe ( "ls", args, "r" );
> do printf ( "%s\n", File::fgets ( ls ) );
+ while ( ! File::end ( ls ) );
bin
man
nickle
share
</screen></informalexample>
</para>
<para>
When a file is no longer needed, it should be closed.
</para>
<synopsis>
void close(file f)
</synopsis>
<informalexample><screen>
> File::close ( ls );
</screen></informalexample>
</sect2>

<sect2><title>Flush</title>
<para>
Output written to a file is not immediately written, but buffered until an appropriate time.
Ordinarily, this is not noticed; if, however, it is important to know that all buffers have been written to a file, they can be flushed:
</para>
<synopsis>
void flush (file f)
</synopsis>
</sect2>

<sect2><title>End</title>
<para>
Returns true if the file is at end-of-file, otherwise returns false.
</para>
<synopsis>
bool end (file f)
</synopsis>
</sect2>

<sect2><title>Characters and strings</title>
<para>
Individual characters can be read and written using <literal>getc</literal>, <literal>getchar</literal>, <literal>putc</literal>, and <literal>putchar</literal>.
</para>
<synopsis>
int getc(file f)
</synopsis>
<synopsis>
int getchar()
</synopsis>
<synopsis>
int putc(int c,file f)
</synopsis>
<synopsis>
void putchar(int c)
</synopsis>
<para>
A character can be pushed back onto the stream with <literal>ungetc</literal> or <literal>ungetchar</literal>.
</para>
<synopsis>
int ungetc(int c, file f)
</synopsis>
<synopsis>
int ungetchar(int c)
</synopsis>
<para>
Strings can be read, a line at a time, using <literal>fgets</literal> and <literal>gets</literal>.
</para>
<synopsis>
string fgets(file f)
</synopsis>
<synopsis>
string gets()
</synopsis>
<para>
All of these are like their C counterparts, with the exception noted in the following section.
</para>
</sect2>

<sect2><title>Unicode and characters vs. bytes</title>
<para>
Unicode is a standard for representing characters, like ASCII.
However, Unicode is designed to be able to support a much larger range of characters; in fact, every character in every alphabet worldwide.
It is optimized so standard ASCII characters retain their ASCII codes, and characters are not larger than they have to be.
Because of its advantages, and the possibility that it may become more standard than ASCII, and because there is no reason not to, Nickle reads and writes Unicode.
This is entirely transparent to the user/programmer.
</para>
<para>
However, there is one situation in which the programmer will notice (disregarding the case where the programmer finds himself typing on a Sanskrit keyboard): extended characters that do not stand for themselves the same in ASCII and Unicode are <emphasis>not</emphasis> one byte long; they can be as many as four for the really obscure characters.
Therefore, unlike in C, <emphasis>characters cannot be counted on to be the same as bytes</emphasis>.
For this reason, Nickle provides the following functions:
</para>
<synopsis>
int putb(int c,file f)
</synopsis>
<synopsis>
int getb(file f)
</synopsis>
<synopsis>
int ungetb(file f)
</synopsis>
<para>
These operate the same as <literal>putc</literal>, <literal>getc</literal>, and <literal>ungetc</literal>, but will always read or write one byte at a time, regardless of character representation.
</para>
</sect2>

<sect2><title>Formatted I/O</title>
<para>
Nickle provides functions such as <literal>printf</literal>, <literal>sprintf</literal>, and <literal>scanf</literal> to perform formatted input and output.
These functions perform like their C counterparts, with the following exceptions:
</para>
<itemizedlist>
<listitem><para>The precision of a field in the format string may be specified to be '-', which means infinite precision.</para></listitem>
<listitem><para>The %g format specifier requires a number, and prints it in the best way possible. For example:
<informalexample><screen>
> printf("%g %g %g\n", 1, 1/3, sqrt(2));
1 0.{3} 1.414213562373095
</screen></informalexample>
</para></listitem>
<listitem><para>
The %v format specifier will attempt to find the best way to print whatever value it is given.
This is a great way to print polys whose types will not be known ahead of time.
<informalexample><screen>
> printf("%v %v %v\n", 1/3, "hello", fork 4!);
(1/3) "hello" %38
</screen></informalexample>
Notice that it can even figure out difficult things like the thread returned by 'fork'.
</para></listitem>
</itemizedlist>
</sect2>

<sect2><title>At the top level</title>
<para>
Many functions in the File namespace have counterparts builtin at the top level; these do not need to be imported from File because they are automatically present.
</para>
<itemizedlist>
<listitem><para>int printf(string fmt, poly args...) is the same as <literal>File::printf</literal>.</para></listitem>
<listitem><para>string printf(string fmt, poly args...) is the same as <literal>File::sprintf</literal>.</para></listitem>
<listitem><para>void putchar(int c) is the same as <literal>File::putchar</literal>.</para></listitem>
</itemizedlist>
<para>
File also contains a namespace called FileGlobals, which is automatically imported.
It contains the following definitions:
<informalexample><screen>
public int scanf (string format, *poly args...)
{
        return File::vfscanf (stdin, format, args);
}

public int vscanf (string format, (*poly)[*] args)
{
        return File::vfscanf (stdin, format, args);
}    

public string gets ()
{
        return File::fgets (stdin);
}

public int getchar ()
{
        return File::getc (stdin);
}

public void ungetchar (int ch)
{
        File::ungetc (ch, stdin);
}
</screen></informalexample>
Thus, <literal>scanf</literal>, <literal>vscanf</literal>, <literal>gets</literal>, <literal>getchar</literal>, and <literal>ungetchar</literal> call the appropriate functions in File and return their results.
The other functions in File must be imported as normal.
</para>
</sect2>

</sect1>