# Input

## Reading a Complete File

### `Read(name): MonStgElt -> MonStgElt`

Returns the contents of the file named *name* as a string. Note that *name* may be an expression returning a string.

### `ReadBinary(name): MonStgElt -> BStgElt`

Returns the contents of the file named *name* as a binary string.

### `Example: Read (ex-63220d)`

In this example we show how `Read` can be used to import the complete output from a separate C program into a Magma session. We assume that a file `mystery.c` (the contents of which are shown below) is present in the current directory. We first compile it, from within Magma, and then use it to produce output for the Magma version of our `mystery` function.

```magma
> Read("mystery.c");
#include <stdio.h>

main(argc, argv)
int     argc;
char    **argv;
{
    int n, i;

    n = atoi(argv[1]);

    for (i = 1; i <= n; i++)
        printf("%d\\n", i * i);

    return 0;
}
> System("cc mystery.c -o mystery");
> mysteryMagma := function(n)
>    System("./mystery " cat IntegerToString(n) cat " >outfile");
>    output := Read("outfile");
>    return StringToIntegerSequence(output);
> end function;
> mysteryMagma(5);
[ 1, 4, 9, 16, 25 ]

```

## Reading Command Output

The intrinsics in this section are not currently available on Windows platforms. This will be addressed in a future release.

### `Pipe(cmd, input): MonStgElt, MonStgElt -> MonStgElt`

Given a shell command *cmd* and an input string *input*, run *cmd* in a new process with *input* as its input and return the output of this command as a string. Note that for many commands, *input* should finish with a new line character if it consists of only one line.

### `Pipe(cmds, inputs): SeqEnum, SeqEnum -> SeqEnum`

Given a sequence of shell commands *cmds* and a sequence of input strings *inputs*, run each command in *cmds* in a new process with the corresponding element of *inputs* as its input. Returns the sequence of outputs (as strings) of the commands.

### `Example: Pipe (ex-b6f57d)`

We revisit the `mystery` program from the earlier example on file reading. Using a pipe means that we no longer need a temporary file.

```magma
> mysteryMagma := function(n)
>    cmd := Sprintf("./mystery %o", n);
>    output := Pipe(cmd, "");
>    return StringToIntegerSequence(output);
> end function;
> mysteryMagma(5);
[ 1, 4, 9, 16, 25 ]

```

### `Example: Pipes (ex-7c1133)`

In this example, we use external commands to apply alphabetic shifts to input words. First, we write a function of $n$ to return the appropriate command to (cyclically) shift each letter forward $n$ places in the alphabet. The UNIX `tr` command is used for this purpose.

```magma
> letters := "abcdefghijklmnopqrstuvwxyz";
> shiftcmd := func<n | Sprintf("tr 'a-z' '%o-za-%o'", letters[n+1], letters[n])>;

```

Then we form the commands for shifting by amounts from 1 to 13 and apply them to some well-chosen inputs.

```magma
> cmds := [ shiftcmd(n) : n in [1..13] ];
> inputs :=
> [
>     "steeds", "pyic", "dolt", "pecan", "fizzy", "fusion", "inkier", "talk",
>     "sleep", "cubed", "spots", "road", "nowhere"
> ];
> Pipe(cmds, inputs);
[ tuffet, rake, grow, tiger, kneed, layout, purply, bits, bunny, melon, dazed,
damp, abjurer ]

```

## Interactive Input

### `read identifier;`

### `read identifier, prompt;`

This statement will cause Magma to assign to the given identifier the string of characters appearing (at run-time) on the following line. This allows the user to provide an input string at run-time. If the optional prompt is given (a string), that is printed first.

### `readi identifier;`

### `readi identifier, prompt;`

This statement will cause Magma to assign to the given identifier the literal integer appearing (at run-time) on the following line. This allows the user to specify integer input at run-time. If the optional prompt is given (a string), that is printed first.