terminal-file-picker 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 36bd9443b474cff7cc402fb518e1a42f8f098a871da283384d74b5fb7cf2510a
+  data.tar.gz: b82f7ce18c958d285d9b55b5898e23c821bf6b49dfc2fe99984a88956cd1277d
+SHA512:
+  metadata.gz: bf21ba6ce88b30cb26cccbcf81b095d5c094e279ea8558a4dd8071fc88c5da39a256a0e080fe48ae2879238f671ae8fbeb33ab7de6526a652a566d598032180e
+  data.tar.gz: bfc0933ba0facedfe964f1008060331611b6d48762bc769d2b7fb1d957529f30f567fa654f4dd9f7525e6da97203c46fd4e3990bc5b3c00845e455b2aaf67ec1

data/README.md

@@ -0,0 +1,94 @@
+# Terminal File Picker
+
+This gem shows an interactive terminal file picker to user, allowing them to browse their files with arrow keys and file. The picked file path is then returned to the calling program. The file picker is completely text-based and can be used with a terminal or terminal emulator. It is essentially a terminal version of a GUI file choosing dialogue.
+
+The gem is useful when your program needs to accept a file path as input and you want a more user-friendly option than asking user to find out the file path and enter it as text.
+
+The gem does not rely on the Curses library and instead uses the [TTY toolkit](https://github.com/piotrmurach/tty), which has cross platform support and support for many types of terminals/terminal emulators. Therefore this gem should also have the same level of support.
+
+# Simple Usage
+
+```rb
+# Only required argument is the "root path". The user starts
+# navigating from the root path and the returned path of
+# the chosen file is relative to this root path.
+picker = FilePicker.new('.')
+
+# This brings up the interactive file picker. Once the user
+# has picked a file, the picker is cleared from screen and
+# the chosen file path returned.
+
+# If user picks a directory, instead of returning its path,
+# the files inside the chosen directory is shown instead.
+puts(picker.pick_file)
+```
+
+The simple file picker looks like this:
+
+```
+Page: 1/2 | Directory: .
+
+  Name                            Size (B)    Date modified    Time modified
+  ----------------------------------------------------------------------------
+  .                               4096        21/05/2020       00:53
+  ..                              4096        18/05/2020       22:45
+  terminal-file-picker.rb         113         21/05/2020       00:19
+  .gitignore                      20          17/05/2020       01:04
+  LICENSE                         1068        17/05/2020       22:42
+  README.md                       916         21/05/2020       00:53
+  .rubocop.yml                    497         17/05/2020       19:15
+  terminal-file-picker.gemspec    581         17/05/2020       22:24
+  .git/                           4096        21/05/2020       00:51
+  spec/                           4096        21/05/2020       00:47
+```
+
+# Options
+
+There are some options to customise the look and feel of the file picker (all options do have default values, so all are optional)
+
+The table headers can be changed (e.g. for internationalisation of if you want shorter headers).
+```rb
+FilePicker.new('.', header: ["Nm.", "Sz.", "Date md.", "Time md."])
+```
+
+You can change the current directory label which by default says "Directory" in the info line.
+
+```rb
+FilePicker.new('.', dir_label: 'Dir')
+```
+
+You can change current page label which by default says "Page" in the info line.
+
+```rb
+FilePicker.new('.', page_label: 'Pg')
+```
+
+You can change paddings of the table (in terms of number of spaces)
+
+```rb
+FilePicker.new('.', left_pad: 1, right_pad: 1)
+```
+
+The file picker automatically paginates files. You can set how many files there should be in each page (10 by default)
+
+```rb
+FilePicker.new('.', files_per_page: 20)
+```
+
+You can choose to hide the info line (the line which shows the current directory and current page)
+
+```rb
+FilePicker.new('.', show_info_line: false)
+```
+
+You can also change the position of the info line (valid values are :top or :bottom. :top is the default)
+
+```rb
+FilePicker.new('.', info_line_position: :bottom)
+```
+
+You can change the date and time format of date modified and time modified columns. The format can be specified using the same format accepted by the built-in `strftime` function.
+
+```rb
+FilePicker.new('.',  date_format: '%d-%m-%Y', time_format: '%H.%m')
+```

data/lib/file_browser_view.rb

@@ -0,0 +1,103 @@
+require 'tty-table'
+require 'tty-screen'
+require_relative 'helper'
+
+# Renders a directory view with pagination support. Allows
+# highlighting an item in the directory to indicate its selected.
+# Instance stores directory view rendering options.
+class FileBrowserView
+  attr_reader :files_per_page
+
+  def initialize(options = {})
+    @header = options.fetch(:header,
+                            ['Name', 'Size (B)', 'Date modified', 'Time modified'])
+    @dir_label = options.fetch(:dir_label, 'Directory')
+    @page_label = options.fetch(:page_label, 'Page')
+    @left_pad = options.fetch(:left_pad, 2)
+    @right_pad = options.fetch(:right_pad, 2)
+    @files_per_page = options.fetch(:files_per_page, 10)
+    @show_info_line = options.fetch(:show_info_line, true)
+    @info_line_position = options.fetch(:info_line_position, :top)
+    @screen_width = TTY::Screen.width
+
+    @cache = ''
+  end
+
+  def render(dir_path, files, selected_index, page, use_cache = false)
+    if !use_cache || (use_cache && @cache.empty?)
+      @cache = render_files_table(files)
+    end
+
+    files_table = @cache
+    file_browser = render_file_browser(files_table, selected_index, page)
+
+    return file_browser unless @show_info_line
+
+    info_line = info_bar(files.length, page, dir_path)
+    return "#{info_line}\n\n#{file_browser}" if @info_line_position == :top
+
+    "#{file_browser}\n\n#{info_line}"
+  end
+
+  private
+
+  def render_file_browser(rendered_files_table, selected_index, page)
+    rendered_rows = rendered_files_table.split("\n")
+
+    header = rendered_rows[0..1].join("\n")
+
+    body_rows = rendered_rows[2..]
+    body_rows = highlight_row(body_rows, selected_index)
+    body_rows = paginate_table_body(body_rows, page)
+    body = body_rows.join("\n")
+
+    "#{header}\n#{body}"
+  end
+
+  def render_files_table(files)
+    table = TTY::Table.new(@header, files)
+
+    table.render(:basic) do |r|
+      r.width = @screen_width
+      r.resize = table_width_overflowed?(table.width)
+      table_padding(r)
+      table_border(r)
+    end
+  end
+
+  def highlight_row(rows, row_no)
+    rows[row_no] = Helper.highlight(rows[row_no])
+
+    rows
+  end
+
+  def info_bar(total_files, page, dir_path)
+    page_count = (total_files.to_f / @files_per_page).ceil
+    "#{@page_label}: #{page + 1}/#{page_count} | #{@dir_label}: #{dir_path}"
+  end
+
+  def paginate_table_body(body_rows, page_no)
+    page_start = page_no * @files_per_page
+    page_end = page_start + (@files_per_page - 1)
+
+    body_rows[page_start..page_end]
+  end
+
+  def table_width_overflowed?(table_content_width)
+    table_padding = @header.length * (@left_pad + @right_pad) + 1
+    full_table_length = table_content_width + table_padding
+
+    full_table_length >= @screen_width
+  end
+
+  def table_padding(renderer)
+    renderer.padding = [0, @right_pad, 0, @left_pad]
+  end
+
+  def table_border(renderer)
+    renderer.border do
+      center ''
+      mid '-'
+    end
+  end
+end

data/lib/helper.rb

@@ -0,0 +1,23 @@
+require 'pastel'
+require 'tty-cursor'
+
+# Misc. helper methods which accomplish some common tasks.
+module Helper
+  class << self
+    def print_in_place(text)
+      line_count = text.count("\n")
+      cursor = TTY::Cursor
+
+      in_place = cursor.column(1)
+      in_place << text
+      in_place << cursor.up(line_count)
+      in_place << cursor.column(1)
+
+      print(in_place)
+    end
+
+    def highlight(text)
+      Pastel.new.decorate(text, :inverse)
+    end
+  end
+end

data/lib/terminal-file-picker.rb

@@ -0,0 +1,146 @@
+require 'tty-cursor'
+require 'tty-reader'
+require_relative 'file_browser_view'
+require_relative 'helper'
+
+# Responsible for keeping the state of the interactive file picker.
+# Also responds to user input to modify the state and redraw
+# file picker to reflect new state.
+class FilePicker
+  def initialize(dir_path, options = {})
+    @root_path = dir_path
+    @dir = FileBrowserView.new(options)
+    @reader = TTY::Reader.new(interrupt: :exit)
+    @reader.subscribe(self)
+    @user_have_picked = false
+    @page = 0
+    @cursor = TTY::Cursor
+
+    @date_format = options.fetch(:date_format, '%d/%m/%Y')
+    @time_format = options.fetch(:time_format, '%H:%M')
+    change_directory(dir_path)
+  end
+
+  def pick_file
+    @user_have_picked = false
+    redraw(false)
+
+    @cursor.invisible do
+      @reader.read_keypress until @user_have_picked
+    end
+
+    print(@cursor.clear_screen_down)
+    full_path_of_selected
+  end
+
+  def keydown(_event)
+    @selected += 1 unless selected_at_bottom?
+    if selected_below_page?
+      @page += 1
+      print(@cursor.clear_screen_down)
+    end
+    redraw(true)
+  end
+
+  def keyup(_event)
+    @selected -= 1 unless selected_at_top?
+    if selected_above_page?
+      @page -= 1
+      print(@cursor.clear_screen_down)
+    end
+    redraw(true)
+  end
+
+  def keypress(event)
+    case event.value
+    when "\r"
+      if File.directory?(full_path_of_selected)
+        change_directory(full_path_of_selected)
+        print(@cursor.clear_screen_down)
+        # Cache keeps a rendering of current directory.
+        # Going to a new directory, so needs to refresh
+        # the cache.
+        redraw(false)
+      else
+        @user_have_picked = true
+      end
+    end
+  end
+
+  private
+
+  def redraw(use_cache)
+    rendered = @dir.render(@current_path, @files, @selected, @page, use_cache)
+    Helper.print_in_place(rendered)
+  end
+
+  def selected_at_top?
+    @selected.zero?
+  end
+
+  def selected_at_bottom?
+    @selected == @files.length - 1
+  end
+
+  def selected_above_page?
+    @selected < (@page * @dir.files_per_page)
+  end
+
+  def selected_below_page?
+    @selected > (@page * @dir.files_per_page) + @dir.files_per_page - 1
+  end
+
+  def files_in_dir(dir_path)
+    Dir.entries(dir_path).map do |f|
+      size_bytes = File.size(full_path(f))
+
+      mtime = File.mtime(full_path(f))
+      date_mod = mtime.strftime(@date_format)
+      time_mod = mtime.strftime(@time_format)
+
+      name = file_display_name(f)
+
+      [name, size_bytes, date_mod, time_mod]
+    end
+  end
+
+  def change_directory(full_path)
+    @page = 0
+    @selected = 0
+    @current_path = full_path
+    @files = order_files(files_in_dir(@current_path))
+  end
+
+  def order_files(files)
+    # Put "." and ".." at the start
+    groups = files.group_by do |f|
+      if f.first == '.' || f.first == '..'
+        :dots
+      else
+        :files
+      end
+    end
+
+    # Sort so that "." comes before ".."
+    (groups[:dots] || []).sort + (groups[:files] || [])
+  end
+
+  def full_path(file_name)
+    return @current_path if file_name == '.'
+    return "#{@current_path}#{file_name}" if @current_path[-1] == '/'
+
+    "#{@current_path}/#{file_name}"
+  end
+
+  def full_path_of_selected
+    full_path(@files[@selected].first)
+  end
+
+  def file_display_name(file_name)
+    if File.directory?(full_path(file_name))
+      return "#{file_name}/" unless ['.', '..'].include?(file_name)
+    end
+
+    file_name
+  end
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: terminal-file-picker
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ilkut Kutlar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.4
+- !ruby/object:Gem::Dependency
+  name: tty-cursor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: tty-reader
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: tty-screen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: tty-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.82.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.82.0
+description: This gem shows an interactive terminal file picker to user, allowing
+  them to browse their files with arrow keys. The picked file path is then returned
+  to the calling program.
+email:
+- ilkutkutlar@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/file_browser_view.rb
+- lib/helper.rb
+- lib/terminal-file-picker.rb
+homepage: https://github.com/ilkutkutlar/terminal-file-picker
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Interactive terminal file picker
+test_files: []