neo_faker

defmodule NeoFaker.Boolean do
  @moduledoc """
  Functions for generating random boolean values.

  Provides utilities to generate `true` or `false` with a configurable probability,
  with an option to return integer equivalents instead.
  """
  @moduledoc since: "0.5.0"

  alias NeoFaker.Boolean.Generator
  alias NeoFaker.Helpers.Formatter
  alias NeoFaker.Helpers.Options

  @ratio_range 0..100

  @doc """
  Generates a random boolean value with a configurable probability of returning `true`.

  The `true_ratio` parameter sets the percentage chance (0–100) of returning `true`.
  Pass `integer: true` to receive `1` or `0` instead of `true` or `false`.

  ## Parameters

  - `true_ratio` - Percentage probability of returning `true` (0–100). Defaults to `50`.
  - `opts` - Keyword list of options:
    - `:integer` - When `true`, returns `1` or `0`. Defaults to `false`.

  ## Examples

      iex> NeoFaker.Boolean.boolean()
      false

      iex> NeoFaker.Boolean.boolean(75)
      true

      iex> NeoFaker.Boolean.boolean(75, integer: true)
      1

      iex> NeoFaker.Boolean.boolean(0)
      false

      iex> NeoFaker.Boolean.boolean(100)
      true

  """
  @spec boolean(0..100, Keyword.t()) :: boolean() | non_neg_integer()
  def boolean(true_ratio \\ 50, opts \\ [])

  def boolean(true_ratio, opts) when true_ratio in @ratio_range do
    result = Generator.boolean(true_ratio)

    if Options.get(opts, :integer, false) do
      Formatter.format_boolean(result, :integer)
    else
      result
    end
  end

  def boolean(true_ratio, _opts) do
    raise ArgumentError, "true_ratio must be between 0 and 100, got: #{true_ratio}"
  end
end