TTY::Editor

Opens a file or text in the user's preferred 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

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

You can further customise this behaviour with :prompt.

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

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

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")

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

License

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