Sheetshow.Cell (Sheetshow v0.1.6)

Copy Markdown View Source

A cell: where it is, what it holds, how it looks.

iex> Sheetshow.Cell.new("Costs!B4", 0.22, %{number_format: "0%"})
%Sheetshow.Cell{
  coord: %Sheetshow.Coord{row: 3, col: 1, sheet: "Costs"},
  value: 0.22,
  style: %{number_format: "0%"},
  meta: %{}
}

A spreadsheet is a list of these, in no particular order. Knowing cells, you know most of Sheetshow: everything else builds lists of them, moves them about, or turns them into requests.

meta is where readers put what they learned, such as the text Sheets displayed for a value, and it is yours besides. A writer looks at it only for what a reader of the same backend put there to write an untouched cell back as it was (an .xlsx cell's style index, say), and each such key is checked against the cell before it is used; the planner skips the cell Sheetshow.pad_below/2 leaves to hold room. Values and styles are checked by validate/1, which writers call, rather than on construction.

Summary

Types

t()

Functions

new(coord, value \\ nil, style \\ %{})

Builds a cell at a Sheetshow.Coord or an A1 reference (raising if the reference is malformed).

put_sheet(cell, sheet)

Puts the cell on a sheet.

put_style(cell, more)

Merges a style into the cell's, the new keys winning.

shift(cell, rows, cols)

Moves the cell by rows down and cols right; see Sheetshow.Coord.shift/3.

valid?(cell)

Whether the term is a valid cell.

validate(cell)

Checks the coordinate, value and style.

Types

t()

@type t() :: %Sheetshow.Cell{
  coord: Sheetshow.Coord.t(),
  meta: map(),
  style: Sheetshow.Style.t(),
  value: Sheetshow.Value.t()
}

Functions

new(coord, value \\ nil, style \\ %{})

@spec new(Sheetshow.Coord.t() | String.t(), Sheetshow.Value.t(), Sheetshow.Style.t()) ::
  t()

Builds a cell at a Sheetshow.Coord or an A1 reference (raising if the reference is malformed).

iex> Sheetshow.Cell.new(Sheetshow.Coord.new(0, 0), "Item")
%Sheetshow.Cell{coord: %Sheetshow.Coord{row: 0, col: 0, sheet: nil}, value: "Item", style: %{}, meta: %{}}

put_sheet(cell, sheet)

@spec put_sheet(t(), String.t() | nil) :: t()

Puts the cell on a sheet.

iex> Sheetshow.Cell.new("A1") |> Sheetshow.Cell.put_sheet("Costs") |> Map.fetch!(:coord) |> Sheetshow.Coord.to_a1()
"Costs!A1"

put_style(cell, more)

@spec put_style(t(), Sheetshow.Style.t()) :: t()

Merges a style into the cell's, the new keys winning.

iex> Sheetshow.Cell.new("A1", 1, %{bold: true})
...> |> Sheetshow.Cell.put_style(%{bold: false, italic: true})
...> |> Map.fetch!(:style)
%{bold: false, italic: true}

shift(cell, rows, cols)

@spec shift(t(), integer(), integer()) :: t()

Moves the cell by rows down and cols right; see Sheetshow.Coord.shift/3.

iex> Sheetshow.Cell.new("A1") |> Sheetshow.Cell.shift(1, 2) |> Map.fetch!(:coord) |> Sheetshow.Coord.to_a1()
"C2"

valid?(cell)

@spec valid?(term()) :: boolean()

Whether the term is a valid cell.

validate(cell)

@spec validate(term()) :: :ok | {:error, Sheetshow.Error.t()}

Checks the coordinate, value and style.

iex> Sheetshow.Cell.validate(Sheetshow.Cell.new("A1", 1, %{bold: true}))
:ok
iex> {:error, %Sheetshow.Error{reason: :invalid_style}} =
...>   Sheetshow.Cell.validate(Sheetshow.Cell.new("A1", 1, %{bold: "yes"}))