gum 0.2.0 → 0.3.0

data/lib/gum/command.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+require "English"
+require "open3"
+
+module Gum
+  module Command
+    def self.run(*, input: nil, interactive: true)
+      if input && interactive
+        run_interactive_with_input(*, input: input)
+      elsif input
+        run_non_interactive(*, input: input)
+      else
+        run_interactive(*)
+      end
+    end
+
+    def self.run_non_interactive(*args, input:)
+      stdout, stderr, status = Open3.capture3(Gum.executable, *args.map(&:to_s), stdin_data: input)
+
+      unless status.success?
+        return nil if status.exitstatus == 130 # User cancelled (Ctrl+C)
+
+        raise Error, "gum #{args.first} failed: #{stderr}" unless stderr.empty?
+      end
+
+      stdout.chomp
+    end
+
+    def self.run_interactive(*args)
+      tty = File.open("/dev/tty", "r+")
+
+      stdout, wait_thread = Open3.pipeline_r(
+        [Gum.executable, *args.map(&:to_s)],
+        in: tty,
+        err: tty
+      )
+
+      output = stdout.read.chomp
+      stdout.close
+      tty.close
+
+      status = wait_thread.last.value
+      return nil if status.exitstatus == 130 # User cancelled
+      return nil unless status.success?
+
+      output
+    rescue Errno::ENOENT, Errno::ENXIO, Errno::EIO
+      stdout, stderr, status = Open3.capture3(Gum.executable, *args.map(&:to_s))
+
+      unless status.success?
+        return nil if status.exitstatus == 130
+        raise Error, "gum #{args.first} failed: #{stderr}" unless stderr.empty?
+      end
+
+      stdout.chomp
+    end
+
+    def self.run_interactive_with_input(*args, input:)
+      tty = File.open("/dev/tty", "r+")
+      stdin_read, stdin_write = IO.pipe
+      stdout_read, stdout_write = IO.pipe
+
+      pid = Process.spawn(
+        Gum.executable, *args.map(&:to_s),
+        in: stdin_read,
+        out: stdout_write,
+        err: tty
+      )
+
+      stdin_read.close
+      stdout_write.close
+
+      stdin_write.write(input)
+      stdin_write.close
+
+      output = stdout_read.read.chomp
+      stdout_read.close
+
+      _, status = Process.wait2(pid)
+      tty.close
+
+      return nil if status.exitstatus == 130 # User cancelled
+      return nil unless status.success?
+
+      output
+    rescue Errno::ENOENT, Errno::ENXIO, Errno::EIO
+      run_non_interactive(*args, input: input)
+    end
+
+    def self.run_display_only(*args, input:)
+      IO.popen([Gum.executable, *args.map(&:to_s)], "w") do |io|
+        io.write(input)
+      end
+
+      $CHILD_STATUS.success? || nil
+    rescue Errno::ENOENT
+      raise Error, "gum executable not found"
+    end
+
+    def self.run_with_status(*args, input: nil)
+      if input
+        _stdout, _stderr, status = Open3.capture3(Gum.executable, *args.map(&:to_s), stdin_data: input)
+        status.success?
+      else
+        system(Gum.executable, *args.map(&:to_s))
+      end
+    end
+
+    def self.build_args(command, *positional, **options)
+      args = [command]
+      args.concat(positional.flatten.compact)
+
+      options.each do |key, value|
+        next if value.nil?
+
+        flag = key.to_s.tr("_", "-")
+
+        case value
+        when true
+          args << "--#{flag}"
+        when false
+          args << "--no-#{flag}" if flag_supports_negation?(command, flag)
+        when Array
+          value.each { |v| args << "--#{flag}=#{v}" }
+        when Hash
+          value.each { |k, v| args << "--#{flag}.#{k}=#{v}" }
+        else
+          args << "--#{flag}=#{value}"
+        end
+      end
+
+      args
+    end
+
+    def self.add_style_args(args, flag, style_hash)
+      return unless style_hash
+
+      style_hash.each do |key, value|
+        args << "--#{flag}.#{key}" << value.to_s
+      end
+    end
+
+    def self.flag_supports_negation?(command, flag)
+      negatable = {
+        "filter" => ["fuzzy", "sort", "strict", "reverse", "indicator"],
+        "choose" => ["limit"],
+        "input" => ["echo-mode"],
+        "file" => ["all", "file", "directory"],
+        "pager" => ["soft-wrap"],
+        "table" => ["border", "print"],
+      }
+
+      negatable.fetch(command, []).include?(flag)
+    end
+  end
+end

data/lib/gum/commands/choose.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Choose an option from a list of choices
+  #
+  # @example Single selection with array
+  #   color = Gum.choose(%w[red green blue])
+  #
+  # @example Single selection with splat
+  #   color = Gum.choose("red", "green", "blue")
+  #
+  # @example Multiple selection
+  #   colors = Gum.choose(%w[red green blue], limit: 2)
+  #
+  # @example Unlimited selection
+  #   colors = Gum.choose(%w[red green blue], no_limit: true)
+  #
+  # @example With header and custom height
+  #   choice = Gum.choose(options, header: "Pick one:", height: 10)
+  #
+  class Choose
+    # Choose from a list of options
+    #
+    # @rbs *items: Array[String] | String -- list of choices to display (array or splat)
+    # @rbs limit: Integer? -- maximum number of items that can be selected (1 = single select)
+    # @rbs no_limit: bool -- allow unlimited selections (use tab/ctrl+space to select)
+    # @rbs ordered: bool? -- maintain selection order
+    # @rbs height: Integer? -- height of the list
+    # @rbs cursor: String? -- cursor character (default: ">")
+    # @rbs header: String? -- header text displayed above choices
+    # @rbs cursor_prefix: String? -- prefix for the cursor line
+    # @rbs selected_prefix: String? -- prefix for selected items (default: "✓")
+    # @rbs unselected_prefix: String? -- prefix for unselected items (default: "○")
+    # @rbs selected: Array[String]? -- items to pre-select
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs cursor_style: Hash[Symbol, untyped]? -- cursor style options
+    # @rbs header_style: Hash[Symbol, untyped]? -- header text style
+    # @rbs item_style: Hash[Symbol, untyped]? -- item text style
+    # @rbs selected_style: Hash[Symbol, untyped]? -- selected item style
+    # @rbs return: String | Array[String] | nil -- selected item(s), or nil if cancelled
+    def self.call(
+      *items,
+      limit: nil,
+      no_limit: false,
+      ordered: nil,
+      height: nil,
+      cursor: nil,
+      header: nil,
+      cursor_prefix: nil,
+      selected_prefix: nil,
+      unselected_prefix: nil,
+      selected: nil,
+      timeout: nil,
+      cursor_style: nil,
+      header_style: nil,
+      item_style: nil,
+      selected_style: nil
+    )
+      items = items.flatten
+
+      options = {
+        limit: no_limit ? nil : limit,
+        "no-limit": no_limit || nil,
+        ordered: ordered,
+        height: height,
+        cursor: cursor,
+        header: header,
+        "cursor-prefix": cursor_prefix,
+        "selected-prefix": selected_prefix,
+        "unselected-prefix": unselected_prefix,
+        timeout: timeout ? "#{timeout}s" : nil,
+        item: item_style,
+        selected: selected,
+      }
+
+      args = Command.build_args("choose", *items, **options.compact)
+
+      Command.add_style_args(args, :cursor, cursor_style)
+      Command.add_style_args(args, :header, header_style)
+      Command.add_style_args(args, :selected, selected_style)
+
+      result = Command.run(*args)
+
+      return nil if result.nil?
+
+      if no_limit || (limit && limit > 1)
+        result.split("\n")
+      else
+        result
+      end
+    end
+  end
+end

data/lib/gum/commands/confirm.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Ask for user confirmation
+  #
+  # @example Basic confirmation
+  #   if Gum.confirm("Delete file?")
+  #     File.delete(path)
+  #   end
+  #
+  # @example With default value
+  #   proceed = Gum.confirm("Continue?", default: true)
+  #
+  # @example With custom button labels
+  #   Gum.confirm("Save changes?", affirmative: "Save", negative: "Discard")
+  #
+  class Confirm
+    # Prompt for yes/no confirmation
+    #
+    # @rbs prompt: String -- the confirmation prompt
+    # @rbs default: bool? -- default value (true = yes, false = no)
+    # @rbs affirmative: String? -- text for affirmative button (default: "Yes")
+    # @rbs negative: String? -- text for negative button (default: "No")
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs prompt_style: Hash[Symbol, untyped]? -- prompt text style options
+    # @rbs selected_style: Hash[Symbol, untyped]? -- selected button style options
+    # @rbs unselected_style: Hash[Symbol, untyped]? -- unselected button style options
+    # @rbs return: bool -- true if confirmed, false if rejected
+    def self.call(
+      prompt = "Are you sure?",
+      default: nil,
+      affirmative: nil,
+      negative: nil,
+      timeout: nil,
+      prompt_style: nil,
+      selected_style: nil,
+      unselected_style: nil
+    )
+      options = {
+        default: default.nil? ? nil : default,
+        affirmative: affirmative,
+        negative: negative,
+        timeout: timeout ? "#{timeout}s" : nil,
+      }
+
+      args = Command.build_args("confirm", prompt, **options.compact)
+
+      Command.add_style_args(args, :prompt, prompt_style)
+      Command.add_style_args(args, :selected, selected_style)
+      Command.add_style_args(args, :unselected, unselected_style)
+
+      Command.run_with_status(*args)
+    end
+  end
+end

data/lib/gum/commands/file.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Pick a file from a folder
+  #
+  # @example Basic file picker
+  #   path = Gum.file
+  #
+  # @example Start from specific directory
+  #   path = Gum.file(directory: "~/Documents")
+  #
+  # @example Show hidden files
+  #   path = Gum.file(all: true)
+  #
+  # @example Only show directories
+  #   dir = Gum.file(directory_only: true)
+  #
+  class FilePicker
+    # Pick a file from the filesystem
+    #
+    # @rbs path: String? -- starting directory path
+    # @rbs cursor: String? -- cursor character
+    # @rbs all: bool? -- show hidden files and directories
+    # @rbs file: bool? -- allow file selection (default: true)
+    # @rbs directory: bool? -- allow directory selection (default: false)
+    # @rbs directory_only: bool -- only allow directory selection (convenience option)
+    # @rbs height: Integer? -- height of the file picker
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs cursor_style: Hash[Symbol, untyped]? -- cursor style options
+    # @rbs symlink_style: Hash[Symbol, untyped]? -- symlink text style
+    # @rbs directory_style: Hash[Symbol, untyped]? -- directory text style
+    # @rbs file_style: Hash[Symbol, untyped]? -- file text style
+    # @rbs permissions_style: Hash[Symbol, untyped]? -- permissions text style
+    # @rbs selected_style: Hash[Symbol, untyped]? -- selected item style
+    # @rbs file_size_style: Hash[Symbol, untyped]? -- file size text style
+    # @rbs return: String? -- selected file path, or nil if cancelled
+    def self.call(
+      path = nil,
+      cursor: nil,
+      all: nil,
+      file: nil,
+      directory: nil,
+      directory_only: false,
+      height: nil,
+      timeout: nil,
+      cursor_style: nil,
+      symlink_style: nil,
+      directory_style: nil,
+      file_style: nil,
+      permissions_style: nil,
+      selected_style: nil,
+      file_size_style: nil
+    )
+      if directory_only
+        file = false
+        directory = true
+      end
+
+      options = {
+        cursor: cursor,
+        all: all,
+        file: file,
+        directory: directory,
+        height: height,
+        timeout: timeout ? "#{timeout}s" : nil,
+      }
+
+      positional = path ? [path] : [] #: Array[String]
+      args = Command.build_args("file", *positional, **options.compact)
+
+      Command.add_style_args(args, :cursor, cursor_style)
+      Command.add_style_args(args, :symlink, symlink_style)
+      Command.add_style_args(args, :directory, directory_style)
+      Command.add_style_args(args, :file, file_style)
+      Command.add_style_args(args, :permissions, permissions_style)
+      Command.add_style_args(args, :selected, selected_style)
+      Command.add_style_args(args, :"file-size", file_size_style)
+
+      Command.run(*args)
+    end
+  end
+end

data/lib/gum/commands/filter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Filter items from a list with fuzzy matching
+  #
+  # @example Single selection filter with array
+  #   file = Gum.filter(Dir.glob("*"))
+  #
+  # @example Single selection filter with splat
+  #   file = Gum.filter("file1.rb", "file2.rb", "file3.rb")
+  #
+  # @example Multiple selection filter
+  #   files = Gum.filter(Dir.glob("*"), limit: 5)
+  #
+  # @example With placeholder and height
+  #   selection = Gum.filter(items, placeholder: "Search...", height: 20)
+  #
+  class Filter
+    # Filter a list with fuzzy matching
+    #
+    # @rbs *items: Array[String] | String -- list of items to filter (array or splat)
+    # @rbs limit: Integer? -- maximum number of items that can be selected
+    # @rbs no_limit: bool -- allow unlimited selections (use tab/ctrl+space to select)
+    # @rbs height: Integer? -- height of the list
+    # @rbs width: Integer? -- width of the filter input
+    # @rbs placeholder: String? -- placeholder text for the filter input
+    # @rbs prompt: String? -- prompt string shown before input
+    # @rbs value: String? -- initial filter value
+    # @rbs header: String? -- header text displayed above the list
+    # @rbs indicator: String? -- character for selected item indicator
+    # @rbs selected_prefix: String? -- prefix for selected items
+    # @rbs unselected_prefix: String? -- prefix for unselected items
+    # @rbs match_prefix: String? -- prefix for matched text
+    # @rbs fuzzy: bool? -- enable fuzzy matching (default: true)
+    # @rbs sort: bool? -- sort results by match score (default: true)
+    # @rbs strict: bool? -- require exact match
+    # @rbs reverse: bool? -- reverse the order of results
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs header_style: Hash[Symbol, untyped]? -- header text style
+    # @rbs text_style: Hash[Symbol, untyped]? -- text style for items
+    # @rbs cursor_text_style: Hash[Symbol, untyped]? -- style for cursor line text
+    # @rbs match_style: Hash[Symbol, untyped]? -- style for matched characters
+    # @rbs placeholder_style: Hash[Symbol, untyped]? -- placeholder text style
+    # @rbs prompt_style: Hash[Symbol, untyped]? -- prompt text style
+    # @rbs indicator_style: Hash[Symbol, untyped]? -- indicator character style
+    # @rbs return: String | Array[String] | nil -- selected item(s), or nil if cancelled
+    def self.call(
+      *items,
+      limit: nil,
+      no_limit: false,
+      height: nil,
+      width: nil,
+      placeholder: nil,
+      prompt: nil,
+      value: nil,
+      header: nil,
+      indicator: nil,
+      selected_prefix: nil,
+      unselected_prefix: nil,
+      match_prefix: nil,
+      fuzzy: nil,
+      sort: nil,
+      strict: nil,
+      reverse: nil,
+      timeout: nil,
+      header_style: nil,
+      text_style: nil,
+      cursor_text_style: nil,
+      match_style: nil,
+      placeholder_style: nil,
+      prompt_style: nil,
+      indicator_style: nil
+    )
+      items = items.flatten
+
+      options = {
+        limit: no_limit ? 0 : limit,
+        height: height,
+        width: width,
+        placeholder: placeholder,
+        prompt: prompt,
+        value: value,
+        header: header,
+        indicator: indicator,
+        selected_prefix: selected_prefix,
+        unselected_prefix: unselected_prefix,
+        match_prefix: match_prefix,
+        fuzzy: fuzzy,
+        sort: sort,
+        strict: strict,
+        reverse: reverse,
+        timeout: timeout ? "#{timeout}s" : nil,
+        text: text_style,
+        cursor_text: cursor_text_style,
+        match: match_style,
+      }
+
+      args = Command.build_args("filter", **options.compact)
+
+      Command.add_style_args(args, :header, header_style)
+      Command.add_style_args(args, :placeholder, placeholder_style)
+      Command.add_style_args(args, :prompt, prompt_style)
+      Command.add_style_args(args, :indicator, indicator_style)
+
+      input_data = items.join("\n")
+      result = Command.run(*args, input: input_data)
+
+      return nil if result.nil?
+
+      if no_limit || (limit && limit > 1)
+        result.split("\n")
+      else
+        result
+      end
+    end
+  end
+end

data/lib/gum/commands/format.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Format text with markdown, code highlighting, templates, or emojis
+  #
+  # @example Markdown formatting
+  #   Gum.format("# Hello\n- Item 1\n- Item 2")
+  #
+  # @example Code highlighting
+  #   Gum.format(code, type: :code, language: "ruby")
+  #
+  # @example Template formatting
+  #   Gum.format('{{ Bold "Hello" }} {{ Color "99" "0" " World " }}', type: :template)
+  #
+  # @example Emoji formatting
+  #   Gum.format("I :heart: Ruby :gem:", type: :emoji)
+  #
+  class Format
+    TYPES = [:markdown, :code, :template, :emoji].freeze #: Array[Symbol]
+
+    # Format and render text
+    #
+    # @rbs *text: String -- text content to format (multiple strings joined with newlines)
+    # @rbs type: Symbol | String | nil -- format type (:markdown, :code, :template, :emoji)
+    # @rbs language: String? -- programming language for code highlighting
+    # @rbs theme: String? -- syntax highlighting theme
+    # @rbs return: String? -- formatted text output
+    def self.call(*text, type: nil, language: nil, theme: nil)
+      options = {
+        type: type&.to_s,
+        language: language,
+        theme: theme,
+      }
+
+      content = text.join("\n")
+
+      args = Command.build_args("format", **options.compact)
+
+      if content.empty?
+        Command.run(*args, interactive: false)
+      else
+        Command.run(*args, input: content, interactive: false)
+      end
+    end
+
+    # @rbs text: String -- markdown text to format
+    # @rbs return: String? -- rendered markdown output
+    def self.markdown(text)
+      call(text, type: :markdown)
+    end
+
+    # @rbs text: String -- source code to highlight
+    # @rbs language: String? -- programming language for highlighting
+    # @rbs theme: String? -- syntax highlighting theme
+    # @rbs return: String? -- syntax-highlighted code output
+    def self.code(text, language: nil, theme: nil)
+      call(text, type: :code, language: language, theme: theme)
+    end
+
+    # @rbs text: String -- template string with Termenv helpers
+    # @rbs return: String? -- rendered template output
+    def self.template(text)
+      call(text, type: :template)
+    end
+
+    # @rbs text: String -- text with :emoji_name: codes
+    # @rbs return: String? -- text with emojis rendered
+    def self.emoji(text)
+      call(text, type: :emoji)
+    end
+  end
+end

data/lib/gum/commands/input.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Prompt for single-line input
+  #
+  # @example Basic input
+  #   name = Gum.input(placeholder: "Enter your name")
+  #
+  # @example Password input
+  #   password = Gum.input(password: true)
+  #
+  # @example With default value and custom prompt
+  #   email = Gum.input(value: "user@", prompt: "> ", placeholder: "email")
+  #
+  class Input
+    # Prompt for single-line input
+    #
+    # @rbs placeholder: String? -- placeholder text shown when input is empty
+    # @rbs prompt: String? -- prompt string shown before input
+    # @rbs value: String? -- initial value for the input
+    # @rbs char_limit: Integer? -- maximum number of characters allowed
+    # @rbs width: Integer? -- width of the input field
+    # @rbs password: bool -- mask input characters for password entry
+    # @rbs header: String? -- header text displayed above the input
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs cursor: Hash[Symbol, untyped]? -- cursor style options (foreground, background)
+    # @rbs prompt_style: Hash[Symbol, untyped]? -- prompt text style options
+    # @rbs placeholder_style: Hash[Symbol, untyped]? -- placeholder text style options
+    # @rbs header_style: Hash[Symbol, untyped]? -- header text style options
+    # @rbs return: String? -- the entered text, or nil if cancelled
+    def self.call(
+      placeholder: nil,
+      prompt: nil,
+      value: nil,
+      char_limit: nil,
+      width: nil,
+      password: false,
+      header: nil,
+      timeout: nil,
+      cursor: nil,
+      prompt_style: nil,
+      placeholder_style: nil,
+      header_style: nil
+    )
+      options = {
+        placeholder: placeholder,
+        prompt: prompt,
+        value: value,
+        char_limit: char_limit,
+        width: width,
+        password: password || nil,
+        header: header,
+        timeout: timeout ? "#{timeout}s" : nil,
+        cursor: cursor,
+      }
+
+      args = Command.build_args("input", **options.compact)
+
+      Command.add_style_args(args, :prompt, prompt_style)
+      Command.add_style_args(args, :placeholder, placeholder_style)
+      Command.add_style_args(args, :header, header_style)
+
+      Command.run(*args)
+    end
+  end
+end

data/lib/gum/commands/join.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Join text blocks horizontally or vertically
+  #
+  # @example Horizontal join (default)
+  #   combined = Gum.join(box1, box2)
+  #
+  # @example Vertical join
+  #   stacked = Gum.join(box1, box2, vertical: true)
+  #
+  # @example With alignment
+  #   aligned = Gum.join(box1, box2, vertical: true, align: :center)
+  #
+  class Join
+    # Join text blocks together
+    #
+    # @rbs *texts: String -- text blocks to join (usually styled with Gum.style)
+    # @rbs vertical: bool -- stack blocks vertically (default: false, horizontal)
+    # @rbs horizontal: bool -- place blocks side by side (default)
+    # @rbs align: Symbol | String | nil -- alignment (:left, :center, :right for vertical; :top, :middle, :bottom for horizontal)
+    # @rbs return: String? -- combined text output
+    def self.call(*texts, vertical: false, horizontal: false, align: nil)
+      options = {} #: Hash[Symbol, untyped]
+
+      if vertical
+        options[:vertical] = true
+      elsif horizontal
+        options[:horizontal] = true
+      end
+
+      options[:align] = align.to_s if align
+
+      args = Command.build_args("join", *texts, **options.compact)
+
+      Command.run(*args, interactive: false)
+    end
+  end
+end