tty-editor 0.4.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e9145c73047747147deaee2f06829d2defe3f465
-  data.tar.gz: 92a3157a7607890f740ba1b12fe1ee2ee297e9fe
+SHA256:
+  metadata.gz: 4c69c19a05883e0929e4f5432eb4732036b11866419842e7e9b08906de54d1fb
+  data.tar.gz: e7a817e4d91766846da2274c4c0cb0b76fc116bb189c9d01f9bb5feb4555fe96
 SHA512:
-  metadata.gz: 09dfdbe26a184a2a17516dcea8de5f83931133656fbf2f7e86bc7c9ff0d76c8cf45974c3139ed2339d08a9a90b8015023500ab0942863aa31b0a893404520260
-  data.tar.gz: cc8ce5952131f699be2ccf9cb0a9f22bf0d295c6648cbd661819781a2a614c590bbaf9d268f8368bf52589be85594ca633b2146edafdbcf814efb690bca5e4f1
+  metadata.gz: ee9f89d51a6d0645887416dae70c6c435af1d87ed8d90a8c3f7c459ff2f3e6eb2776afe818cf1b1285ad323e3ca771a7d9e3b31ad91af1083789d1c3fcbc06d5
+  data.tar.gz: 1e3668e7158517017a779b1aac72abc85296c58c81c2388136b08b3228d2c5b045727282216af54daea838aed56474e4e639fb89ebf6e38ffeae02df70fe1698

data/CHANGELOG.md

@@ -1,9 +1,62 @@
 # Change log
 
+## [v0.7.0] - 2021-05-31
+
+### Added
+* Add :enable_color option to allow control over editor menu colouring
+* Add :menu_interrupt to control how editor select menu handles interrupt signal
+* Add gedit and kate to the list of default editors
+
+### Changed
+* Change to search default editors when command and env variables checks fail
+* Change to rename :show_menu option as :hide_menu to indicate default behaviour
+* Change default editors list to be sorted in alphabetical order
+
+### Fixed
+* Fix Editor#exist? to correctly check command with an absolute path
+
+## [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
+* Change to update tty-prompt dependency
+* Change to relax bundler & rake version requirement
+
+## [v0.5.0] - 2018-12-18
+
+### Changed
+* Change to update and relax tty-prompt & tty-which constraints
+
+## [v0.4.1] - 2018-08-29
+
+### Changed
+* Update tty-prompt dependency
+
 ## [v0.4.0] - 2018-04-14
 
 ### Changed
 * Update tty-prompt dependency
+* Change to freeze all strings
 
 ## [v0.3.0] - 2018-01-06
 
@@ -46,10 +99,15 @@
 
 * Initial implementation and release
 
+[v0.7.0]: https://github.com/piotrmurach/tty-editor/compare/v0.6.0...v0.7.0
+[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
 [v0.4.0]: https://github.com/piotrmurach/tty-editor/compare/v0.3.0...v0.4.0
 [v0.3.0]: https://github.com/piotrmurach/tty-editor/compare/v0.2.1...v0.3.0
 [v0.2.1]: https://github.com/piotrmurach/tty-editor/compare/v0.2.0...v0.2.1
 [v0.2.0]: https://github.com/piotrmurach/tty-editor/compare/v0.1.2...v0.2.0
 [v0.1.2]: https://github.com/piotrmurach/tty-editor/compare/v0.1.1...v0.1.2
 [v0.1.1]: https://github.com/piotrmurach/tty-editor/compare/v0.1.0...v0.1.1
-[v0.1.0]: https://github.com/piotrmurach/tty-editor/compare/v0.1.0
+[v0.1.0]: https://github.com/piotrmurach/tty-editor/compare/762a7ec...v0.1.0

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Piotr Murach
+Copyright (c) 2016 Piotr Murach (piotrmurach.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,21 +1,25 @@
+<div align="center">
+  <a href="https://ttytoolkit.org"><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]
 
 [![Gem Version](https://badge.fury.io/rb/tty-editor.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-editor.svg?branch=master)][travis]
+[![Actions CI](https://github.com/piotrmurach/tty-editor/workflows/CI/badge.svg?branch=master)][gh_actions_ci]
 [![Build status](https://ci.appveyor.com/api/projects/status/yw4guy16meq5wkee?svg=true)][appveyor]
 [![Maintainability](https://api.codeclimate.com/v1/badges/0afb9e75eef4ae4615c6/maintainability)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-editor/badge.svg)][coverage]
-[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-editor.svg?branch=master)][inchpages]
+[![Inline docs](https://inch-ci.org/github/piotrmurach/tty-editor.svg?branch=master)][inchpages]
 
 [gitter]: https://gitter.im/piotrmurach/tty
-[gem]: http://badge.fury.io/rb/tty-editor
-[travis]: http://travis-ci.org/piotrmurach/tty-editor
+[gem]: https://badge.fury.io/rb/tty-editor
+[gh_actions_ci]: https://github.com/piotrmurach/tty-editor/actions?query=workflow%3ACI
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-editor
 [codeclimate]:https://codeclimate.com/github/piotrmurach/tty-editor/maintainability
 [coverage]: https://coveralls.io/github/piotrmurach/tty-editor
-[inchpages]: http://inch-ci.org/github/piotrmurach/tty-editor
+[inchpages]: https://inch-ci.org/github/piotrmurach/tty-editor
 
-> Opens a file or text in the user's preferred editor.
+> Open a file or text in a preferred terminal text editor.
 
 **TTY::Editor** provides independent component for [TTY](https://github.com/piotrmurach/tty) toolkit.
 
@@ -24,7 +28,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'tty-editor'
+gem "tty-editor"
 ```
 
 And then execute:
@@ -35,72 +39,279 @@ Or install it yourself as:
 
     $ gem install tty-editor
 
-## Usage
+## Contents
+
+* [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.1.5 :hide_menu](#215-hide_menu)
+    * [2.1.6 :enable_color](#216-enable_color)
+    * [2.1.7 :menu_interrupt](#217-menu_interrupt)
+  * [2.2 open](#22-open)
+* [3. Default Editors](#3-default-editors)
 
-To edit a file in default editor:
+## 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")
+```
+
+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:
+
+```ruby
+TTY::Editor.open("/path/to/file", command: "vim -f")
+```
+
+When `VISUAL` or `EDITOR` are not specified, a selection menu will be presented to the user.
+
+For example, if an user has `code`, `emacs` and `vim` editors available on their system, they will see the following menu:
+
+```
+Select an editor?
+  1) code
+  2) emacs
+  3) vim
+  Choose 1-3 [1]:
 ```
 
-Also, the `VISUAL` or `EDITOR` shell environment variables take precedencee when auto detecting available editors.
+You can further customise this behaviour with [:prompt](#214-prompt), [:hide_menu](#215-hide_menu), [:enable_color](#216-enable_color) and [:menu_interrupt](#217-menu_interrupt).
 
-## Interface
+## 2. API
 
-### open
+### 2.1 new
 
-If you wish to open editor with no file or content do:
+Instantiation of an editor will trigger automatic search for available command-line editors:
 
 ```ruby
-TTY::Editor.open
+editor = TTY::Editor.new
 ```
 
-When editor successfully opens file or content then `true` is returned.
+You can change default search with the `:command` keyword argument.
 
-If the editor cannot be opened, a `TTY::Editor::CommandInvocation` error is raised.
+#### 2.1.1 :command
 
-In order to open text content inside an editor do:
+You can force to always use a specific editor by passing `:command` option:
 
 ```ruby
-TTY::Editor.open(content: 'text')
+editor = TTY::Editor.new(command: "vim")
 ```
 
-You can also provide filename that will be created with specified content before editor is opened:
+Or you can specify multiple commands and give a user a choice:
 
 ```ruby
-TTY::Editor.open('new.rb', content: 'text')
+editor = TTY::Editor.new(command: ["vim", "emacs"])
 ```
 
-If you open a filename with already existing content then new content gets appended at the end of the file.
+The class-level `open` method accepts the same parameters:
 
-### :env
+```ruby
+TTY::Editor.open("/path/to/file", command: "vim")
+```
+
+#### 2.1.2 :env
 
-Use `:env` key to forward environment variables to  the editor.
+Use `:env` key to forward environment variables to the text editor launch command:
 
 ```ruby
-TTY::Editor.open('hello.rb', env: {"FOO" => "bar"})
+TTY::Editor.new(env: {"FOO" => "bar"})
 ```
 
-### :command
+The class-level `open` method accepts the same parameters:
 
-You can force to always use a specific editor by passing `:command` option:
+```ruby
+TTY::Editor.open("/path/to/file", env: {"FOO" => "bar"})
+```
+
+#### 2.1.3 :raise_on_failure
+
+By default when editor fails to open a `false` status is returned:
+
+```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
+editor = TTY::Editor.new(raise_on_failure: true)
+editor.open("/path/to/unknown/file")
+# => raises TTY::Editor::ComandInvocationError
+```
+
+#### 2.1.4 :prompt
+
+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 `code`, `emacs` and `vim` executable exists on the system, the following menu will be displayed:
+
+```
+Select an editor?
+  1) code
+  2) emacs
+  3) vim
+  Choose 1-3 [1]:
+```
+
+If you would like to change the menu prompt use `:prompt` keyword:
+
+```ruby
+editor = TTY::Editor.new(prompt: "Which one do you fancy?")
+editor.open("/path/to/file")
+```
+
+This may produce the following in the terminal:
+
+```
+Which one do you fancy?
+  1) code
+  2) emacs
+  3) vim
+  Choose 1-3 [1]:
+```
+
+#### 2.1.5 :hide_menu
+
+When more than one editor is available from the default list, a selection menu will be displayed in the console:
+
+```
+Select an editor?
+  1) code
+  2) emacs
+  3) vim
+  Choose 1-3 [1]:
+```
+
+To hide the menu and automatically choose the first available editor use the `:hide_menu` keyword option:
 
 ```ruby
-TTY::Editor.open('hello.rb', command: :vim)
+editor = TTY::Editor.new(hide_menu: true)
 ```
 
+#### 2.1.6 :enable_color
+
+An editor selection menu will display the first choice in colour on terminals that support colours. However, you can turn off colouring with the `:enable_color` keyword option:
+
+```ruby
+editor = TTY::Editor.new(enable_color: false)
+```
+
+Equally, you can enforce the current menu choice to be always coloured:
+
+```ruby
+editor = TTY::Editor.new(enable_color: true)
+```
+
+### 2.1.7 :menu_interrupt
+
+When an editor selection menu gets interrupted by the `Ctrl+C` key, an `InputInterrupt` error is raised. To change this, provide the `:menu_interrupt` option with one of the following:
+
+* `:error` - raises `InputInterrupt` error
+* `:exit` - exits with `130` status code
+* `:noop` - skips handler
+* `:signal` - sends interrupt signal
+* `proc` - custom proc handler
+
+For example, to immediately exit the menu and program do:
+
+```ruby
+editor = TTY::Editor.new(menu_interrupt: :exit)
+```
+
+### 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("file_1", "file_2", "new_file_3")
+```
+
+## 3. Default Editors
+
+When an editor in `EDITOR` and `VISUAL` environment variables can't be found or isn't specified, a choice menu is displayed. The menu includes available editors from the default list of text editors:
+
+* `Atom`
+* `Emacs`
+* `gedit`
+* `JED`
+* `Kate`
+* `Mg`
+* `Nano`
+* `Notepad`
+* `Pico`
+* `Sublime Text`
+* `TextMate`
+* `Vi`
+* `Vim`
+* `Visual Studio Code`
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -109,12 +320,16 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-editor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-editor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/piotrmurach/tty-editor/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
+## Code of Conduct
+
+Everyone interacting in the TTY::Editor project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-editor/blob/master/CODE_OF_CONDUCT.md).
+
 ## Copyright
 
-Copyright (c) 2017-2018 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2017 Piotr Murach. See LICENSE for further details.