Fortune

Get a fortune!

Fortune reads a string, usually a random one, from one or more fortune files. Fortune files contain a list of strings and an associated index for for quick retrieval of a randomly chosen string. This implementation provides an Elixir take on the ubiquitous Unix fortune implementation. It is compatible with Unix fortune and can read most Unix fortune files.

iex> Fortune.random! |> IO.puts
Harness the power of the BEAM, one Elixir potion at a time.
:ok

No fortunes are provided, though. You'll need to add your own, add Elixir libraries to your mix dependencies that have fortunes, or configure Fortune to use your system ones.

An easy way to start is to install the Unix fortune program using your package manager. If no fortunes are supplied by Elixir libraries, Fortune will consult it. You can also force it using the :include_system_fortunes? option.

iex> Fortune.random!(include_system_fortunes?: true) |> IO.puts
Ignore the next fortune
:ok

Fortunes provided by Elixir libraries are stored in that library's priv/fortune directory when using this library's fortune compiler. Fortune scans for these paths by default.

Installation

Add fortune to your list of dependencies in mix.exs:

def deps do
  [
    {:fortune, "~> 0.1"}
  ]
end

Note that Fortune does NOT provide any fortunes itself.

Configuration

The defaults should be good for most users. If not, see fortune_options/0 to adjust fortune search paths and more. These can be passed to Fortune.random/1 or added to your config.exs for use as new defaults:

# Completely override fortune search paths
config :fortune, paths: [Path.join(["some/location", "fortune"])]]

# Only include fortunes from a couple applications
config :fortune, included_applications: [:funny_app, :helpful_app]

# Remove fortunes from a list of applications
config :fortune, excluded_applications: [:bad_app]

Adding fortunes to your Elixir project

Any project can supply fortunes (or tips, since that's the likely use case).

Here are the steps:

1. Create a fortune directory in your Elixir project
2. Create one or more fortune-formatted files in the fortune directory
3. Add the :fortune_compiler to the compilers list in your mix.exs
4. Run mix compile

Fortune files

Fortune files are text files with quotes separated by % lines. Filenames can be anything but must not have an extension.

It's easies to see by example:

cd path/to/my/project
mkdir -p fortune
touch fortune/my-fortunes

Then open my-fortunes in a text editor:

My first fortune
%
Another string or fortune
and this can be multiple lines too.
%
The last string

Compiling fortune files

Fortune files need to be indexed for use by fortune. The :fortune_compiler knows how to do this, so add it to your mix.exs:

  def project do
    [
      ...
      compilers: Mix.compilers() ++ [:fortune_compiler],
      ...
    ]
  end

If you don't like putting your fortunes in the fortune directory, use the :fortunec_paths option.

Finally, run:

mix deps.get
mix compile

Then to see the result of your work, run:

iex -S mix

Interactive Elixir - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> Fortune.random()
{:ok, "My first fortune"}