TTY::Editor

Open a file or text in a preferred terminal text editor.

TTY::Editor provides independent component for TTY toolkit.

Installation

Add this line to your application's Gemfile:

gem "tty-editor"

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-editor

1. Usage
2. API
- 2.1 new
- 2.2 open
3. Default Editors

1. Usage

To edit a file in a default text editor do:

TTY::Editor.open("/path/to/file")

To edit text in a default editor:

TTY::Editor.open(text: "Some text")

You can also open multiple existing and/or new files:

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:

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]:

You can further customise this behaviour with :prompt, :hide_menu, :enable_color and :menu_interrupt.

2. API

2.1 new

Instantiation of an editor will trigger automatic search for available command-line editors:

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:

editor = TTY::Editor.new(command: "vim")

Or you can specify multiple commands and give a user a choice:

editor = TTY::Editor.new(command: ["vim", "emacs"])

The class-level open method accepts the same parameters:

TTY::Editor.open("/path/to/file", command: "vim")

2.1.2 :env

Use :env key to forward environment variables to the text editor launch command:

TTY::Editor.new(env: {"FOO" => "bar"})

The class-level open method accepts the same parameters:

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:

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:

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:

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:

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:

editor = TTY::Editor.new(enable_color: false)

Equally, you can enforce the current menu choice to be always coloured:

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:

editor = TTY::Editor.new(menu_interrupt: :exit)

2.2 open

There is a class-level and instance-level open method. These are equivalent:

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:

TTY::Editor.open

To open a file, pass a path as an argument to open:

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:

TTY::Editor.open(text: "Some text")

You can also provide filename that will be created with specified content before editor is opened:

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:

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.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

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 code of conduct.

License

The gem is available as open source under the terms of the MIT License.

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.

piotrmurach/tty-editor