# `Owl.Box`
[🔗](https://github.com/fuelen/owl/blob/v0.13.1/lib/owl/box.ex#L1)

Wraps data in boxes.

# `new`

```elixir
@spec new(Owl.Data.t(),
  padding: non_neg_integer(),
  padding_x: non_neg_integer(),
  padding_y: non_neg_integer(),
  padding_top: non_neg_integer(),
  padding_bottom: non_neg_integer(),
  padding_right: non_neg_integer(),
  padding_left: non_neg_integer(),
  min_height: non_neg_integer(),
  min_width: non_neg_integer(),
  max_width: non_neg_integer() | :infinity,
  horizontal_align: :left | :center | :right,
  vertical_align: :top | :middle | :bottom,
  border_style: :solid | :solid_rounded | :double | :none,
  border_tag: Owl.Data.sequence() | [Owl.Data.sequence()],
  word_wrap: :normal | :break_word,
  truncate_lines: boolean(),
  title: nil | Owl.Data.t()
) :: Owl.Data.t()
```

Wraps data into a box.

## Options
* `:padding` - sets the padding area for all four sides at once.  Defaults to 0.
* `:padding_x` - sets `:padding_right` and `:padding_left` at once. Overrides value set by `:padding`. Defaults to 0.
* `:padding_y` - sets `:padding_top` and `:padding_bottom` at once. Overrides value set by `:padding`. Defaults to 0.
* `:padding_top` - sets the padding area for top side. Overrides value set by `:padding_y` or `:padding`.  Defaults to 0.
* `:padding_bottom` - sets the padding area for bottom side. Overrides value set by `:padding_y` or `:padding`. Defaults to 0.
* `:padding_right` - sets the padding area for right side. Overrides value set by `:padding_x` or `:padding`. Defaults to 0.
* `:padding_left` - sets the padding area for left side. Overrides value set by `:padding_x` or `:padding`. Defaults to 0.
* `:min_height` - sets the minimum height of the box, including paddings and the border size. Defaults to 0.
* `:min_width` - sets the minimum width of the box, including paddings and the border size. Defaults to 0.
* `:max_width` - sets the maximum width of the box, including paddings and the border size. Defaults to the terminal width if available; otherwise `:infinity`.
* `:horizontal_align` - sets the horizontal alignment of the content inside the box. Defaults to `:left`.
* `:vertical_align` - sets the vertical alignment of the content inside the box. Defaults to `:top`.
* `:border_style` - sets the border style. Defaults to `:solid`.
* `:border_tag` - sets the tag for border characters. See `t:Owl.Data.sequence/0` for valid sequences. Defaults to `[]`.
* `:title` - sets a title that is displayed in a top border. Ignored if `:border_style` is `:none`. Defaults to `nil`.
* `:word_wrap` - sets the word wrapping mode. Can be `:break_word` or `:normal`. Defaults to `:break_word`. Ignored if `:truncate_lines` is `true`.
* `:truncate_lines` - specifies whether to truncate lines that are too long to fit into a box. Defaults to `false`.

## Examples

    iex> "Owl" |> Owl.Box.new() |> to_string()
    """
    ┌───┐
    │Owl│
    └───┘
    """ |> String.trim_trailing()

    iex> "Owl" |> Owl.Box.new(padding_x: 4) |> to_string()
    """
    ┌───────────┐
    │    Owl    │
    └───────────┘
    """ |> String.trim_trailing()

    iex> "Hello\nworld!"
    ...> |> Owl.Box.new(
    ...>   title: "Greeting!",
    ...>   min_width: 20,
    ...>   horizontal_align: :center,
    ...>   border_style: :double
    ...> )
    ...> |> to_string()
    """
    ╔═Greeting!════════╗
    ║      Hello       ║
    ║      world!      ║
    ╚══════════════════╝
    """ |> String.trim_trailing()

    iex> "Success"
    ...> |> Owl.Box.new(
    ...>   min_width: 20,
    ...>   min_height: 3,
    ...>   border_style: :none,
    ...>   horizontal_align: :right,
    ...>   vertical_align: :bottom
    ...> )
    ...> |> to_string()
    """
                        
                        
                 Success
    """ |> String.trim_trailing()

    iex> "OK"
    ...> |> Owl.Box.new(min_height: 5, vertical_align: :middle)
    ...> |> to_string()
    """
    ┌──┐
    │  │
    │OK│
    │  │
    └──┘
    """ |> String.trim_trailing()

    iex> "VeryLongLine" |> Owl.Box.new(max_width: 6) |> to_string()
    """
    ┌────┐
    │Very│
    │Long│
    │Line│
    └────┘
    """ |> String.trim_trailing()

    iex> "VeryLongLine" |> Owl.Box.new(max_width: 4, border_style: :none) |> to_string()
    """
    Very
    Long
    Line
    """ |> String.trim_trailing()

    iex> "Green!"
    ...> |> Owl.Data.tag(:green)
    ...> |> Owl.Box.new(title: Owl.Data.tag("Red!", :red))
    ...> |> Owl.Data.tag(:cyan)
    ...> |> Owl.Data.to_chardata()
    ...> |> to_string()
    """
    \e[36m┌─\e[31mRed!\e[36m────┐\e[39m
    \e[36m│\e[32mGreen!\e[36m   │\e[39m
    \e[36m└─────────┘\e[39m\e[0m
    """ |> String.trim_trailing()

    iex> "Hello\nworld!"
    ...> |> Owl.Box.new(
    ...>   min_width: 20,
    ...>   horizontal_align: :center,
    ...>   border_style: :double,
    ...>   border_tag: :cyan
    ...> )
    ...> |> Owl.Data.to_chardata()
    ...> |> to_string()
    """
    \e[36m╔\e[39m\e[36m══════════════════\e[39m\e[36m╗\e[39m
    \e[36m║\e[39m      Hello       \e[36m║\e[39m
    \e[36m║\e[39m      world!      \e[36m║\e[39m
    \e[36m╚\e[39m\e[36m══════════════════\e[39m\e[36m╝\e[39m\e[0m
    """ |> String.trim_trailing()

    iex> "Hello\nworld!"
    ...> |> Owl.Box.new(
    ...>   title: "Greeting!",
    ...>   min_width: 20,
    ...>   horizontal_align: :center,
    ...>   border_style: :double,
    ...>   border_tag: :cyan
    ...> )
    ...> |> Owl.Data.to_chardata()
    ...> |> to_string()
    """
    \e[36m╔\e[39m\e[36m═\e[39mGreeting!\e[36m════════\e[39m\e[36m╗\e[39m
    \e[36m║\e[39m      Hello       \e[36m║\e[39m
    \e[36m║\e[39m      world!      \e[36m║\e[39m
    \e[36m╚\e[39m\e[36m══════════════════\e[39m\e[36m╝\e[39m\e[0m
    """ |> String.trim_trailing()

---

*Consult [api-reference.md](api-reference.md) for complete listing*