realbook

# Running a realbook

In order to run a realbook, you must do four things.  It's probably a good
idea to wrap all of these steps in a single Task, and place that task
in a supervision tree.

## External mode

1. Specify the realbook directory.  This is global, and can be set at
  compile time using the `Config.config/2` directive in your `config.exs`
  or child configuration files.
  ```elixir
  Application.put_env(:realbook, :script_dir, realbook_script_dir)
  ```
  If you're going to release your app to prod, it's recommended to
  keep these scripts in the `priv` directory.

2. Connect to the target.  The following example shows how to connect
  with passwordless ssh.  For other options, see `SSH.connect/2`:
  ```elixir
  Realbook.connect!(:ssh, host: "my_host", user: "admin")
  ```
  Note that the `:local` connect target is also provided.


3. Set required variables.  If you forget any, the realbook won't execute.
  ```elixir
  Realbook.set(foo: "bar", baz: "quux")
  ```

4.  Launch the realbook.
  ```elixir
  Realbook.run("my_realbook_script.exs")
  ```

## Inline mode

Steps 1-3 are the same as above.

Instead of launching the realbook by file, use `Realbook.sigil_B/2`
to run an inline realbook.

```elixir
def run_realbook do
  ~B"""
  verify false
  play do
    # my code
  end
  """
end
```

This is especially useful if you are using `requires` to batch groups
of realbooks.

```elixir
def run_realbook do
  ~B"""
  requires ["my_realbook1", "my_realbook2", "my_realbook3"]
  """
end
```