Class: Graphina::Graph

Inherits:
Object
  • Object
show all
Includes:
Formatters, Term::ANSIColor
Defined in:
lib/graphina/graph.rb,
lib/graphina/graph/display.rb,
lib/graphina/graph/formatters.rb

Overview

A class that provides graphical display functionality for terminal-based data visualization

The Graph class enables the creation of dynamic, real-time visualizations of data values within a terminal environment. It manages the rendering of graphical representations such as line charts or graphs, updating them continuously based on provided data sources. The class handles terminal control operations, including cursor positioning, color management, and screen clearing to ensure smooth visual updates. It also supports configuration of display parameters like title, formatting strategies for values, update intervals, and color schemes for different data series.

Examples:

graph = Graphina::Graph.new(
  title: 'CPU Usage',
  value: ->(i) { rand(100) },
  format_value: :as_percent,
  sleep: 1,
  color: 33
)
graph.start
# Starts the graphical display loop
graph = Graphina::Graph.new(
  title: 'Memory Usage',
  value: ->(i) { `vm_stat`.match(/Pages free: (\d+)/)[1].to_i },
  format_value: :as_bytes,
  sleep: 2
)
graph.start
# Starts a memory usage graph with custom data source and formatting

Defined Under Namespace

Modules: Formatters Classes: Display

Instance Method Summary collapse

Methods included from Formatters

#as_bytes, #as_celsius, #as_default, #as_hertz, #as_percent, #derive_color_from_string

Constructor Details

#initialize(title:, value: -> i { 0 }, format_value: nil, sleep: 5, true_coloring: true, color: nil, color_secondary: nil, adjust_brightness: :lighten, adjust_brightness_percentage: 15, foreground_color: :white, background_color: :black, resolution: :double) ⇒ Graph

The initialize method sets up a Graph instance by configuring its display parameters and internal state.

This method configures the graph visualization with title, value provider, formatting options, update interval, and color settings. It initializes internal data structures for storing historical values and manages synchronization through a mutex for thread-safe operations.

Parameters:

  • title (String) —

    the title to display at the bottom of the graph

  • value (Proc) (defaults to: -> i { 0 }) —

    a proc that takes an index and returns a numeric value for plotting

  • format_value (Proc, Symbol, nil) (defaults to: nil) —

    formatting strategy for displaying values

  • sleep (Numeric) (defaults to: 5) —

    time in seconds between updates

  • color (Object, Proc, nil) (defaults to: nil) —

    color or proc or nil. nil determineicolor dynamically from the title

  • color_secondary (Object, nil) (defaults to: nil) —

    secondary color or nil for enhanced visuals, nil derives secondary color from (primary) color

  • adjust_brightness (Symbol) (defaults to: :lighten) —

    the method to call on the color for brightness adjustment (:lighten or :darken), defaults to :lighten

  • adjust_brightness_percentage (Float) (defaults to: 15) —

    the percentage value to use for the brightness adjustment

  • foreground_color (Symbol) (defaults to: :white) —

    the default text color for the display

  • background_color (Symbol) (defaults to: :black) —

    the default background color for the display

  • resolution (Symbol) (defaults to: :double) —

    the resolution mode (:single or :double) for the graph display, defaults to :double.

Raises:

  • (ArgumentError) —

    if the sleep parameter is negative

  • (TypeError) —

    if the sleep parameter is not numeric

  • (ArgumentError) —

    if the resolution parameter is not :single or :double



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/graphina/graph.rb', line 73

def initialize(
  title:,
  value:                        -> i { 0 },
  format_value:                 nil,
  sleep:                        5,
  true_coloring:                true,
  color:                        nil,
  color_secondary:              nil,
  adjust_brightness:            :lighten,
  adjust_brightness_percentage: 15,
  foreground_color:             :white,
  background_color:             :black,
  resolution:                   :double
)
  @title                        = title
  @value                        = value
  @format_value                 = format_value
  sleep = Float(sleep)
  sleep >= 0 or raise ArgumentError, 'sleep has to be >= 0'
  @sleep                        = sleep
  @continue                     = false
  @data                         = []
  @color                        = color
  @color_secondary              = color_secondary
  adjust_brightness             = adjust_brightness.to_sym
  if %i[ lighten darken ].include? adjust_brightness
    @adjust_brightness          = adjust_brightness
  else
    raise ArgumentError, 'adjust_brightness required to be either :lighten or :darken'
  end
  @adjust_brightness_percentage = Float(adjust_brightness_percentage)
  @foreground_color             = foreground_color
  @background_color             = background_color
  resolution                    = resolution.to_sym
  if %i[ single double ].include? resolution
    @resolution                 = resolution
  else
    raise ArgumentError, 'resolution required to be either :single or :double'
  end
  Term::ANSIColor.true_coloring = true_coloring
  @mutex                        = Mutex.new
end

Instance Method Details

#start ⇒ Object

The start method initiates the graphical display process by setting up signal handlers, performing an initial terminal reset, and entering the main update loop

This method serves as the entry point for starting the graph visualization functionality. It configures the necessary signal handlers for graceful shutdown and terminal resizing, performs an initial full reset of the display state, and then begins the continuous loop that updates and renders graphical data.



125
126
127
128
129
 
# File 'lib/graphina/graph.rb', line 125

def start
  install_handlers
  full_reset
  start_loop
end

#stop ⇒ Object

The stop method terminates the graphical display process by performing a full reset and setting the continue flag to false

This method serves as the shutdown mechanism for the graph visualization functionality. It ensures that all display resources are properly cleaned up and the terminal state is restored to its original condition before stopping the continuous update loop.



138
139
140
141
 
# File 'lib/graphina/graph.rb', line 138

def stop
  full_reset
  @continue = false
end