# Elixir v1.10.3 StringIO View Source

Controls an IO device process that wraps a string.

A `StringIO` IO device can be passed as a "device" to most of the functions in the `IO` module.

## Examples

    iex> {:ok, pid} = StringIO.open("foo")
    iex> IO.read(pid, 2)
    "fo"

# Link to this section Summary

## Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

close(pid)

Stops the IO device and returns the remaining input/output buffers.

contents(pid)

Returns the current input/output buffers for the given IO device.

flush(pid)

Flushes the output buffer and returns its current contents.

open(string, options_or_function \\ [])

Creates an IO device.

open(string, options, function)

Creates an IO device.

# Link to this section Functions

Link to this function

# child_spec(init_arg)

View Source

Returns a specification to start this module under a supervisor.

See `Supervisor`.

Link to this function

# close(pid)

View Source

## Specs

    close(pid()) :: {:ok, {binary(), binary()}}

Stops the IO device and returns the remaining input/output buffers.

## Examples

    iex> {:ok, pid} = StringIO.open("in")
    iex> IO.write(pid, "out")
    iex> StringIO.close(pid)
    {:ok, {"in", "out"}}

Link to this function

# contents(pid)

View Source

## Specs

    contents(pid()) :: {binary(), binary()}

Returns the current input/output buffers for the given IO device.

## Examples

    iex> {:ok, pid} = StringIO.open("in")
    iex> IO.write(pid, "out")
    iex> StringIO.contents(pid)
    {"in", "out"}

Link to this function

# flush(pid)

View Source

## Specs

    flush(pid()) :: binary()

Flushes the output buffer and returns its current contents.

## Examples

    iex> {:ok, pid} = StringIO.open("in")
    iex> IO.write(pid, "out")
    iex> StringIO.flush(pid)
    "out"
    iex> StringIO.contents(pid)
    {"in", ""}

Link to this function

# open(string, options_or_function \\ [])

View Source

## Specs

    open(binary(), keyword()) :: {:ok, pid()}

    open(binary(), (pid() -> res)) :: {:ok, res} when res: var

Creates an IO device.

`string` will be the initial input of the newly created device.

`options_or_function` can be a keyword list of options or a function.

If options are provided, the result will be `{:ok, pid}`, returning the IO device created. The option `:capture_prompt`, when set to `true`, causes prompts (which are specified as arguments to `IO.get*` functions) to be included in the device's output.

If a function is provided, the device will be created and sent to the function. When the function returns, the device will be closed. The final result will be a tuple with `:ok` and the result of the function.

## Examples

    iex> {:ok, pid} = StringIO.open("foo")
    iex> IO.gets(pid, ">")
    "foo"
    iex> StringIO.contents(pid)
    {"", ""}

    iex> {:ok, pid} = StringIO.open("foo", capture_prompt: true)
    iex> IO.gets(pid, ">")
    "foo"
    iex> StringIO.contents(pid)
    {"", ">"}

    iex> StringIO.open("foo", fn pid ->
    ...>   input = IO.gets(pid, ">")
    ...>   IO.write(pid, "The input was #{input}")
    ...>   StringIO.contents(pid)
    ...> end)
    {:ok, {"", "The input was foo"}}

Link to this function

# open(string, options, function)

View Source (since 1.7.0)

## Specs

    open(binary(), keyword(), (pid() -> res)) :: {:ok, res} when res: var

Creates an IO device.

`string` will be the initial input of the newly created device.

The device will be created and sent to the function given. When the function returns, the device will be closed. The final result will be a tuple with `:ok` and the result of the function.

## Options

- `:capture_prompt` - if set to `true`, prompts (specified as arguments to `IO.get*` functions) are captured in the output. Defaults to `false`.

- `:encoding` (since v1.10.0) - encoding of the IO device. Allowed values are `:unicode` (default) and `:latin1`.

## Examples

    iex> StringIO.open("foo", [], fn pid ->
    ...>   input = IO.gets(pid, ">")
    ...>   IO.write(pid, "The input was #{input}")
    ...>   StringIO.contents(pid)
    ...> end)
    {:ok, {"", "The input was foo"}}

    iex> StringIO.open("foo", [capture_prompt: true], fn pid ->
    ...>   input = IO.gets(pid, ">")
    ...>   IO.write(pid, "The input was #{input}")
    ...>   StringIO.contents(pid)
    ...> end)
    {:ok, {"", ">The input was foo"}}