curses_menu 0.0.1 → 0.0.5

data/lib/curses_menu/curses_row.rb

@@ -1,150 +1,151 @@
-class CursesMenu
-
-  # Definition of a row that stores for each cell the string and color information to be displayed
-  class CursesRow
-
-    # Constructor
-    #
-    # Parameters::
-    # * *cells* (Hash< Symbol, Hash<Symbol,Object> >): For each cell id (ordered), the cell info:
-    #   * *text* (String): Text associated to this cell
-    #   * *color_pair* (Integer): Associated color pair [optional]
-    #   * *begin_with* (String): String to prepend to the text [default: '']
-    #   * *end_with* (String): String to append to the text [default: '']
-    #   * *fixed_size* (Integer): Number of characters this cell will take, or nil if no limit. [default: nil]
-    #   * *justify* (Symbol): Text justification (only used when fixed_size is not nil). Values can be: [default: :left]
-    #     * *left*: Left justified
-    #     * *right*: Right justified
-    #   * *pad* (String): Text to be used to pad the cell content (only used when fixed_size is not nil) [default: ' ']
-    # * *separator* (String): Separator used between cells [default: ' ']
-    def initialize(cells, separator: ' ')
-      @cells = cells
-      @separator = separator
-    end
-
-    # Change the cells order
-    #
-    # Parameters::
-    # * *cells* (Array<Symbol>): The ordered list of cells to filter
-    # * *unknown_cells* (String or Hash<Symbol,Object>): Content to put in unknown cells (as a String or properties like in #initialize), or nil to not add them. [default: nil]
-    def cells_order(cells, unknown_cells: nil)
-      new_cells = {}
-      cells.each do |cell_id|
-        if @cells.key?(cell_id)
-          new_cells[cell_id] = @cells[cell_id]
-        elsif !unknown_cells.nil?
-          new_cells[cell_id] = unknown_cells.is_a?(String) ? { text: unknown_cells } : unknown_cells
-        end
-      end
-      @cells = new_cells
-    end
-
-    # Change properties of a set of cells
-    #
-    # Parameters::
-    # * *cells* (Hash<Symbol, Hash<Symbol,Object> >): The cells properties to change, per cell id. Possible properties are the ones given in the #initialize method.
-    def change_cells(cells)
-      cells.each do |cell_id, cell_info|
-        raise "Unknown cell #{cell_id}" unless @cells.key?(cell_id)
-        @cells[cell_id].merge!(cell_info)
-        @cells[cell_id].delete(:cache_rendered_text)
-      end
-    end
-
-    # Get the size of the total string of such row.
-    #
-    # Parameters::
-    # * *cells* (Array<Symbol>): The list of cells to consider for the size [default: @cells.keys]
-    # Result::
-    # * Integer: Row size
-    def size(cells: @cells.keys)
-      result = @separator.size * (cells.size - 1)
-      cells.each do |cell_id|
-        result += cell_text(cell_id).size
-      end
-      result
-    end
-
-    # Print this row into a window
-    #
-    # Parameters::
-    # * *window* (Window): Curses window to print on
-    # * *from* (Integer): From index to be displayed [default: 0]
-    # * *to* (Integer): To index to be displayed [default: total size]
-    # * *default_color_pair* (Integer): Default color pair to use if no color information is provided [default: COLORS_LINE]
-    # * *force_color_pair* (Integer): Force color pair to use, or nil to not force [default: nil]
-    # * *pad* (String or nil): Pad the line to the row extent with the given string, or nil for no padding. [default: nil]
-    # * *add_nl* (Boolean): If true, then add a new line at the end [default: true]
-    # * *single_line* (Boolean): If true, then make sure the print does not exceed the line [default: false]
-    def print_on(window, from: 0, to: nil, default_color_pair: COLORS_LINE, force_color_pair: nil, pad: nil, add_nl: true, single_line: false)
-      text_size = size
-      from = text_size if from > text_size
-      to = text_size - 1 if to.nil?
-      to = window.maxx - window.curx + from - 2 if single_line && window.curx + to - from >= window.maxx - 1
-      current_idx = 0
-      @cells.each.with_index do |(cell_id, cell_info), cell_idx|
-        text = cell_text(cell_id)
-        full_substring_size = text.size + @separator.size
-        if from < current_idx + full_substring_size
-          # We have something to display from this substring
-          window.color_set(
-            if force_color_pair.nil?
-              cell_info[:color_pair] ? cell_info[:color_pair] : default_color_pair
-            else
-              force_color_pair
-            end
-          )
-          window << "#{text}#{cell_idx == @cells.size - 1 ? '' : @separator}"[(from < current_idx ? 0 : from - current_idx)..to - current_idx]
-        end
-        current_idx += full_substring_size
-        break if current_idx > to
-      end
-      window.color_set(force_color_pair.nil? ? default_color_pair : force_color_pair)
-      if pad && window.curx < window.maxx
-        nbr_chars = window.maxx - window.curx - 1
-        window << (pad * nbr_chars)[0..nbr_chars - 1]
-      end
-      window << "\n" if add_nl
-    end
-
-    private
-
-    # Get a cell's text.
-    # Cache it to not compute it several times.
-    #
-    # Parameters::
-    # * *cell_id* (Symbol): Cell id to get text for
-    # Result::
-    # * String: The cell's text
-    def cell_text(cell_id, cell_decorator: nil)
-      unless @cells[cell_id].key?(:cache_rendered_text)
-        begin_str = "#{@cells[cell_id][:begin_with] || ''}#{@cells[cell_id][:text]}"
-        end_str = @cells[cell_id][:end_with] || ''
-        @cells[cell_id][:cache_rendered_text] =
-          if @cells[cell_id][:fixed_size]
-            text = "#{begin_str[0..@cells[cell_id][:fixed_size] - end_str.size - 1]}#{end_str}"
-            remaining_size = @cells[cell_id][:fixed_size] - text.size
-            if remaining_size > 0
-              padding = ((@cells[cell_id][:pad] || ' ') * remaining_size)[0..remaining_size - 1]
-              justify = @cells[cell_id][:justify] || :left
-              case justify
-              when :left
-                "#{text}#{padding}"
-              when :right
-                "#{padding}#{text}"
-              else
-                raise "Unknown justify decorator: #{justify}"
-              end
-            else
-              text[0..@cells[cell_id][:fixed_size] - 1]
-            end
-          else
-            "#{begin_str}#{end_str}"
-          end
-      end
-      @cells[cell_id][:cache_rendered_text]
-    end
-
-  end
-
-end
+class CursesMenu
+
+  # Definition of a row that stores for each cell the string and color information to be displayed
+  class CursesRow
+
+    # Constructor
+    #
+    # Parameters::
+    # * *cells* (Hash< Symbol, Hash<Symbol,Object> >): For each cell id (ordered), the cell info:
+    #   * *text* (String): Text associated to this cell
+    #   * *color_pair* (Integer): Associated color pair [optional]
+    #   * *begin_with* (String): String to prepend to the text [default: '']
+    #   * *end_with* (String): String to append to the text [default: '']
+    #   * *fixed_size* (Integer): Number of characters this cell will take, or nil if no limit. [default: nil]
+    #   * *justify* (Symbol): Text justification (only used when fixed_size is not nil). Values can be: [default: :left]
+    #     * *left*: Left justified
+    #     * *right*: Right justified
+    #   * *pad* (String): Text to be used to pad the cell content (only used when fixed_size is not nil) [default: ' ']
+    # * *separator* (String): Separator used between cells [default: ' ']
+    def initialize(cells, separator: ' ')
+      @cells = cells
+      @separator = separator
+    end
+
+    # Change the cells order
+    #
+    # Parameters::
+    # * *cells* (Array<Symbol>): The ordered list of cells to filter
+    # * *unknown_cells* (String or Hash<Symbol,Object>): Content to put in unknown cells (as a String or properties like in #initialize), or nil to not add them. [default: nil]
+    def cells_order(cells, unknown_cells: nil)
+      new_cells = {}
+      cells.each do |cell_id|
+        if @cells.key?(cell_id)
+          new_cells[cell_id] = @cells[cell_id]
+        elsif !unknown_cells.nil?
+          new_cells[cell_id] = unknown_cells.is_a?(String) ? { text: unknown_cells } : unknown_cells
+        end
+      end
+      @cells = new_cells
+    end
+
+    # Change properties of a set of cells
+    #
+    # Parameters::
+    # * *cells* (Hash<Symbol, Hash<Symbol,Object> >): The cells properties to change, per cell id. Possible properties are the ones given in the #initialize method.
+    def change_cells(cells)
+      cells.each do |cell_id, cell_info|
+        raise "Unknown cell #{cell_id}" unless @cells.key?(cell_id)
+
+        @cells[cell_id].merge!(cell_info)
+        @cells[cell_id].delete(:cache_rendered_text)
+      end
+    end
+
+    # Get the size of the total string of such row.
+    #
+    # Parameters::
+    # * *cells* (Array<Symbol>): The list of cells to consider for the size [default: @cells.keys]
+    # Result::
+    # * Integer: Row size
+    def size(cells: @cells.keys)
+      result = @separator.size * (cells.size - 1)
+      cells.each do |cell_id|
+        result += cell_text(cell_id).size
+      end
+      result
+    end
+
+    # Print this row into a window
+    #
+    # Parameters::
+    # * *window* (Window): Curses window to print on
+    # * *from* (Integer): From index to be displayed [default: 0]
+    # * *to* (Integer): To index to be displayed [default: total size]
+    # * *default_color_pair* (Integer): Default color pair to use if no color information is provided [default: COLORS_LINE]
+    # * *force_color_pair* (Integer): Force color pair to use, or nil to not force [default: nil]
+    # * *pad* (String or nil): Pad the line to the row extent with the given string, or nil for no padding. [default: nil]
+    # * *add_nl* (Boolean): If true, then add a new line at the end [default: true]
+    # * *single_line* (Boolean): If true, then make sure the print does not exceed the line [default: false]
+    def print_on(window, from: 0, to: nil, default_color_pair: COLORS_LINE, force_color_pair: nil, pad: nil, add_nl: true, single_line: false)
+      text_size = size
+      from = text_size if from > text_size
+      to = text_size - 1 if to.nil?
+      to = window.maxx - window.curx + from - 2 if single_line && window.curx + to - from >= window.maxx - 1
+      current_idx = 0
+      @cells.each.with_index do |(cell_id, cell_info), cell_idx|
+        text = cell_text(cell_id)
+        full_substring_size = text.size + @separator.size
+        if from < current_idx + full_substring_size
+          # We have something to display from this substring
+          window.color_set(
+            if force_color_pair.nil?
+              cell_info[:color_pair] || default_color_pair
+            else
+              force_color_pair
+            end
+          )
+          window << "#{text}#{cell_idx == @cells.size - 1 ? '' : @separator}"[(from < current_idx ? 0 : from - current_idx)..to - current_idx]
+        end
+        current_idx += full_substring_size
+        break if current_idx > to
+      end
+      window.color_set(force_color_pair.nil? ? default_color_pair : force_color_pair)
+      if pad && window.curx < window.maxx
+        nbr_chars = window.maxx - window.curx - 1
+        window << (pad * nbr_chars)[0..nbr_chars - 1]
+      end
+      window << "\n" if add_nl
+    end
+
+    private
+
+    # Get a cell's text.
+    # Cache it to not compute it several times.
+    #
+    # Parameters::
+    # * *cell_id* (Symbol): Cell id to get text for
+    # Result::
+    # * String: The cell's text
+    def cell_text(cell_id)
+      unless @cells[cell_id].key?(:cache_rendered_text)
+        begin_str = "#{@cells[cell_id][:begin_with] || ''}#{@cells[cell_id][:text]}"
+        end_str = @cells[cell_id][:end_with] || ''
+        @cells[cell_id][:cache_rendered_text] =
+          if @cells[cell_id][:fixed_size]
+            text = "#{begin_str[0..@cells[cell_id][:fixed_size] - end_str.size - 1]}#{end_str}"
+            remaining_size = @cells[cell_id][:fixed_size] - text.size
+            if remaining_size.positive?
+              padding = ((@cells[cell_id][:pad] || ' ') * remaining_size)[0..remaining_size - 1]
+              justify = @cells[cell_id][:justify] || :left
+              case justify
+              when :left
+                "#{text}#{padding}"
+              when :right
+                "#{padding}#{text}"
+              else
+                raise "Unknown justify decorator: #{justify}"
+              end
+            else
+              text[0..@cells[cell_id][:fixed_size] - 1]
+            end
+          else
+            "#{begin_str}#{end_str}"
+          end
+      end
+      @cells[cell_id][:cache_rendered_text]
+    end
+
+  end
+
+end

data/lib/curses_menu/version.rb

@@ -0,0 +1,5 @@
+class CursesMenu
+
+  VERSION = '0.0.5'
+
+end

data/spec/curses_menu_test.rb

@@ -0,0 +1,131 @@
+require 'curses_menu'
+
+module CursesMenuTest
+
+  # Monkey-patch the curses_menu_finalize method so that it captures the menu screen before finalizing
+  module CursesMenuPatch
+
+    # Last screenshot taken
+    # Array<String>: List of lines
+    attr_reader :screenshot
+
+    # Finalize the curses menu window
+    def curses_menu_finalize
+      @screenshot = capture_screenshot
+      super
+    end
+
+    private
+
+    # Get a screenshot of the menu
+    #
+    # Result::
+    # * Array<String>: List of lines
+    def capture_screenshot
+      # Curses is initialized
+      window = Curses.stdscr
+      old_x = window.curx
+      old_y = window.cury
+      chars = []
+      window.maxy.times do |idx_y|
+        window.maxx.times do |idx_x|
+          window.setpos idx_y, idx_x
+          chars << window.inch
+        end
+      end
+      window.setpos old_y, old_x
+      # Build the map of colors per color pair acutally registered
+      colors_left_shift = Curses::A_COLOR.to_s(2).match(/^1+(0+)$/)[1].size
+      color_pairs = CursesMenu.constants.select { |const| const.to_s.start_with?('COLORS_') }.map do |const|
+        color_pair = CursesMenu.const_get(const)
+        [
+          # On Windows using Curses.color_pair can result in bugs [BUG] Unnormalized Fixnum value when using/displaying the value.
+          # So for now we depend on the internal algorithm used by color_pair (which is a left shift of the 0 bits of A_COLOR mask)
+          # TODO: Uncomment the following when curses will be fixed on Windows
+          # Curses.color_pair(color_pair),
+          color_pair << colors_left_shift,
+          const
+        ]
+      end.to_h
+      chars.
+        map do |chr|
+          {
+            char: begin
+              (chr & Curses::A_CHARTEXT).chr(Encoding::UTF_8)
+            rescue RangeError
+              # On Windows curses returns wrong encoded characters.
+              # In this case we just force an ASCII version of it.
+              (chr & 255).chr(Encoding::UTF_8)
+            end,
+            color: color_pairs[chr & Curses::A_COLOR] || chr & Curses::A_COLOR,
+            attributes: chr & Curses::A_ATTRIBUTES
+          }
+        end.
+        each_slice(window.maxx).
+        to_a
+    end
+
+  end
+
+  # Helpers for the tests
+  module Helpers
+
+    # Test a given menu, and prepare a screenshot to be analyzed
+    #
+    # Parameters::
+    # * *title* (String): The title [default: 'Menu title']
+    # * *keys* (Array<Object> or nil): Keys to automatically press [default: []]
+    # * *auto_exit* (Boolean): Do we automatically add the escape key to the key presses? [default: true]
+    # * Proc: The code called with the test menu to be populated
+    #   * Parameters::
+    #     * *menu* (CursesMenu): Curses menu to populate
+    #     * *key_presses* (Array<Object>): Keys to possibly give to sub-menus
+    def test_menu(title: 'Menu title', keys: [], auto_exit: true)
+      # TODO: Find a way to not depend on the current terminal screen, and run the tests silently.
+      key_presses = auto_exit ? keys + [CursesMenu::KEY_ESCAPE] : keys
+      menu = CursesMenu.new(title, key_presses: key_presses) do |m|
+        yield m, key_presses
+      end
+      @screenshot = menu.screenshot
+    end
+
+    # Assert that a line of the screenshot starts with a given content
+    #
+    # Parameters::
+    # * *line_idx* (Integer): The line index of the screenshot
+    # * *expectation* (String or Regexp): The expected line
+    def assert_line(line_idx, expectation)
+      line = @screenshot[line_idx][0..(expectation.is_a?(Regexp) ? -1 : expectation.size)].map { |char_info| char_info[:char] }.join
+      if expectation.is_a?(Regexp)
+        expect(line).to match(expectation), "Screenshot line #{line_idx} differs:\n  \"#{line}\" should be\n  \"#{expectation} \""
+      else
+        # Add an ending space to make sure the line does not continue after what we test
+        expect(line).to eq("#{expectation} "), "Screenshot line #{line_idx} differs:\n  \"#{line}\" should be\n  \"#{expectation} \""
+      end
+    end
+
+    # Assert that a line of the screenshot starts with a given content, using colors information
+    #
+    # Parameters::
+    # * *line_idx* (Integer): The line index of the screenshot
+    # * *expectation* (String): The expected line
+    # * *color* (Symbol): The expected color pair name
+    def assert_colored_line(line_idx, expectation, color)
+      colored_line = @screenshot[line_idx][0..expectation.size - 1].map do |char_info|
+        [char_info[:char], char_info[:color]]
+      end
+      expected_colored_line = expectation.each_char.map do |chr|
+        [chr, color]
+      end
+      expect(colored_line).to eq(expected_colored_line), "Screenshot line #{line_idx} differs:\n  \"#{colored_line}\" should be\n  \"#{expected_colored_line}\""
+    end
+
+  end
+
+end
+
+class CursesMenu
+
+  prepend CursesMenuTest::CursesMenuPatch
+
+end

data/spec/curses_menu_test/actions_spec.rb

@@ -0,0 +1,221 @@
+describe CursesMenu do
+
+  it 'actions the default selection when pressed enter' do
+    actioned = false
+    test_menu(keys: [CursesMenu::KEY_ENTER]) do |menu|
+      menu.item 'Menu item' do
+        actioned = true
+      end
+    end
+    expect(actioned).to eq(true)
+  end
+
+  it 'actions the default selection when pressed enter on the correct item' do
+    action = nil
+    test_menu(keys: [Curses::KEY_DOWN, Curses::KEY_DOWN, CursesMenu::KEY_ENTER]) do |menu|
+      menu.item 'Menu item 1' do
+        action = 1
+      end
+      menu.item 'Menu item 2' do
+        action = 2
+      end
+      menu.item 'Menu item 3' do
+        action = 3
+      end
+      menu.item 'Menu item 4' do
+        action = 4
+      end
+    end
+    expect(action).to eq(3)
+  end
+
+  it 'actions other actions' do
+    action = nil
+    test_menu(keys: ['a']) do |menu|
+      menu.item 'Menu item', actions: {
+        'a' => {
+          name: 'Action A',
+          execute: proc { action = 'a' }
+        },
+        'b' => {
+          name: 'Action B',
+          execute: proc { action = 'b' }
+        }
+      }
+    end
+    expect(action).to eq('a')
+  end
+
+  it 'actions several actions' do
+    actions = []
+    test_menu(keys: %w[a b a]) do |menu|
+      menu.item 'Menu item', actions: {
+        'a' => {
+          name: 'Action A',
+          execute: proc { actions << 'a' }
+        },
+        'b' => {
+          name: 'Action B',
+          execute: proc { actions << 'b' }
+        }
+      }
+    end
+    expect(actions).to eq(%w[a b a])
+  end
+
+  it 'actions several actions including the default one' do
+    actions = []
+    test_menu(keys: ['a', 'b', CursesMenu::KEY_ENTER, 'a']) do |menu|
+      menu.item(
+        'Menu item',
+        actions: {
+          'a' => {
+            name: 'Action A',
+            execute: proc { actions << 'a' }
+          },
+          'b' => {
+            name: 'Action B',
+            execute: proc { actions << 'b' }
+          }
+        }
+      ) do
+        actions << 'ENTER'
+      end
+    end
+    expect(actions).to eq(%w[a b ENTER a])
+  end
+
+  it 'actions nothing if action does not exist' do
+    actions = []
+    test_menu(keys: %w[a b c a]) do |menu|
+      menu.item(
+        'Menu item',
+        actions: {
+          'a' => {
+            name: 'Action A',
+            execute: proc { actions << 'a' }
+          },
+          'b' => {
+            name: 'Action B',
+            execute: proc { actions << 'b' }
+          }
+        }
+      ) do
+        actions << 'ENTER'
+      end
+    end
+    expect(actions).to eq(%w[a b a])
+  end
+
+  it 'exits when action returns :menu_exit' do
+    quit = false
+    test_menu(keys: [CursesMenu::KEY_ENTER], auto_exit: false) do |menu|
+      menu.item 'Menu item quit' do
+        quit = true
+        :menu_exit
+      end
+    end
+    expect(quit).to eq(true)
+  end
+
+  it 'navigates in sub-menus' do
+    actions = []
+    test_menu(
+      keys: [
+        # Enter sub-menu 1
+        CursesMenu::KEY_ENTER,
+        # Action sub-menu second item
+        Curses::KEY_DOWN,
+        CursesMenu::KEY_ENTER,
+        # Back to first menu
+        CursesMenu::KEY_ESCAPE,
+        # Enter sub-menu 2
+        Curses::KEY_DOWN,
+        CursesMenu::KEY_ENTER,
+        # Action sub-menu item
+        CursesMenu::KEY_ENTER,
+        # Exit sub-menu
+        Curses::KEY_DOWN,
+        CursesMenu::KEY_ENTER
+      ]
+    ) do |menu, key_presses|
+      menu.item 'Sub-menu 1' do
+        described_class.new('Sub-menu 1 title', key_presses: key_presses) do |sub_menu|
+          sub_menu.item 'Sub-menu item 1'
+          sub_menu.item 'Sub-menu item 2' do
+            actions << 'a'
+          end
+        end
+      end
+      menu.item 'Sub-menu 2' do
+        described_class.new('Sub-menu 2 title', key_presses: key_presses) do |sub_menu|
+          sub_menu.item 'Sub-menu item 1' do
+            actions << 'b'
+          end
+          sub_menu.item 'Sub-menu item 2' do
+            :menu_exit
+          end
+        end
+      end
+    end
+    expect(actions).to eq(%w[a b])
+  end
+
+  it 'exits only the sub-menu when action returns :menu_exit in a sub-menu' do
+    actions = []
+    test_menu(keys: [CursesMenu::KEY_ENTER, CursesMenu::KEY_ENTER, Curses::KEY_DOWN, CursesMenu::KEY_ENTER]) do |menu, key_presses|
+      menu.item 'Sub-menu' do
+        described_class.new('Sub-menu title', key_presses: key_presses) do |sub_menu|
+          sub_menu.item 'Sub-menu item quit' do
+            actions << 'a'
+            :menu_exit
+          end
+        end
+      end
+      menu.item 'Menu item 2' do
+        actions << 'b'
+      end
+    end
+    expect(actions).to eq(%w[a b])
+  end
+
+  it 'exits only the sub-menu when Escape key is used' do
+    actions = []
+    test_menu(keys: [CursesMenu::KEY_ENTER, CursesMenu::KEY_ESCAPE, Curses::KEY_DOWN, CursesMenu::KEY_ENTER]) do |menu, key_presses|
+      menu.item 'Sub-menu' do
+        described_class.new('Sub-menu title', key_presses: key_presses) do |sub_menu|
+          sub_menu.item 'Sub-menu item quit' do
+            actions << 'a'
+            :menu_exit
+          end
+        end
+      end
+      menu.item 'Menu item 2' do
+        actions << 'b'
+      end
+    end
+    expect(actions).to eq(%w[b])
+  end
+
+  it 'does not refresh menu items normally' do
+    idx = 0
+    test_menu(keys: [CursesMenu::KEY_ENTER, CursesMenu::KEY_ENTER]) do |menu|
+      menu.item "Menu item #{idx}" do
+        idx += 1
+      end
+    end
+    assert_line 3, 'Menu item 0'
+  end
+
+  it 'refreshes menu items when action returns :menu_refresh' do
+    idx = 0
+    test_menu(keys: [CursesMenu::KEY_ENTER, CursesMenu::KEY_ENTER]) do |menu|
+      menu.item "Menu item #{idx}" do
+        idx += 1
+        :menu_refresh
+      end
+    end
+    assert_line 3, 'Menu item 2'
+  end
+
+end