tty-menu-tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 401abaaf372d1d2c9cf1302166e8f10b59806e6fc5e12107119c9ad242b0ce38
+  data.tar.gz: b5dd398022905ea05cb357b4e92fd6894f3ce3669a2737a720c9f3cd00e68f4c
+SHA512:
+  metadata.gz: d76b274a7e3f4ad52c9cb3835712315bac5bf2ebdf3c65ba45b7f5d025445b443ac989cc9faff734d09e62889feb719f4b679cfede4fbc8bf13541868bcb8971
+  data.tar.gz: 617e6ece447e68f1b7096c5f2d599e762fa2f2de25a4a7b12afa5ca261fb6c496a2ba981871bd1444b5c5d009c6e636f73bac713bfb7aaa21562e760a3fdb329

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- `TTY::MenuTree::Menu` — runs a tree of actions as an interactive menu with
+  submenu descent, back navigation, and an exit action.
+- `TTY::MenuTree::Action` — base class defining the `name`/`call`/`submenu`/`exit?`
+  protocol.
+- `TTY::MenuTree::Group` — an action that opens a submenu of child actions.
+- `TTY::MenuTree::ExitAction` — a ready-made action that ends the loop.
+- `TTY::MenuTree::Prompt` — a `tty-prompt` wrapper providing `select_action`
+  with optional "Back" handling.
+- `on_start` / `on_exit` hooks so banners and goodbyes stay out of the library.
+
+[Unreleased]: https://github.com/xef5000/tty-menu-tree/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/xef5000/tty-menu-tree/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Romain Deshaies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+# TTY::MenuTree
+
+Interactive, hierarchical command-line menus built on
+[tty-prompt](https://github.com/piotrmurach/tty-prompt).
+
+You model each menu entry as a small **action** object. `TTY::MenuTree::Menu`
+runs them in a loop: leaf actions are invoked, groups open a submenu (with
+automatic "Back" navigation), and an exit action ends the loop. Banners and
+goodbyes are injectable hooks, so the menu itself stays free of
+application-specific content.
+
+## Installation
+
+Add it to your Gemfile:
+
+```ruby
+gem "tty-menu-tree"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install it directly:
+
+```sh
+gem install tty-menu-tree
+```
+
+## Usage
+
+An action is any object that responds to `name`, `call`, `submenu`, and
+`exit?`. Subclass `TTY::MenuTree::Action` to get sensible defaults.
+
+```ruby
+require "tty/menu_tree"
+
+class SayHello < TTY::MenuTree::Action
+  def name = "Say hello"
+  def call = puts("Hello! 👋")
+end
+
+class ShowTime < TTY::MenuTree::Action
+  def name = "Show the time"
+  def call = puts(Time.now)
+end
+
+actions = [
+  TTY::MenuTree::Group.new(name: "Greetings", actions: [SayHello.new]),
+  ShowTime.new,
+  TTY::MenuTree::ExitAction.new,
+]
+
+TTY::MenuTree::Menu.new(
+  actions: actions,
+  title: "What would you like to do?",
+  on_start: -> { puts "Welcome!" },
+  on_exit: -> { puts "Goodbye!" },
+).run
+```
+
+### The action protocol
+
+| Method     | Returns              | Meaning                                            |
+| ---------- | -------------------- | -------------------------------------------------- |
+| `name`     | `String`             | Label shown in the menu.                           |
+| `call`     | anything             | Runs a leaf action (skipped when `submenu` is set).|
+| `submenu`  | `Array<#name>`/`nil` | Child actions to descend into, or `nil` for leaves.|
+| `exit?`    | `Boolean`            | When `true`, ends the top-level loop.              |
+
+You do not have to subclass anything — any duck-typed object works. The
+provided building blocks are just conveniences:
+
+- `TTY::MenuTree::Action` — base class with defaults and `NotImplementedError`
+  guards.
+- `TTY::MenuTree::Group` — an action whose `submenu` is its child actions.
+- `TTY::MenuTree::ExitAction` — an action whose `exit?` is `true`.
+
+### Customizing the prompt
+
+`Menu` only needs an object responding to
+`select_action(title, actions, back:)`. The default `TTY::MenuTree::Prompt`
+wraps `tty-prompt` and appends a "Back" entry (returning `nil`) when
+`back: true`. Pass your own prompt to fully control rendering:
+
+```ruby
+TTY::MenuTree::Menu.new(actions: actions, prompt: MyPrompt.new).run
+```
+
+You can also customize the default prompt's colors or Back label:
+
+```ruby
+prompt = TTY::MenuTree::Prompt.new(
+  tty_prompt: TTY::Prompt.new(active_color: :magenta),
+  back_label: "⬅ Back",
+)
+```
+
+## Development
+
+```sh
+bin/setup       # bundle install
+bundle exec rspec
+```
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/tty/menu_tree/action.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module TTY
+  module MenuTree
+    # Base class for anything that can appear in a menu.
+    #
+    # An action is any object that responds to the four methods below. You do
+    # not have to subclass +Action+; duck typing is enough. Subclassing simply
+    # gives you sensible defaults ({#submenu} => +nil+, {#exit?} => +false+) and
+    # +NotImplementedError+ guards for the parts you must define.
+    #
+    # @example A leaf action
+    #   class SayHello < TTY::MenuTree::Action
+    #     def name = "Say hello"
+    #     def call = puts("Hello!")
+    #   end
+    class Action
+      # @return [String] the label shown for this action in a menu.
+      def name
+        raise NotImplementedError, "#{self.class}#name must be implemented"
+      end
+
+      # Invoked when a leaf action is selected.
+      #
+      # Not called for actions that return a {#submenu}; those are descended
+      # into instead.
+      #
+      # @return [void]
+      def call
+        raise NotImplementedError, "#{self.class}#call must be implemented"
+      end
+
+      # @return [Array<#name>, nil] child actions to descend into, or +nil+ for
+      #   a leaf action.
+      def submenu
+        nil
+      end
+
+      # @return [Boolean] when +true+, selecting this action ends the top-level
+      #   menu loop.
+      def exit?
+        false
+      end
+    end
+  end
+end

data/lib/tty/menu_tree/exit_action.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "action"
+
+module TTY
+  module MenuTree
+    # A ready-made action that ends the top-level menu loop when selected.
+    #
+    # @example Custom label
+    #   TTY::MenuTree::ExitAction.new(name: "Quit")
+    class ExitAction < Action
+      DEFAULT_NAME = "Exit"
+
+      # @return [String] the label shown for this action.
+      attr_reader :name
+
+      # @param name [String] label shown in the menu.
+      def initialize(name: DEFAULT_NAME)
+        super()
+        @name = name
+      end
+
+      # No-op; selecting this action ends the loop rather than doing work.
+      # @return [void]
+      def call; end
+
+      # @return [true]
+      def exit?
+        true
+      end
+    end
+  end
+end

data/lib/tty/menu_tree/group.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "action"
+
+module TTY
+  module MenuTree
+    # An action that, when selected, opens a submenu of child actions rather
+    # than performing work itself.
+    #
+    # @example
+    #   TTY::MenuTree::Group.new(name: "Settings", actions: [ChangeTheme.new, Reset.new])
+    class Group < Action
+      # @return [String] the label shown for this group.
+      attr_reader :name
+
+      # @return [Array<#name>] the child actions.
+      attr_reader :submenu
+
+      # @param name [String] label shown in the parent menu.
+      # @param actions [Array<#name>] child actions to show when this group is
+      #   selected.
+      def initialize(name:, actions:)
+        super()
+        @name = name
+        @submenu = actions
+      end
+    end
+  end
+end

data/lib/tty/menu_tree/menu.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "prompt"
+
+module TTY
+  module MenuTree
+    # Runs a tree of actions as an interactive, hierarchical menu.
+    #
+    # The loop repeatedly asks the user to pick an action. Leaf actions are
+    # invoked via +#call+; actions that expose a +#submenu+ are descended into
+    # (with a "Back" entry); and an action whose +#exit?+ returns +true+ ends
+    # the loop.
+    #
+    # @example
+    #   menu = TTY::MenuTree::Menu.new(
+    #     actions: [group, TTY::MenuTree::ExitAction.new],
+    #     title: "What would you like to do?",
+    #     on_start: -> { puts "Welcome!" },
+    #     on_exit: -> { puts "Goodbye!" },
+    #   )
+    #   menu.run
+    class Menu
+      # @param actions [Array<#name>] top-level actions.
+      # @param prompt [#select_action] object used to render menus. Defaults to
+      #   a {Prompt}.
+      # @param title [String] heading shown for the top-level menu each loop.
+      # @param on_start [#call, nil] callable run once before the loop starts.
+      # @param on_exit [#call, nil] callable run once after an exit action is
+      #   chosen.
+      def initialize(actions:, prompt: Prompt.new, title: "What would you like to do?",
+                     on_start: nil, on_exit: nil)
+        @actions = actions
+        @prompt = prompt
+        @title = title
+        @on_start = on_start
+        @on_exit = on_exit
+      end
+
+      # Run the interactive loop until an exit action is chosen.
+      # @return [void]
+      def run
+        @on_start&.call
+
+        loop do
+          action = @prompt.select_action(@title, @actions)
+
+          if action.exit?
+            @on_exit&.call
+            break
+          end
+
+          run_action(action)
+        end
+      end
+
+      private
+
+      def run_action(action)
+        return action.call unless action.submenu
+
+        loop do
+          child = @prompt.select_action(action.name, action.submenu, back: true)
+          return if child.nil?
+
+          run_action(child)
+        end
+      end
+    end
+  end
+end

data/lib/tty/menu_tree/prompt.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+
+module TTY
+  module MenuTree
+    # Thin wrapper around +TTY::Prompt+ that knows how to render a list of
+    # actions and, optionally, a "Back" entry.
+    #
+    # {Menu} only depends on the {#select_action} method, so you may pass any
+    # object that implements it if you want fully custom rendering.
+    class Prompt
+      DEFAULT_BACK_LABEL = "\u21A9\uFE0F  Back"
+
+      # @param tty_prompt [TTY::Prompt] the underlying prompt to drive.
+      # @param back_label [String] label used for the "Back" entry.
+      def initialize(tty_prompt: TTY::Prompt.new(active_color: :cyan, help_color: :bright_black),
+                     back_label: DEFAULT_BACK_LABEL)
+        @tty_prompt = tty_prompt
+        @back_label = back_label
+      end
+
+      # Present +actions+ and return the one the user picked.
+      #
+      # @param title [String] heading shown above the choices.
+      # @param actions [Array<#name>] selectable actions.
+      # @param back [Boolean] when +true+, append a "Back" entry that returns
+      #   +nil+ when chosen.
+      # @return [Object, nil] the selected action, or +nil+ when "Back" was
+      #   chosen.
+      def select_action(title, actions, back: false)
+        choices = actions.to_h { |action| [action.name, action] }
+        choices[@back_label] = nil if back
+        @tty_prompt.select("\n#{title}", choices, per_page: choices.size)
+      end
+    end
+  end
+end

data/lib/tty/menu_tree/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TTY
+  module MenuTree
+    VERSION = "0.1.0"
+  end
+end

data/lib/tty/menu_tree.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "menu_tree/version"
+require_relative "menu_tree/action"
+require_relative "menu_tree/group"
+require_relative "menu_tree/exit_action"
+require_relative "menu_tree/prompt"
+require_relative "menu_tree/menu"
+
+module TTY
+  # A small toolkit for building interactive, hierarchical command-line menus
+  # on top of +tty-prompt+.
+  #
+  # See {TTY::MenuTree::Menu} for the entry point.
+  module MenuTree
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: tty-menu-tree
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Romain Deshaies
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |-
+  TTY::MenuTree runs a tree of polymorphic "action" objects as an interactive
+  command-line menu, with support for nested submenus, back navigation, and an
+  exit action. Content such as banners and goodbyes are injectable hooks so the
+  menu itself stays free of application-specific concerns.
+email:
+- romain.deshaies@shopify.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/tty/menu_tree.rb
+- lib/tty/menu_tree/action.rb
+- lib/tty/menu_tree/exit_action.rb
+- lib/tty/menu_tree/group.rb
+- lib/tty/menu_tree/menu.rb
+- lib/tty/menu_tree/prompt.rb
+- lib/tty/menu_tree/version.rb
+homepage: https://github.com/xef5000/tty-menu-tree
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/xef5000/tty-menu-tree
+  changelog_uri: https://github.com/xef5000/tty-menu-tree/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Interactive, hierarchical command-line menus built on tty-prompt.
+test_files: []