View Source ExTerm.Console.Update (ex_term v0.2.0)

struct describing console changes. These updates will be broadcast to liveviews (or any other processes) that listen in console updates.

Typically this update will be automatically issued by Console functions, but the struct is documented here so that receiving processes can be aware of what messages are coming in.

Link to this section Summary

Types

t()

struct which describes the update information

Functions

records changing the cursor into update.

obtains the cells from a console datastructure corresponding to the :changes field.

identifies if a term is a end_range/0

identifies if a term is a t:Console.location/0

identifies if a term is a cell_range/0

merges an update struct into the merge struct that is waiting in the process dictionary

To be used when tracking update changes in a custom fashion bypassing updates separate from the process dictionary.

merges the cursor location into the changes; this should be the last step before sending the update message.

adds a cell change or set of cell changes into the update that is stored in the current process dictionary.

records a range to declare as the insertion range

Link to this section Types

@type cell_change() :: Console.location() | cell_range() | end_range()
@type cell_changes() :: [cell_change()]
@type cell_range() :: {Console.location(), Console.location() | row_end()}
@type end_range() :: {Console.location(), :end}
@type row_end() :: {pos_integer(), :end}
@type t() :: %ExTerm.Console.Update{
  changes: cell_changes(),
  cursor: nil | ExTerm.Console.location(),
  insertion: nil | Range.t()
}

struct which describes the update information

fields

fields

  • cursor: nil if there is no change in the cursor location, new cursor t:Console.location/0 otherwise.
  • insertion: nil if no rows have been inserted, a range if the insertion has come about due to an insert_iodata instruction
  • cells: A list of changes to the console data. This is a list of one of the following types
    • single t:Console.location/0. This indicates a single location has changed.
    • location range, represented by a {begin, end} twople of t:Console.location/0. This indicates multiple consecutive locations have changed in the range between begin and end locations. This is allowed to span multiple lines.
    • location range with end-of-line, represented by a twople of t:Console.location/0 and {row, :end}. This should be used in lieu of a single location if the location is the last character on the line, OR if a location range ends at last character on the line.
    • location range with end-of-console, reppresnted by a twople of t:Console.location/0 and :end. Note that the cells should be in reverse-sorted order, and should be compacted.

Link to this section Functions

@spec change_cursor(ExTerm.Console.location()) :: :ok

records changing the cursor into update.

Does not add this into the chnages list due to the fact that the cursor may change again before the update needs to be dispatched. The cursor position may be added prior to dispatch using merge_cursor/1

obtains the cells from a console datastructure corresponding to the :changes field.

Link to this macro

is_end_range(item)

View Source (macro)

identifies if a term is a end_range/0

Optimized to distinguish between t:Console.location/0, cell_range/0, and end_range/0.

May not correctly type other terms.

iex> alias ExTerm.Console.Update
iex> Update.is_end_range({1, 2})
false
iex> Update.is_end_range({{1, 1}, {1, 2}})
false
iex> Update.is_end_range({{1, 1}, {1, :end}})
false
iex> Update.is_end_range({{1, 1}, :end})
true
Link to this macro

is_location(item)

View Source (macro)

identifies if a term is a t:Console.location/0

Optimized to distinguish between t:Console.location/0, cell_range/0, and end_range/0. May not correctly type other terms.

iex> alias ExTerm.Console.Update
iex> Update.is_location({1, 2})
true
iex> Update.is_location({{1, 1}, {1, 2}})
false
iex> Update.is_location({{1, 1}, {1, :end}})
false
iex> Update.is_location({{1, 1}, :end})
false
Link to this macro

is_range(item)

View Source (macro)

identifies if a term is a cell_range/0

Optimized to distinguish between t:Console.location/0, cell_range/0, and end_range/0.

May not correctly type other terms.

iex> alias ExTerm.Console.Update
iex> Update.is_range({1, 2})
false
iex> Update.is_range({{1, 1}, {1, 2}})
true
iex> Update.is_range({{1, 1}, {1, :end}})
true
iex> Update.is_range({{1, 1}, :end})
false
@spec merge(t()) :: :ok

merges an update struct into the merge struct that is waiting in the process dictionary

Link to this function

merge_changes(update, change)

View Source
@spec merge_changes(t(), cell_change() | cell_changes()) :: t()

To be used when tracking update changes in a custom fashion bypassing updates separate from the process dictionary.

Should always be succeeded by merge/2, which will merge these separate updates into the process dictionary

@spec merge_cursor(t()) :: t()

merges the cursor location into the changes; this should be the last step before sending the update message.

Link to this function

register_cell_change(console, cell_changes)

View Source
@spec register_cell_change(ExTerm.Console.t(), cell_change() | cell_changes()) ::
  ExTerm.Console.t()

adds a cell change or set of cell changes into the update that is stored in the current process dictionary.

@spec set_insertion(Range.t()) :: :ok

records a range to declare as the insertion range