tty-editor 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d7c645222f24a5cef4cf15e61bf3dff1d2513312cd68e108639b99e32f445e9
-  data.tar.gz: 857b47f67928ff366acb4064431765e2a3db718a458933ac1d9a9368122a6bdf
+  metadata.gz: 43382f86c223e305662a67b003a4337ce5946adaee09dcd48879714a91e45eae
+  data.tar.gz: fd58b6084c4cbedd605c09ce30fca817ea7f4d467e32ddfd558e3c7eb972f0a4
 SHA512:
-  metadata.gz: 5c8872fa73934f4cb626a8f57fd15e7378c8e77f7bd7138d209f2e3c134922e736f887c6dac4edb90d37b82e2cb1245b8d2d73552b5b138b59356f8a93db7c5d
-  data.tar.gz: c768f3a8b70beb0058ab6d1ced349a36751cea6a4c43a70713d1baf5f63e350993ab7b1d7fb5e4700a20b0ff7589edbdfaf5c6b7813e89f0817b79ef0157bb54
+  metadata.gz: 31385f2ece1195d0c3801e495830c182f6808050c510ae83f3c78f48117a6a6a088ffce3177ea5283507a7e67cc235f6e580261e73ce03d0916044eeaeed0209
+  data.tar.gz: ddf5f4e74879e30a641ca4d3c7af06ffb0b7e36f8dd989915d599b283855e1fee77843d4788dd60eb7be93b1ef47b77285abb4a06b60528a36aefae75717dead

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Change log
 
+## [v0.6.0] - 2020-09-22
+
+### Added
+* Add ability to edit multiple files
+* Add ability to configure input and output
+* Add :raise_on_failure configuration option to control editor failure to run
+* Add :show_menu configuration option to disable editor menu choice
+* Add :prompt to configure an editor choice menu prompt
+
+### Changed
+* Change Editor#exist? to use direct path env var search
+* Change Editor#new to stop accepting filename and text arguments
+* Change Editor#new to select available text editors
+* Change Editor#open to accept keyword arguments
+* Change to stop raising when editor command cannot be run and return false instead
+* Remove tty-which dependency
+* Update tty-prompt dependency
+
+### Fixed
+* Fix to allow setting editor commands with flags
+
 ## [v0.5.1] - 2019-08-06
 
 ### Changed
@@ -63,6 +84,7 @@
 
 * Initial implementation and release
 
+[v0.6.0]: https://github.com/piotrmurach/tty-editor/compare/v0.5.1...v0.6.0
 [v0.5.1]: https://github.com/piotrmurach/tty-editor/compare/v0.5.0...v0.5.1
 [v0.5.0]: https://github.com/piotrmurach/tty-editor/compare/v0.4.1...v0.5.0
 [v0.4.1]: https://github.com/piotrmurach/tty-editor/compare/v0.4.0...v0.4.1

data/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+  <a href="https://ttytoolkit.org" target="_blank"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a>
 </div>
 
 # TTY::Editor [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
@@ -28,7 +28,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'tty-editor'
+gem "tty-editor"
 ```
 
 And then execute:
@@ -39,84 +39,206 @@ Or install it yourself as:
 
     $ gem install tty-editor
 
-## Usage
+## Contents
 
-To edit a file in default editor:
+* [1. Usage](#1-usage)
+* [2. API](#2-api)
+  * [2.1 new](#21-new)
+    * [2.1.1 :command](#211-command)
+    * [2.1.2 :env](#212-env)
+    * [2.1.3 :raise_on_failure](#213-raise_on_failure)
+    * [2.1.4 :prompt](#214-prompt)
+  * [2.2 open](#22-open)
+
+## 1. Usage
+
+To edit a file in a default text editor do:
 
 ```ruby
-TTY::Editor.open('hello.rb')
+TTY::Editor.open("/path/to/file")
 ```
 
-To edit content in a default editor:
+To edit text in a default editor:
 
 ```ruby
-TTY::Editor.open(content: "some text")
+TTY::Editor.open(text: "Some text")
 ```
 
-You can also set your preferred editor command:
+You can also open multiple existing and/or new files:
 
 ```ruby
-TTY::Editor.open('hello.rb', command: :vim)
+TTY::Editor.open("file_1", "file_2", "new_file_3")
 ```
 
-Also, the `VISUAL` or `EDITOR` shell environment variables take precedence when auto detecting available editors.
+Note that the `VISUAL` or `EDITOR` shell environment variables take precedence when auto detecting available editors.
+
+You can also set your preferred editor command(s) and ignore `VISUAL` and `EDITOR` as well as other user preferences:
 
-## Interface
+```ruby
+TTY::Editor.open("/path/to/file", command: "vim -f")
+```
 
-### open
+When `VISUAL` or `EDITOR` are not specified, a selection menu will be presented to the user.
+
+For example, if an user has `vim`, `emacs` and `code` editors available on their system, they will see the following menu:
+
+```
+# Select an editor?
+#   1) vim
+#   2) emacs
+#   3) code
+#   Choose 1-2 [1]:
+```
 
-If you wish to open editor with no file or content do:
+You can further customise this behaviour with [:prompt](#214-prompt).
+
+## 2. API
+
+### 2.1 new
+
+Instantiation of an editor will trigger automatic search for available command-line editors:
 
 ```ruby
-TTY::Editor.open
+editor = TTY::Editor.new
+```
+
+You can change default search with the `:command` keyword argument.
+
+#### 2.1.1 :command
+
+You can force to always use a specific editor by passing `:command` option:
+
+```ruby
+editor = TTY::Editor.new(command: "vim")
 ```
 
-To open a file at a path pass it as a first argument:
+Or you can specify multiple commands and give a user a choice:
 
 ```ruby
-TTY::Editor.open('../README.md')
+editor = TTY::Editor.new(command: ["vim", "emacs"])
 ```
 
-When editor successfully opens file or content then `true` is returned.
+The class-level `open` method accepts the same parameters:
 
-If the editor cannot be opened, a `TTY::Editor::CommandInvocation` error is raised.
+```ruby
+TTY::Editor.open("/path/to/file", command: "vim")
+```
 
-In order to open text content inside an editor do:
+#### 2.1.2 :env
+
+Use `:env` key to forward environment variables to the text editor launch command:
 
 ```ruby
-TTY::Editor.open(content: 'text')
+TTY::Editor.new(env: {"FOO" => "bar"})
 ```
 
-You can also provide filename that will be created with specified content before editor is opened:
+The class-level `open` method accepts the same parameters:
 
 ```ruby
-TTY::Editor.open('new.rb', content: 'text')
+TTY::Editor.open("/path/to/file", env: {"FOO" => "bar"})
 ```
 
-If you open a filename with already existing content then new content gets appended at the end of the file.
+#### 2.1.3 :raise_on_failure
 
-### :env
+By default when editor fails to open a `false` status is returned:
 
-Use `:env` key to forward environment variables to  the editor.
+```ruby
+TTY::Editor.open("/path/to/unknown/file") # => false
+```
+
+Alternatively, you can use `:raise_on_failure` to raise an error on failure to open a file.
+
+The `TTY::Editor::CommandInvocationError` will be raised anytime an editor fails to open a file:
 
 ```ruby
-TTY::Editor.open('hello.rb', env: {"FOO" => "bar"})
+editor = TTY::Editor.new(raise_on_failure: true)
+editor.open("/path/to/unknown/file")
+# => raises TTY::Editor::ComandInvocationError
 ```
 
-### :command
+#### 2.1.4 :prompt
 
-You can force to always use a specific editor by passing `:command` option:
+When more than one editor is available and user hasn't specified their preferred choice via `VISUAL` or `EDITOR` variables, a selection menu is presented.
+
+For example, when `vim`, `emacs` and `code` executable exists on the system, the following menu will be displayed:
+
+```
+# Select an editor?
+#   1) vim
+#   2) emacs
+#   3) code
+#   Choose 1-2 [1]:
+```
+
+If you would like to change the menu prompt use `:prompt` keyword:
 
 ```ruby
-TTY::Editor.open('hello.rb', command: :vim)
+editor = TTY::Editor.new(prompt: "Which one do you fancy?")
+editor.open("/path/to/file")
 ```
 
-To specify more than one command, and hence give a user a choice do:
+This may produce the following in the terminal:
+
+```
+# Which one do you fancy?
+#   1) vim
+#   2) emacs
+#   3) code
+#   Choose 1-2 [1]:
+```
+
+### 2.2 open
+
+There is a class-level and instance-level `open` method. These are equivalent:
+
+```ruby
+editor = TTY::Editor.new
+editor.open(...)
+# or
+TTY::Editor.open(...)
+```
+
+Creating `TTY::Editor` instance means that the search for a command editor will be performed only once. Then the editor command will be shared between invocations of `open` call.
+
+Conversely, the class-level `open` method will search for an editor each time it is invoked.
+
+The following examples of using the `open` method apply to both the instance and class level invocations.
+
+If you wish to open an editor without giving a file or content do:
+
+```ruby
+TTY::Editor.open
+```
+
+To open a file, pass a path as an argument to `open`:
+
+```ruby
+TTY::Editor.open("../README.md")
+# => true
+```
+
+When editor successfully opens a file or content then `true` is returned, `false` otherwise.
+
+You can change this with `:raise_on_failure` keyword to raise a `TTY::Editor::CommandInvocation` error when an editor cannot be opened.
+
+In order to open text content inside an editor use `:text` keyword like so:
+
+```ruby
+TTY::Editor.open(text: "Some text")
+```
+
+You can also provide filename that will be created with specified content before editor is opened:
+
+```ruby
+TTY::Editor.open("/path/to/new-file", text: "Some text")
+```
+
+If you open a filename with already existing content then the new content will be appended at the end of the file.
+
+You can also open multiple existing and non-existing files providing them as consecutive arguments:
 
 ```ruby
-TTY::Editor.open('hello.rb') do |editor|
-  editor.command :vim, :emacs
-end
+TTY::Editor.open("file_1", "file_2", "new_file_3")
 ```
 
 ## Development

data/lib/tty-editor.rb

@@ -1 +1 @@
-require_relative 'tty/editor'
+require_relative "tty/editor"

data/lib/tty/editor.rb

@@ -1,40 +1,53 @@
 # frozen_string_literal: true
 
-require 'tty-prompt'
-require 'tty-which'
-require 'tempfile'
-require 'fileutils'
-require 'shellwords'
+require "fileutils"
+require "shellwords"
+require "tempfile"
+require "tty-prompt"
 
-require_relative 'editor/version'
+require_relative "editor/version"
 
 module TTY
   # A class responsible for launching an editor
   #
   # @api public
   class Editor
+    Error = Class.new(StandardError)
+
+    # Raised when user provides unnexpected or incorrect argument
+    InvalidArgumentError = Class.new(Error)
+
     # Raised when command cannot be invoked
     class CommandInvocationError < RuntimeError; end
 
     # Raised when editor cannot be found
     class EditorNotFoundError < RuntimeError; end
 
-    # Check if editor exists
+    # List possible command line text editors
     #
-    # @return [Boolean]
+    # @return [Array[String]]
     #
-    # @api private
-    def self.exist?(cmd)
-      TTY::Which.exist?(cmd)
-    end
+    # @api public
+    EXECUTABLES = [
+      "nano -w", "notepad", "vim", "vi", "emacs",
+      "code", "subl -n -w", "mate -w", "atom",
+      "pico", "qe", "mg", "jed"
+    ].freeze
 
-    # Check if Windowz
+    # Check if editor command exists
+    #
+    # @example
+    #   exist?("vim") # => true
     #
     # @return [Boolean]
     #
-    # @api public
-    def self.windows?
-      ::File::ALT_SEPARATOR == "\\"
+    # @api private
+    def self.exist?(command)
+      exts = ENV.fetch("PATHEXT", "").split(::File::PATH_SEPARATOR)
+      ENV.fetch("PATH", "").split(::File::PATH_SEPARATOR).any? do |dir|
+        file = ::File.join(dir, command)
+        ::File.exist?(file) || exts.any? { |ext| ::File.exist?("#{file}#{ext}") }
+      end
     end
 
     # Check editor from environment variables
@@ -43,90 +56,98 @@ module TTY
     #
     # @api public
     def self.from_env
-      [ENV['VISUAL'], ENV['EDITOR']].compact
-    end
-
-    # List possible executable for editor command
-    #
-    # @return [Array[String]]
-    #
-    # @api public
-    def self.executables
-      ['vim', 'vi', 'emacs', 'nano', 'nano-tiny', 'pico', 'mate -w']
+      [ENV["VISUAL"], ENV["EDITOR"]].compact
     end
 
-    # Find available command
+    # Find available text editors
     #
     # @param [Array[String]] commands
     #   the commands to use intstead of defaults
     #
     # @return [Array[String]]
+    #   the existing editor commands
     #
     # @api public
     def self.available(*commands)
-      return commands unless commands.empty?
-
-      if !from_env.all?(&:empty?)
-        [from_env.find { |e| !e.empty? }]
-      elsif windows?
-        ['notepad']
-      else
-        executables.uniq.select(&method(:exist?))
-      end
+      execs = if !commands.empty?
+                commands.map(&:to_s)
+              elsif from_env.any?
+                [from_env.first]
+              else
+                EXECUTABLES
+              end
+      execs.compact.map(&:strip).reject(&:empty?).uniq
+           .select { |exec| exist?(exec.split.first) }
     end
 
     # Open file in system editor
     #
     # @example
-    #   TTY::Editor.open('filename.rb')
+    #   TTY::Editor.open("/path/to/filename")
     #
-    # @param [String] file
-    #   the name of the file
+    # @example
+    #   TTY::Editor.open("file1", "file2", "file3")
+    #
+    # @example
+    #   TTY::Editor.open(text: "Some text")
+    #
+    # @param [Array<String>] files
+    #   the files to open in an editor
+    # @param [String] :command
+    #   the editor command to use, by default auto detects
+    # @param [String] :text
+    #   the text to edit in an editor
+    # @param [Hash] :env
+    #   environment variables to forward to the editor
     #
     # @return [Object]
     #
     # @api public
-    def self.open(*args)
-      editor = new(*args)
-
-      yield(editor) if block_given?
-
-      editor.open
+    def self.open(*files, text: nil, **options, &block)
+      editor = new(**options, &block)
+      editor.open(*files, text: text)
     end
 
     # Initialize an Editor
     #
-    # @param [String] file
-    # @param [Hash[Symbol]] options
-    # @option options [Hash] :command
+    # @param [String] :command
     #   the editor command to use, by default auto detects
-    # @option options [Hash] :env
+    # @param [Hash] :env
     #   environment variables to forward to the editor
+    # @param [IO] :input
+    #   the standard input
+    # @param [IO] :output
+    #   the standard output
+    # @param [Boolean] :raise_on_failure
+    #   whether or not raise on command failure, false by default
+    # @param [Boolean] :show_menu
+    #   whether or not show commands menu, true by default
     #
     # @api public
-    def initialize(*args, **options)
-      @filename = args.unshift.first
-      @env      = options.fetch(:env) { {} }
-      @command  = options[:command]
-      if @filename
-        if ::File.exist?(@filename) && !::FileTest.file?(@filename)
-          raise ArgumentError, "Don't know how to handle `#{@filename}`. " \
-                               "Please provida a file path or content"
-        elsif ::File.exist?(@filename) && !options[:content].to_s.empty?
-          ::File.open(@filename, 'a') { |f| f.write(options[:content]) }
-        elsif !::File.exist?(@filename)
-          ::File.write(@filename, options[:content])
-        end
-      elsif options[:content]
-        @filename = tempfile_path(options[:content])
-      end
+    def initialize(command: nil, raise_on_failure: false, show_menu: true,
+                   prompt: "Select an editor?", env: {},
+                   input: $stdin, output: $stdout, &block)
+      @env = env
+      @command = nil
+      @input = input
+      @output = output
+      @raise_on_failure = raise_on_failure
+      @show_menu = show_menu
+      @prompt = prompt
+
+      block.(self) if block
+
+      command(*Array(command))
     end
 
     # Read or update environment vars
     #
+    # @return [Hash]
+    #
     # @api public
     def env(value = (not_set = true))
       return @env if not_set
+
       @env = value
     end
 
@@ -146,64 +167,116 @@ module TTY
       execs = self.class.available(*commands)
       if execs.empty?
         raise EditorNotFoundError,
-              'Could not find editor to use. Please specify $VISUAL or $EDITOR'
+              "could not find a text editor to use. Please specify $VISUAL or "\
+              "$EDITOR or install one of the following editors: " \
+              "#{EXECUTABLES.map { |ed| ed.split.first }.join(", ")}."
       end
-      exec = choose_exec_from(execs)
-      @command = TTY::Which.which(exec.to_s)
+      @command = choose_exec_from(execs)
     end
 
+    # Run editor command in a shell
+    #
+    # @param [Array<String>] files
+    #   the files to open in an editor
+    # @param [String] :text
+    #   the text to edit in an editor
+    #
+    # @raise [TTY::CommandInvocationError]
+    #
+    # @return [Boolean]
+    #   whether editor command suceeded or not
+    #
     # @api private
-    def choose_exec_from(execs)
-      if execs.size > 1
-        prompt = TTY::Prompt.new
-        prompt.enum_select('Select an editor?', execs)
-      else
-        execs[0]
+    def open(*files, text: nil)
+      validate_arguments(files, text)
+      text_written = false
+
+      filepaths = files.reduce([]) do |paths, filename|
+        if !::File.exist?(filename)
+          ::File.write(filename, text || "")
+          text_written = true
+        end
+        paths + [filename]
+      end
+
+      if !text.nil? && !text_written
+        tempfile = create_tempfile(text)
+        filepaths << tempfile.path
       end
+
+      run(filepaths)
+    ensure
+      tempfile.unlink if tempfile
     end
 
-    # Escape file path
+    private
+
+    # Run editor command with file arguments
+    #
+    # @param [Array<String>] filepaths
+    #   the file paths to open in an editor
+    #
+    # @return [Boolean]
+    #   whether command succeeded or not
     #
     # @api private
-    def escape_file
-      Shellwords.shellescape(@filename)
+    def run(filepaths)
+      command_path = "#{command} #{filepaths.shelljoin}"
+      status = system(env, *Shellwords.split(command_path))
+      if @raise_on_failure && !status
+        raise CommandInvocationError,
+              "`#{command_path}` failed with status: #{$? ? $?.exitstatus : nil}"
+      end
+      !!status
     end
 
-    # Build command path to invoke
+    # Check if filename and text arguments are valid
     #
-    # @return [String]
+    # @raise [InvalidArgumentError]
     #
     # @api private
-    def command_path
-      "#{command} #{escape_file}"
+    def validate_arguments(files, text)
+      return if files.empty?
+
+      if files.all? { |file| ::File.exist?(file) } && !text.nil?
+        raise InvalidArgumentError,
+              "cannot give a path to an existing file and text at the same time."
+      elsif filename = files.find { |file| ::File.exist?(file) && !::FileTest.file?(file) }
+        raise InvalidArgumentError, "don't know how to handle `#{filename}`. " \
+                                    "Please provide a file path or text"
+      end
     end
 
-    # Create tempfile with content
+    # Create tempfile with text
     #
-    # @param [String] content
+    # @param [String] text
+    #
+    # @return [Tempfile]
     #
-    # @return [String]
     # @api private
-    def tempfile_path(content)
-      tempfile = Tempfile.new('tty-editor')
-      tempfile << content
+    def create_tempfile(text)
+      tempfile = Tempfile.new("tty-editor")
+      tempfile << text
       tempfile.flush
-      unless tempfile.nil?
-        tempfile.close
-      end
-      tempfile.path
+      tempfile.close
+      tempfile
     end
 
-    # Inovke editor command in a shell
+    # Render an editor selection prompt to the terminal
     #
-    # @raise [TTY::CommandInvocationError]
+    # @return [String]
+    #   the chosen editor
     #
     # @api private
-    def open
-      status = system(env, *Shellwords.split(command_path))
-      return status if status
-      fail CommandInvocationError,
-           "`#{command_path}` failed with status: #{$? ? $?.exitstatus : nil}"
+    def choose_exec_from(execs)
+      if @show_menu && execs.size > 1
+        prompt = TTY::Prompt.new(input: @input, output: @output, env: @env)
+        exec = prompt.enum_select(@prompt, execs)
+        @output.print(prompt.cursor.up + prompt.cursor.clear_line)
+        exec
+      else
+        execs[0]
+      end
     end
   end # Editor
 end # TTY