add the ability to specify keys to select list items

README.md

@@ -629,7 +629,30 @@ choices = [
 ]
 ```
 
-You can specify `:key` as an additional option which will be used as short name for selecting the choice via keyboard key press.
+You can specify `:key` as an additional option which will be used as short name for selecting the choice via keyboard key press. When used with `:enum`, the key is displayed instead of a number.
+
+```ruby
+choices = [{name: "small", key: "s"}, {name: "medium", key: "m"}, {name: "large", key: "l"}]
+prompt.select("What size?", choices, enum: ')')
+# =>
+# What size? (Press ↑/↓ arrow to move and Enter to select)
+# ‣ s) small
+#   m) medium
+#   l) large
+```
+
+When providing `:key`, you can override the displayed text with `:key_name` - as in the case of using the escape key:
+
+
+```ruby
+choices = [{name: "next", key: "n"}, {name: "previous", key: "p"}, {name: "exit", key: :escape, key_name: "esc"}]
+prompt.select("Do what?", choices, enum: ')')
+# =>
+# Do what? (Press ↑/↓ arrow to move and Enter to select)
+# ‣ n) next
+#   p) previous
+#   esc) exit
+```
 
 Another way to create menu with choices is using the DSL and the `choice` method. For example, the previous array of choices with hash values can be translated as:
 
@@ -768,6 +791,30 @@ end
 # ‣ 3. Jax
 ```
 
+If your choices include the `:key` and (optionally) `:key_name` settings, those values will be displayed instead of numbers.
+
+```ruby
+choices = [{name: "small", key: "s"}, {name: "medium", key: "m"}, {name: "large", key: "l"}]
+prompt.select("What size?", choices, enum: ')')
+# =>
+# What size? (Press ↑/↓ arrow to move and Enter to select)
+# ‣ s) small
+#   m) medium
+#   l) large
+```
+
+#### 2.6.2.3 `:key_action`
+
+When using `:enum` or Choice `:key` settings, you can change the keypress behavior. By default, `:key_action` is `:move`: pressing a number key or corresponding `:key` will move the cursor to select the choice. You can also use `key_action: :select` to make a keypress immediately select the item.
+
+
+```ruby
+choices = [{name: "small", key: "s"}, {name: "medium", key: "m"}, {name: "large", key: "l"}]
+prompt.select("What size?", choices, enum: ')', key_action: :select)
+```
+
+In the above example, when pressing "l", the "large" option will be immediately selected and the prompt will exit.
+
 #### 2.6.2.3 `:help`
 
 You can configure help message with `:help` and when to display it with `:show_help` options. The help can be displayed on `start`, `never` or `always`:

lib/tty/prompt/choice.rb

@@ -67,6 +67,13 @@ def self.convert_hash(val)
       # @api public
       attr_reader :key
 
+      # The text to display when this choice is used with :enum (i.e. in List)
+      # Defaults to :key. Use `nil` or `false` to disable showing the enum for
+      # this Choice.
+      #
+      # @api public
+      attr_reader :key_name
+
       # The text to display for disabled choice
       #
       # @api public
@@ -76,9 +83,10 @@ def self.convert_hash(val)
       #
       # @api public
       def initialize(name, value, **options)
-        @name  = name
-        @value = value
-        @key   = options[:key]
+        @name     = name
+        @value    = value
+        @key      = options[:key]
+        @key_name = options[:key_name] || @key
         @disabled = options[:disabled].nil? ? false : options[:disabled]
         freeze
       end
@@ -113,7 +121,8 @@ def ==(other)
         return false unless other.is_a?(self.class)
         name == other.name &&
         value == other.value &&
-        key == other.key
+        key == other.key &&
+        key_name == other.key_name
       end
 
       # Object string representation

lib/tty/prompt/choices.rb

@@ -14,7 +14,7 @@ class Choices
       extend Forwardable
 
       def_delegators :choices, :length, :size, :to_ary, :empty?,
-                     :values_at, :index, :==
+                     :values_at, :index, :==, :last
 
       # Convenience for creating choices
       #

lib/tty/prompt/list.rb

@@ -16,6 +16,14 @@ class List
       # Allowed keys for filter, along with backspace and canc.
       FILTER_KEYS_MATCHER = /\A([[:alnum:]]|[[:punct:]])\Z/.freeze
 
+      # Allowed values for :key_action
+      #   move: move to the choice
+      #   select: select the choice
+      ALLOWED_KEY_ACTIONS = [
+        :move,
+        :select
+      ]
+
       # Create instance of TTY::Prompt::List menu.
       #
       # @param Hash options
@@ -36,6 +44,7 @@ def initialize(prompt, **options)
         @prompt       = prompt
         @prefix       = options.fetch(:prefix) { @prompt.prefix }
         @enum         = options.fetch(:enum) { nil }
+        @key_action   = options.fetch(:key_action) { :move }
         @default      = Array(options[:default])
         @choices      = Choices.new
         @active_color = options.fetch(:active_color) { @prompt.active_color }
@@ -108,6 +117,9 @@ def per_page(value)
         @per_page = value
       end
 
+      # Get the number of items per page.
+      #
+      # @api public
       def page_size
         (@per_page || Paginator::DEFAULT_PAGE_SIZE)
       end
@@ -201,6 +213,7 @@ def choice(*value, &block)
         else
           @choices << value
         end
+        check_choice_consistency(@choices.last)
       end
 
       # Add multiple choices, or return them.
@@ -222,7 +235,10 @@ def choices(values = (not_set = true))
           end
         else
           @filter_cache = {}
-          values.each { |val| @choices << val }
+          values.each do |val|
+            @choices << val
+            check_choice_consistency(@choices.last)
+          end
         end
       end
 
@@ -249,25 +265,35 @@ def enumerate?
         [email protected]?
       end
 
+      def search_choice_in(searchable)
+        searchable.find { |i| !choices[i - 1].disabled? }
+      end
+
+      # Handle pressed numeric keys. Used to select/move to enumerated choices.
+      #
+      # @api private
       def keynum(event)
         return unless enumerate?
 
         value = event.value.to_i
         return unless (1..choices.count).cover?(value)
         return if choices[value - 1].disabled?
         @active = value
+        @done = true if @key_action == :select
       end
 
+      # Select the currently hilighted item.
+      #
+      # @api private
       def keyenter(*)
         @done = true unless choices.empty?
       end
       alias keyreturn keyenter
       alias keyspace keyenter
 
-      def search_choice_in(searchable)
-        searchable.find { |i| !choices[i - 1].disabled? }
-      end
-
+      # Move the the selection up.
+      #
+      # @api private
       def keyup(*)
         searchable  = (@active - 1).downto(1).to_a
         prev_active = search_choice_in(searchable)
@@ -285,6 +311,9 @@ def keyup(*)
         @by_page = false
       end
 
+      # Move the selection down.
+      #
+      # @api private
       def keydown(*)
         searchable  = ((@active + 1)..choices.length)
         next_active = search_choice_in(searchable)
@@ -307,6 +336,8 @@ def keydown(*)
       #
       # When the choice on a page is outside of next page range then
       # adjust it to the last item, otherwise leave unchanged.
+      #
+      # @api private
       def keyright(*)
         if (@active + page_size) <= @choices.size
           searchable = ((@active + page_size)..choices.length)
@@ -328,6 +359,7 @@ def keyright(*)
       end
       alias keypage_down keyright
 
+      # @api private
       def keyleft(*)
         if (@active - page_size) > 0
           searchable = ((@active - page_size)..choices.length)
@@ -341,22 +373,42 @@ def keyleft(*)
       end
       alias keypage_up keyleft
 
+      # Handle entered non-numeric characters. When `filterable?`, apply them
+      # to the filter text. Otherwise, match the input character against Choice
+      # :key settings.
+      #
+      # @api private
       def keypress(event)
-        return unless filterable?
-
-        if event.value =~ FILTER_KEYS_MATCHER
-          @filter << event.value
-          @active = 1
+        # if filterable, ignore :key?
+        if filterable?
+          if event.value =~ FILTER_KEYS_MATCHER
+            @filter << event.value
+            @active = 1
+          end
+        else
+          # check for a matching Choice :key by key 'value', and then by 'name'
+          # this allows for either an alnum like "a", or a special like :escape
+          choice = choices.find_by(:key, event.value) || choices.find_by(:key, event.key.name)
+          if choice
+            @active = choices.index(choice) + 1
+            @done = true if @key_action == :select
+          end
         end
       end
 
+      # Remove characters from the filter text.
+      #
+      # @api private
       def keydelete(*)
         return unless filterable?
 
         @filter.clear
         @active = 1
       end
 
+      # Remove characters from the filter text.
+      #
+      # @api private
       def keybackspace(*)
         return unless filterable?
 
@@ -366,11 +418,30 @@ def keybackspace(*)
 
       private
 
+      # Make sure incompatible options or bad values are not present.
+      #
+      # @api private
       def check_options_consistency(options)
         if options.key?(:enum) && options.key?(:filter)
           raise ConfigurationError,
                 "Enumeration can't be used with filter"
         end
+
+        if options.key?(:key_action) && !ALLOWED_KEY_ACTIONS.include?(options[:key_action])
+          raise ConfigurationError,
+                "Invalid :key_action => %p. Must be one of: %s" %
+                  [ options[:key_action], ALLOWED_KEY_ACTIONS.map(&:inspect).join(', ') ]
+        end
+      end
+
+      # Make sure settings on a Choice are not incompatible with any options.
+      #
+      # @api private
+      def check_choice_consistency(choice)
+        if filterable? && choice.key
+          raise ConfigurationError,
+                "Filtering can't be used with Choice :key settings"
+        end
       end
 
       # Setup default option and active selection
@@ -536,7 +607,16 @@ def render_menu
 
         sync_paginators if @paging_changed
         paginator.paginate(choices, @active, @per_page) do |choice, index|
-          num = enumerate? ? (index + 1).to_s + @enum + " " : ""
+          # enumerate by provided :key, :key_name, or index number.
+          num = ""
+          if enumerate?
+            if choice.key && choice.key_name
+              num = choice.key_name.to_s + @enum + " "
+            elsif !choice.key
+              num = (index + 1).to_s + @enum + " "
+            end
+          end
+
           message = if index + 1 == @active && !choice.disabled?
                       selected = "#{@symbols[:marker]} #{num}#{choice.name}"
                       @prompt.decorate(selected.to_s, @active_color)

spec/unit/choice/eql_spec.rb

@@ -16,6 +16,16 @@
       not_to eq(described_class.new(:large, 2))
   end
 
+  it "is false with different key attribute" do
+    expect(described_class.new(:large, 1, key: "h")).
+      not_to eq(described_class.new(:large, 1, key: "g"))
+  end
+
+  it "is false with different key_name attribute" do
+    expect(described_class.new(:large, 1, key: "h", key_name: "aych")).
+      not_to eq(described_class.new(:large, 1, key: "h", key_name: "gee"))
+  end
+
   it "is false with non-choice object" do
     expect(described_class.new(:large, 1)).not_to eq(:other)
   end

spec/unit/choice/from_spec.rb

@@ -91,11 +91,26 @@
   it "creates choice from hash with key property" do
     default = {key: "h", name: "Help", value: :help}
     expected_choice = described_class.new("Help", :help, key: "h")
-    choice = described_class.from(default) 
+    choice = described_class.from(default)
 
     expect(choice).to eq(expected_choice)
     expect(choice.name).to eq("Help")
     expect(choice.value).to eq(:help)
+    expect(choice.key).to eq("h")
+    expect(choice.key_name).to eq("h")
+    expect(choice.disabled?).to eq(false)
+  end
+
+  it "creates choice from hash with key_name property" do
+    default = {key: :escape, key_name: "esc", name: "Help", value: :help}
+    expected_choice = described_class.new("Help", :help, key: :escape, key_name: "esc")
+    choice = described_class.from(default)
+
+    expect(choice).to eq(expected_choice)
+    expect(choice.name).to eq("Help")
+    expect(choice.value).to eq(:help)
+    expect(choice.key).to eq(:escape)
+    expect(choice.key_name).to eq("esc")
     expect(choice.disabled?).to eq(false)
   end
 

spec/unit/choices/each_spec.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-RSpec.describe TTY::Prompt::Choices, ".each" do
+RSpec.describe TTY::Prompt::Choices, "#each" do
   it "iterates over collection" do
     choices = described_class[:large, :medium, :small]
     actual = []