Class: Hackmac::Graph::Display

Inherits:
Object
  • Object
show all
Defined in:
lib/hackmac/graph/display.rb

Overview

A terminal display class that manages a grid of colored cells with ANSI styling support

The Display class provides functionality for creating and managing terminal-based visual displays It handles cell-level rendering with support for colors, background colors, and text styles The class maintains internal state for cursor position and formatting attributes while providing methods to manipulate individual cells and render complete display grids to the terminal

Examples:

display = Hackmac::Graph::Display.new(24, 80)
# Creates a 24x80 character display grid for terminal rendering

Defined Under Namespace

Classes: Cell

Constant Summary collapse

ANSI = 
Term::ANSIColor

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(lines, columns) ⇒ Display

The initialize method sets up a Display instance by configuring its grid dimensions and initializing internal state

This method creates a display grid with the specified number of lines and columns, establishing the boundaries for cell positioning. It initializes the internal ranges for lines and columns and performs an initial clear operation to set up the display buffer with default values

Parameters:

  • lines (Integer) —

    the number of lines (rows) in the display grid

  • columns (Integer) —

    the number of columns (characters per line) in the display grid



75
76
77
78
79
 
# File 'lib/hackmac/graph/display.rb', line 75

def initialize(lines, columns)
  @lines_range   = 1..lines
  @columns_range = 1..columns
  clear
end

Instance Attribute Details

#x ⇒ Integer (readonly)

The x reader method provides access to the x attribute that was set during object initialization.

This method returns the value of the x instance variable, which typically represents the horizontal coordinate or position within the display grid.

Returns:

  • (Integer) —

    the x coordinate value stored in the instance variable



199
200
201
 
# File 'lib/hackmac/graph/display.rb', line 199

def x
  @x
end

#y ⇒ Integer (readonly)

The y reader method provides access to the y attribute that was set during object initialization.

This method returns the value of the y instance variable, which typically represents the vertical coordinate or position within the display grid.

Returns:

  • (Integer) —

    the y coordinate value stored in the instance variable



208
209
210
 
# File 'lib/hackmac/graph/display.rb', line 208

def y
  @y
end

Instance Method Details

#-(old) ⇒ String

The - method calculates the difference between two display states by comparing their cells and returns a string of ANSI escape sequences that represent only the changes

This method takes another Display instance and compares it with the current display state to identify which cells have changed. It generates a minimal set of ANSI cursor movement and character output commands to redraw only the portions of the display that have changed, making terminal updates more efficient

Parameters:

Returns:

  • (String) —

    a string containing ANSI escape sequences for rendering only the changed cells



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/hackmac/graph/display.rb', line 157

def -(old)
  dimensions != old.dimensions and raise ArgumentError,
    "old dimensions #{old.dimensions.inspect} don't match #{dimensions.inspect}"
  result = +''
  each.zip(old.each) do |(my, mx, me), (_, _, old)|
    if me != old
      result << ANSI.move_to(my, mx) << me.to_s
    end
  end
  result
end

#at(y, x) ⇒ Hackmac::Graph::Display

The at method sets the cursor position within the display grid

This method updates the internal y and x coordinates to the specified position, validating that the coordinates fall within the defined grid boundaries before making the change. It enables subsequent character output operations to occur at the designated location.

Parameters:

  • y (Integer) —

    the vertical coordinate to move the cursor to

  • x (Integer) —

    the horizontal coordinate to move the cursor to

Returns:

Raises:

  • (ArgumentError) —

    raised when the y coordinate is outside the valid lines range

  • (ArgumentError) —

    raised when the x coordinate is outside the valid columns range



279
280
281
282
283
284
285
286
 
# File 'lib/hackmac/graph/display.rb', line 279

def at(y, x)
  @lines_range.include?(y) or
    raise ArgumentError, "y #{y} out of lines range #@lines_range"
  @columns_range.include?(x) or
    raise ArgumentError, "x #{x} out of columns range #@columns_range"
  @y, @x = y, x
  self
end

#attribute!(a) ⇒ Object (private)

The attribute! method validates a given value against known ANSI color attributes and raises an error if invalid

This method serves as a validation wrapper around the attribute? method, ensuring that a provided value is a recognized ANSI color attribute. If the validation fails, it raises an ArgumentError with a descriptive message indicating which value was not accepted

Parameters:

  • a (Object) —

    the value to validate as an ANSI color attribute

Returns:

  • (Object) —

    returns the validated attribute if it passes validation

Raises:

  • (ArgumentError) —

    raised when the provided value is not recognized as a valid ANSI color attribute



525
526
527
528
 
# File 'lib/hackmac/graph/display.rb', line 525

def attribute!(a)
  attribute?(a) or
    raise ArgumentError, "#{a.inspect} is not a color attribute"
end

#attribute?(a) ⇒ Object? (private)

The attribute? method checks if a given value is a valid ANSI color attribute

This method validates whether the provided input corresponds to a recognized ANSI color attribute within the Term::ANSIColor::Attribute namespace

Parameters:

  • a (Object) —

    the value to check against valid ANSI attributes

Returns:

  • (Object, nil) —

    the attribute if valid, nil otherwise



507
508
509
 
# File 'lib/hackmac/graph/display.rb', line 507

def attribute?(a)
  Term::ANSIColor::Attribute[a]
end

#bottom ⇒ Hackmac::Graph::Display

The bottom method moves the cursor position to the last line of the current column

This method sets the vertical cursor coordinate to the last line while preserving the current horizontal position. It is useful for positioning text at the bottom of the current column in terminal displays.

Returns:



355
356
357
 
# File 'lib/hackmac/graph/display.rb', line 355

def bottom
  at(lines, x)
end

#centered ⇒ Hackmac::Graph::Display

The centered method moves the cursor position to the center of the display grid

This method calculates the midpoint coordinates of the terminal display grid and positions the cursor at that location, making it convenient for centering text or other content within the available terminal space

Returns:



394
395
396
 
# File 'lib/hackmac/graph/display.rb', line 394

def centered
  at(lines / 2, columns / 2)
end

#clear ⇒ Hackmac::Graph::Display

The clear method resets the display state by initializing cursor position, color attributes, and cell contents to their default values

This method prepares the terminal display for a fresh rendering by resetting internal tracking variables such as cursor coordinates, color settings, and text styles. It also reinitializes the two-dimensional array of Cell objects that represent the display grid, filling each cell with a space character and default styling attributes

Returns:



92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/hackmac/graph/display.rb', line 92

def clear
  @x        = 1
  @y        = 1
  @color    = 15
  @on_color = 0
  @styles   = []
  @cells    =
    Array.new(lines) {
      Array.new(columns) {
        Cell.new(' ', @color, @on_color, @styles)
      }
    }
  reset
end

#color(color) ⇒ Hackmac::Graph::Display

The color method sets the text color attribute for subsequent character output

This method configures the color that will be applied to characters written to the display by updating the internal color tracking variable with a validated color attribute value

Parameters:

  • color (Integer) —

    the color index to set for subsequent text output

Returns:

Raises:

  • (ArgumentError) —

    raised when the provided color value is not a valid color attribute



441
442
443
444
 
# File 'lib/hackmac/graph/display.rb', line 441

def color(color)
  @color = attribute!(color)
  self
end

#columns ⇒ Integer

The columns method returns the number of columns in the display

This method provides access to the horizontal dimension of the graphical display by returning the total number of columns available for rendering content

Returns:

  • (Integer) —

    the number of columns (characters per line) in the display object



229
230
231
 
# File 'lib/hackmac/graph/display.rb', line 229

def columns
  @columns_range.end
end

#dimensions ⇒ Array<Integer>

The dimensions method returns the size dimensions of the display grid

This method provides access to the display’s rectangular dimensions by returning an array containing the number of lines (height) and columns (width) that define the terminal display area

Returns:

  • (Array<Integer>) —

    an array where the first element is the number of lines and the second element is the number of columns in the display grid



241
242
243
 
# File 'lib/hackmac/graph/display.rb', line 241

def dimensions
  [ lines, columns ]
end

#each {|y, x, cell| ... } ⇒ Enumerator

The each method iterates over all cells in the display grid

This method provides an iterator interface for accessing each cell in the terminal display grid by yielding the row, column, and cell object for each position in the grid

Yields:

  • (y, x, cell) —

    yields the row coordinate, column coordinate, and cell object

Returns:

  • (Enumerator) —

    an enumerator that allows iteration over all cells in the grid



133
134
135
136
137
138
139
140
141
 
# File 'lib/hackmac/graph/display.rb', line 133

def each(&block)
  Enumerator.new do |enum|
    @lines_range.each do |y|
      @columns_range.each do |x|
        enum.yield y, x, @cells[y - 1][x - 1]
      end
    end
  end.each(&block)
end

#get ⇒ Hackmac::Graph::Display::Cell

The get method retrieves the cell object at the current cursor position

This method accesses the internal two-dimensional array of Cell objects using the current vertical and horizontal cursor coordinates to return the specific cell that is currently pointed to by the cursor

Returns:



423
424
425
 
# File 'lib/hackmac/graph/display.rb', line 423

def get
  @cells[@y - 1][@x - 1]
end

#inspect ⇒ String

The inspect method returns a string representation of the display object that includes its class name along with the dimensions of the display grid

Returns:

  • (String) —

    a formatted string containing the class name and display dimensions in the format “#<ClassName: columns×lines>”



188
189
190
 
# File 'lib/hackmac/graph/display.rb', line 188

def inspect
  "#<#{self.class}: #{columns}×#{lines}>"
end

#left ⇒ Hackmac::Graph::Display

The left method moves the cursor position to the first column of the current line

This method sets the horizontal cursor coordinate to the first column while preserving the current vertical position. It is useful for positioning text at the beginning of the current line in terminal displays

Returns:



368
369
370
 
# File 'lib/hackmac/graph/display.rb', line 368

def left
  at(y, 1)
end

#lines ⇒ Integer

The lines method returns the number of lines in the display

This method provides access to the vertical dimension of the graphical display by returning the total number of rows available for rendering content

Returns:

  • (Integer) —

    the number of lines (rows) in the display object



217
218
219
 
# File 'lib/hackmac/graph/display.rb', line 217

def lines
  @lines_range.end
end

#on_color(on_color) ⇒ Hackmac::Graph::Display

The on_color method sets the background color attribute for subsequent character output

This method configures the background color that will be applied to characters written to the display by updating the internal on_color tracking variable with a validated color attribute value

Parameters:

  • on_color (Integer) —

    the background color index to set for subsequent text output

Returns:

Raises:

  • (ArgumentError) —

    raised when the provided color value is not a valid color attribute



461
462
463
464
 
# File 'lib/hackmac/graph/display.rb', line 461

def on_color(on_color)
  @on_color = attribute!(on_color)
  self
end

#put(char) ⇒ Hackmac::Graph::Display

The put method assigns a character to the current cursor position in the display grid

This method stores a character cell at the current vertical and horizontal coordinates within the terminal display grid. It validates that the input is a single character before assigning it, ensuring that only valid characters are placed in the grid.

Parameters:

  • char (String) —

    the single character to be placed at the current cursor position

Returns:

Raises:

  • (ArgumentError) —

    raised when the provided character is not a single character



301
302
303
304
305
306
 
# File 'lib/hackmac/graph/display.rb', line 301

def put(char)
  char.size == 1 or
    raise ArgumentError, "#{char} is not single character"
  @cells[@y - 1][@x - 1] = Cell.new(char, @color, @on_color, @styles)
  self
end

#reset ⇒ Hackmac::Graph::Display

The reset method resets the display’s color and style attributes to their default values

This method reinitializes the internal color tracking variables to their default state, clearing any active styling and resetting the text color to white (15) and background color to black (0). It also clears all active text styles.

Returns:



117
118
119
120
121
122
 
# File 'lib/hackmac/graph/display.rb', line 117

def reset
  @color    = 15
  @on_color = 0
  @styles   = []
  self
end

#right ⇒ Hackmac::Graph::Display

The right method moves the cursor position to the last column of the current line

This method sets the horizontal cursor coordinate to the final column while maintaining the current vertical position. It is useful for positioning text at the end of the current line in terminal displays

Returns:



381
382
383
 
# File 'lib/hackmac/graph/display.rb', line 381

def right
  at(y, columns)
end

#style?(s) ⇒ Boolean (private)

The style? method checks whether a given symbol is a valid text styling attribute

This method verifies if the provided symbol corresponds to one of the supported text styles that can be applied to terminal output, such as bold, italic, underline, and other formatting options

Parameters:

  • s (Symbol) —

    the symbol to check against the list of valid styles

Returns:

  • (Boolean) —

    true if the symbol is a recognized text style, false otherwise



479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
 
# File 'lib/hackmac/graph/display.rb', line 479

def style?(s)
  [
    :bold,
    :dark,
    :faint,
    :italic,
    :underline,
    :underscore,
    :blink,
    :rapid_blink,
    :reverse,
    :negative,
    :concealed,
    :conceal,
    :strikethrough,
  ].member?(s)
end

#styled(*s) ⇒ Hackmac::Graph::Display

The styled method sets the text styles for subsequent character output

This method configures the styling attributes that will be applied to characters written to the display, such as bold, italic, underline, and other text formatting options. It validates that all provided style names are recognized before applying them.

Parameters:

  • s (Array<Symbol>) —

    an array of style symbols to apply

Returns:

Raises:

  • (ArgumentError) —

    raised when any of the provided style symbols is not recognized



257
258
259
260
261
262
263
 
# File 'lib/hackmac/graph/display.rb', line 257

def styled(*s)
  if nope = s.find { !style?(_1) }
    raise ArgumentError, "#{nope} is not a style"
  end
  @styles = s
  self
end

#to_s ⇒ String

The to_s method generates a string representation of the display by iterating over all cells and constructing a formatted terminal output with ANSI escape sequences for positioning and styling

Returns:

  • (String) —

    a complete terminal display string with all cells rendered using their visual attributes and positioned according to their coordinates in the grid



176
177
178
179
180
 
# File 'lib/hackmac/graph/display.rb', line 176

def to_s
  each.inject(ANSI.clear_screen)  do |s, (y, x, c)|
    s << ANSI.move_to(y, x) << c.to_s
  end
end

#top ⇒ Hackmac::Graph::Display

The top method moves the cursor position to the first line of the current column

This method sets the vertical cursor coordinate to the first line while preserving the current horizontal position It is useful for positioning text at the top of the current column in terminal displays

Returns:



342
343
344
 
# File 'lib/hackmac/graph/display.rb', line 342

def top
  at(1, x)
end

#write(string) ⇒ Hackmac::Graph::Display

The write method outputs a string character by character within the display grid

This method takes a string and writes it to the current cursor position in the terminal display, advancing the cursor position after each character is written. It handles line wrapping by stopping when reaching the end of the row.

Parameters:

  • string (String) —

    the string to be written to the display

Returns:



320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/hackmac/graph/display.rb', line 320

def write(string)
  string.each_char do |char|
    put(char)
    if x < columns - 1
      at(y, x + 1)
    else
      break
    end
  end
  self
end

#write_centered(string) ⇒ Hackmac::Graph::Display

The write_centered method positions the cursor at the horizontal center of the display grid and writes a string there

This method calculates the starting column position needed to center the given string within the current display width, moves the cursor to that position, and then writes the string character by character. It is useful for creating centered text output in terminal displays.

Parameters:

  • string (String) —

    the text string to be written and centered on the current line

Returns:



411
412
413
 
# File 'lib/hackmac/graph/display.rb', line 411

def write_centered(string)
  at(@y, (columns - string.size) / 2).write(string)
end