Repository files navigation

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

TTY::Editor provides independent component forTTY toolkit.

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.1.1 :command
    • 2.1.2 :env
    • 2.1.3 :raise_on_failure
    • 2.1.4 :prompt
    • 2.1.5 :hide_menu
    • 2.1.6 :enable_color
    • 2.1.7 :menu_interrupt
  • 2.2 open
• 3. Default Editors

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 theVISUAL orEDITOR shell environment variables take precedence when auto detecting available editors.

You can also set your preferred editor command(s) and ignoreVISUAL andEDITOR as well as other user preferences:

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

WhenVISUAL orEDITOR are not specified, a selection menu will be presented to the user.

For example, if an user hascode,emacs andvim 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.

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.

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-levelopen method accepts the same parameters:

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

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

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

The class-levelopen method accepts the same parameters:

TTY::Editor.open("/path/to/file",env:{"FOO"=>"bar"})

By default when editor fails to open afalse 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.

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

When more than one editor is available and user hasn't specified their preferred choice viaVISUAL orEDITOR variables, a selection menu is presented.

For example, whencode,emacs andvim 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]:

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)

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)

When an editor selection menu gets interrupted by theCtrl+C key, anInputInterrupt error is raised. To change this, provide the:menu_interrupt option with one of the following:

• :error - raisesInputInterrupt error
• :exit - exits with130 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)

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

editor=TTY::Editor.neweditor.open(...)# orTTY::Editor.open(...)

CreatingTTY::Editor instance means that the search for a command editor will be performed only once. Then the editor command will be shared between invocations ofopen call.

Conversely, the class-levelopen method will search for an editor each time it is invoked.

The following examples of using theopen 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 toopen:

TTY::Editor.open("../README.md")# => true

When editor successfully opens a file or content thentrue is returned,false otherwise.

You can change this with:raise_on_failure keyword to raise aTTY::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")

When an editor inEDITOR andVISUAL 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

After checking out the repo, runbin/setup to install dependencies. Then, runrake spec to run the tests. You can also runbin/console for an interactive prompt that will allow you to experiment.

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

Bug reports and pull requests are welcome on GitHub athttps://github.com/piotrmurach/tty-editor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to thecode of conduct.

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

Everyone interacting in the TTY::Editor project's codebases, issue trackers, chat rooms and mailing lists is expected to follow thecode of conduct.

Copyright (c) 2017 Piotr Murach. See LICENSE for further details.