tty-editor 0.4.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: e9145c73047747147deaee2f06829d2defe3f465
4
- data.tar.gz: 92a3157a7607890f740ba1b12fe1ee2ee297e9fe
2
+ SHA256:
3
+ metadata.gz: 4c69c19a05883e0929e4f5432eb4732036b11866419842e7e9b08906de54d1fb
4
+ data.tar.gz: e7a817e4d91766846da2274c4c0cb0b76fc116bb189c9d01f9bb5feb4555fe96
5
5
  SHA512:
6
- metadata.gz: 09dfdbe26a184a2a17516dcea8de5f83931133656fbf2f7e86bc7c9ff0d76c8cf45974c3139ed2339d08a9a90b8015023500ab0942863aa31b0a893404520260
7
- data.tar.gz: cc8ce5952131f699be2ccf9cb0a9f22bf0d295c6648cbd661819781a2a614c590bbaf9d268f8368bf52589be85594ca633b2146edafdbcf814efb690bca5e4f1
6
+ metadata.gz: ee9f89d51a6d0645887416dae70c6c435af1d87ed8d90a8c3f7c459ff2f3e6eb2776afe818cf1b1285ad323e3ca771a7d9e3b31ad91af1083789d1c3fcbc06d5
7
+ data.tar.gz: 1e3668e7158517017a779b1aac72abc85296c58c81c2388136b08b3228d2c5b045727282216af54daea838aed56474e4e639fb89ebf6e38ffeae02df70fe1698
data/CHANGELOG.md CHANGED
@@ -1,9 +1,62 @@
1
1
  # Change log
2
2
 
3
+ ## [v0.7.0] - 2021-05-31
4
+
5
+ ### Added
6
+ * Add :enable_color option to allow control over editor menu colouring
7
+ * Add :menu_interrupt to control how editor select menu handles interrupt signal
8
+ * Add gedit and kate to the list of default editors
9
+
10
+ ### Changed
11
+ * Change to search default editors when command and env variables checks fail
12
+ * Change to rename :show_menu option as :hide_menu to indicate default behaviour
13
+ * Change default editors list to be sorted in alphabetical order
14
+
15
+ ### Fixed
16
+ * Fix Editor#exist? to correctly check command with an absolute path
17
+
18
+ ## [v0.6.0] - 2020-09-22
19
+
20
+ ### Added
21
+ * Add ability to edit multiple files
22
+ * Add ability to configure input and output
23
+ * Add :raise_on_failure configuration option to control editor failure to run
24
+ * Add :show_menu configuration option to disable editor menu choice
25
+ * Add :prompt to configure an editor choice menu prompt
26
+
27
+ ### Changed
28
+ * Change Editor#exist? to use direct path env var search
29
+ * Change Editor#new to stop accepting filename and text arguments
30
+ * Change Editor#new to select available text editors
31
+ * Change Editor#open to accept keyword arguments
32
+ * Change to stop raising when editor command cannot be run and return false instead
33
+ * Remove tty-which dependency
34
+ * Update tty-prompt dependency
35
+
36
+ ### Fixed
37
+ * Fix to allow setting editor commands with flags
38
+
39
+ ## [v0.5.1] - 2019-08-06
40
+
41
+ ### Changed
42
+ * Change to update tty-prompt dependency
43
+ * Change to relax bundler & rake version requirement
44
+
45
+ ## [v0.5.0] - 2018-12-18
46
+
47
+ ### Changed
48
+ * Change to update and relax tty-prompt & tty-which constraints
49
+
50
+ ## [v0.4.1] - 2018-08-29
51
+
52
+ ### Changed
53
+ * Update tty-prompt dependency
54
+
3
55
  ## [v0.4.0] - 2018-04-14
4
56
 
5
57
  ### Changed
6
58
  * Update tty-prompt dependency
59
+ * Change to freeze all strings
7
60
 
8
61
  ## [v0.3.0] - 2018-01-06
9
62
 
@@ -46,10 +99,15 @@
46
99
 
47
100
  * Initial implementation and release
48
101
 
102
+ [v0.7.0]: https://github.com/piotrmurach/tty-editor/compare/v0.6.0...v0.7.0
103
+ [v0.6.0]: https://github.com/piotrmurach/tty-editor/compare/v0.5.1...v0.6.0
104
+ [v0.5.1]: https://github.com/piotrmurach/tty-editor/compare/v0.5.0...v0.5.1
105
+ [v0.5.0]: https://github.com/piotrmurach/tty-editor/compare/v0.4.1...v0.5.0
106
+ [v0.4.1]: https://github.com/piotrmurach/tty-editor/compare/v0.4.0...v0.4.1
49
107
  [v0.4.0]: https://github.com/piotrmurach/tty-editor/compare/v0.3.0...v0.4.0
50
108
  [v0.3.0]: https://github.com/piotrmurach/tty-editor/compare/v0.2.1...v0.3.0
51
109
  [v0.2.1]: https://github.com/piotrmurach/tty-editor/compare/v0.2.0...v0.2.1
52
110
  [v0.2.0]: https://github.com/piotrmurach/tty-editor/compare/v0.1.2...v0.2.0
53
111
  [v0.1.2]: https://github.com/piotrmurach/tty-editor/compare/v0.1.1...v0.1.2
54
112
  [v0.1.1]: https://github.com/piotrmurach/tty-editor/compare/v0.1.0...v0.1.1
55
- [v0.1.0]: https://github.com/piotrmurach/tty-editor/compare/v0.1.0
113
+ [v0.1.0]: https://github.com/piotrmurach/tty-editor/compare/762a7ec...v0.1.0
data/LICENSE.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  The MIT License (MIT)
2
2
 
3
- Copyright (c) 2016 Piotr Murach
3
+ Copyright (c) 2016 Piotr Murach (piotrmurach.com)
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
data/README.md CHANGED
@@ -1,21 +1,25 @@
1
+ <div align="center">
2
+ <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a>
3
+ </div>
4
+
1
5
  # TTY::Editor [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
2
6
 
3
7
  [![Gem Version](https://badge.fury.io/rb/tty-editor.svg)][gem]
4
- [![Build Status](https://secure.travis-ci.org/piotrmurach/tty-editor.svg?branch=master)][travis]
8
+ [![Actions CI](https://github.com/piotrmurach/tty-editor/workflows/CI/badge.svg?branch=master)][gh_actions_ci]
5
9
  [![Build status](https://ci.appveyor.com/api/projects/status/yw4guy16meq5wkee?svg=true)][appveyor]
6
10
  [![Maintainability](https://api.codeclimate.com/v1/badges/0afb9e75eef4ae4615c6/maintainability)][codeclimate]
7
11
  [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-editor/badge.svg)][coverage]
8
- [![Inline docs](http://inch-ci.org/github/piotrmurach/tty-editor.svg?branch=master)][inchpages]
12
+ [![Inline docs](https://inch-ci.org/github/piotrmurach/tty-editor.svg?branch=master)][inchpages]
9
13
 
10
14
  [gitter]: https://gitter.im/piotrmurach/tty
11
- [gem]: http://badge.fury.io/rb/tty-editor
12
- [travis]: http://travis-ci.org/piotrmurach/tty-editor
15
+ [gem]: https://badge.fury.io/rb/tty-editor
16
+ [gh_actions_ci]: https://github.com/piotrmurach/tty-editor/actions?query=workflow%3ACI
13
17
  [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-editor
14
18
  [codeclimate]:https://codeclimate.com/github/piotrmurach/tty-editor/maintainability
15
19
  [coverage]: https://coveralls.io/github/piotrmurach/tty-editor
16
- [inchpages]: http://inch-ci.org/github/piotrmurach/tty-editor
20
+ [inchpages]: https://inch-ci.org/github/piotrmurach/tty-editor
17
21
 
18
- > Opens a file or text in the user's preferred editor.
22
+ > Open a file or text in a preferred terminal text editor.
19
23
 
20
24
  **TTY::Editor** provides independent component for [TTY](https://github.com/piotrmurach/tty) toolkit.
21
25
 
@@ -24,7 +28,7 @@
24
28
  Add this line to your application's Gemfile:
25
29
 
26
30
  ```ruby
27
- gem 'tty-editor'
31
+ gem "tty-editor"
28
32
  ```
29
33
 
30
34
  And then execute:
@@ -35,72 +39,279 @@ Or install it yourself as:
35
39
 
36
40
  $ gem install tty-editor
37
41
 
38
- ## Usage
42
+ ## Contents
43
+
44
+ * [1. Usage](#1-usage)
45
+ * [2. API](#2-api)
46
+ * [2.1 new](#21-new)
47
+ * [2.1.1 :command](#211-command)
48
+ * [2.1.2 :env](#212-env)
49
+ * [2.1.3 :raise_on_failure](#213-raise_on_failure)
50
+ * [2.1.4 :prompt](#214-prompt)
51
+ * [2.1.5 :hide_menu](#215-hide_menu)
52
+ * [2.1.6 :enable_color](#216-enable_color)
53
+ * [2.1.7 :menu_interrupt](#217-menu_interrupt)
54
+ * [2.2 open](#22-open)
55
+ * [3. Default Editors](#3-default-editors)
39
56
 
40
- To edit a file in default editor:
57
+ ## 1. Usage
58
+
59
+ To edit a file in a default text editor do:
41
60
 
42
61
  ```ruby
43
- TTY::Editor.open('hello.rb')
62
+ TTY::Editor.open("/path/to/file")
44
63
  ```
45
64
 
46
- To edit content in a default editor:
65
+ To edit text in a default editor:
47
66
 
48
67
  ```ruby
49
- TTY::Editor.open(content: "some text")
68
+ TTY::Editor.open(text: "Some text")
50
69
  ```
51
70
 
52
- You can also set your preferred editor command:
71
+ You can also open multiple existing and/or new files:
53
72
 
54
73
  ```ruby
55
- TTY::Editor.open('hello.rb', command: :vim)
74
+ TTY::Editor.open("file_1", "file_2", "new_file_3")
75
+ ```
76
+
77
+ Note that the `VISUAL` or `EDITOR` shell environment variables take precedence when auto detecting available editors.
78
+
79
+ You can also set your preferred editor command(s) and ignore `VISUAL` and `EDITOR` as well as other user preferences:
80
+
81
+ ```ruby
82
+ TTY::Editor.open("/path/to/file", command: "vim -f")
83
+ ```
84
+
85
+ When `VISUAL` or `EDITOR` are not specified, a selection menu will be presented to the user.
86
+
87
+ For example, if an user has `code`, `emacs` and `vim` editors available on their system, they will see the following menu:
88
+
89
+ ```
90
+ Select an editor?
91
+ 1) code
92
+ 2) emacs
93
+ 3) vim
94
+ Choose 1-3 [1]:
56
95
  ```
57
96
 
58
- Also, the `VISUAL` or `EDITOR` shell environment variables take precedencee when auto detecting available editors.
97
+ 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).
59
98
 
60
- ## Interface
99
+ ## 2. API
61
100
 
62
- ### open
101
+ ### 2.1 new
63
102
 
64
- If you wish to open editor with no file or content do:
103
+ Instantiation of an editor will trigger automatic search for available command-line editors:
65
104
 
66
105
  ```ruby
67
- TTY::Editor.open
106
+ editor = TTY::Editor.new
68
107
  ```
69
108
 
70
- When editor successfully opens file or content then `true` is returned.
109
+ You can change default search with the `:command` keyword argument.
71
110
 
72
- If the editor cannot be opened, a `TTY::Editor::CommandInvocation` error is raised.
111
+ #### 2.1.1 :command
73
112
 
74
- In order to open text content inside an editor do:
113
+ You can force to always use a specific editor by passing `:command` option:
75
114
 
76
115
  ```ruby
77
- TTY::Editor.open(content: 'text')
116
+ editor = TTY::Editor.new(command: "vim")
78
117
  ```
79
118
 
80
- You can also provide filename that will be created with specified content before editor is opened:
119
+ Or you can specify multiple commands and give a user a choice:
81
120
 
82
121
  ```ruby
83
- TTY::Editor.open('new.rb', content: 'text')
122
+ editor = TTY::Editor.new(command: ["vim", "emacs"])
84
123
  ```
85
124
 
86
- If you open a filename with already existing content then new content gets appended at the end of the file.
125
+ The class-level `open` method accepts the same parameters:
87
126
 
88
- ### :env
127
+ ```ruby
128
+ TTY::Editor.open("/path/to/file", command: "vim")
129
+ ```
130
+
131
+ #### 2.1.2 :env
89
132
 
90
- Use `:env` key to forward environment variables to the editor.
133
+ Use `:env` key to forward environment variables to the text editor launch command:
91
134
 
92
135
  ```ruby
93
- TTY::Editor.open('hello.rb', env: {"FOO" => "bar"})
136
+ TTY::Editor.new(env: {"FOO" => "bar"})
94
137
  ```
95
138
 
96
- ### :command
139
+ The class-level `open` method accepts the same parameters:
97
140
 
98
- You can force to always use a specific editor by passing `:command` option:
141
+ ```ruby
142
+ TTY::Editor.open("/path/to/file", env: {"FOO" => "bar"})
143
+ ```
144
+
145
+ #### 2.1.3 :raise_on_failure
146
+
147
+ By default when editor fails to open a `false` status is returned:
148
+
149
+ ```ruby
150
+ TTY::Editor.open("/path/to/unknown/file") # => false
151
+ ```
152
+
153
+ Alternatively, you can use `:raise_on_failure` to raise an error on failure to open a file.
154
+
155
+ The `TTY::Editor::CommandInvocationError` will be raised anytime an editor fails to open a file:
156
+
157
+ ```ruby
158
+ editor = TTY::Editor.new(raise_on_failure: true)
159
+ editor.open("/path/to/unknown/file")
160
+ # => raises TTY::Editor::ComandInvocationError
161
+ ```
162
+
163
+ #### 2.1.4 :prompt
164
+
165
+ 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.
166
+
167
+ For example, when `code`, `emacs` and `vim` executable exists on the system, the following menu will be displayed:
168
+
169
+ ```
170
+ Select an editor?
171
+ 1) code
172
+ 2) emacs
173
+ 3) vim
174
+ Choose 1-3 [1]:
175
+ ```
176
+
177
+ If you would like to change the menu prompt use `:prompt` keyword:
178
+
179
+ ```ruby
180
+ editor = TTY::Editor.new(prompt: "Which one do you fancy?")
181
+ editor.open("/path/to/file")
182
+ ```
183
+
184
+ This may produce the following in the terminal:
185
+
186
+ ```
187
+ Which one do you fancy?
188
+ 1) code
189
+ 2) emacs
190
+ 3) vim
191
+ Choose 1-3 [1]:
192
+ ```
193
+
194
+ #### 2.1.5 :hide_menu
195
+
196
+ When more than one editor is available from the default list, a selection menu will be displayed in the console:
197
+
198
+ ```
199
+ Select an editor?
200
+ 1) code
201
+ 2) emacs
202
+ 3) vim
203
+ Choose 1-3 [1]:
204
+ ```
205
+
206
+ To hide the menu and automatically choose the first available editor use the `:hide_menu` keyword option:
99
207
 
100
208
  ```ruby
101
- TTY::Editor.open('hello.rb', command: :vim)
209
+ editor = TTY::Editor.new(hide_menu: true)
102
210
  ```
103
211
 
212
+ #### 2.1.6 :enable_color
213
+
214
+ 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:
215
+
216
+ ```ruby
217
+ editor = TTY::Editor.new(enable_color: false)
218
+ ```
219
+
220
+ Equally, you can enforce the current menu choice to be always coloured:
221
+
222
+ ```ruby
223
+ editor = TTY::Editor.new(enable_color: true)
224
+ ```
225
+
226
+ ### 2.1.7 :menu_interrupt
227
+
228
+ 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:
229
+
230
+ * `:error` - raises `InputInterrupt` error
231
+ * `:exit` - exits with `130` status code
232
+ * `:noop` - skips handler
233
+ * `:signal` - sends interrupt signal
234
+ * `proc` - custom proc handler
235
+
236
+ For example, to immediately exit the menu and program do:
237
+
238
+ ```ruby
239
+ editor = TTY::Editor.new(menu_interrupt: :exit)
240
+ ```
241
+
242
+ ### 2.2 open
243
+
244
+ There is a class-level and instance-level `open` method. These are equivalent:
245
+
246
+ ```ruby
247
+ editor = TTY::Editor.new
248
+ editor.open(...)
249
+ # or
250
+ TTY::Editor.open(...)
251
+ ```
252
+
253
+ 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.
254
+
255
+ Conversely, the class-level `open` method will search for an editor each time it is invoked.
256
+
257
+ The following examples of using the `open` method apply to both the instance and class level invocations.
258
+
259
+ If you wish to open an editor without giving a file or content do:
260
+
261
+ ```ruby
262
+ TTY::Editor.open
263
+ ```
264
+
265
+ To open a file, pass a path as an argument to `open`:
266
+
267
+ ```ruby
268
+ TTY::Editor.open("../README.md")
269
+ # => true
270
+ ```
271
+
272
+ When editor successfully opens a file or content then `true` is returned, `false` otherwise.
273
+
274
+ You can change this with `:raise_on_failure` keyword to raise a `TTY::Editor::CommandInvocation` error when an editor cannot be opened.
275
+
276
+ In order to open text content inside an editor use `:text` keyword like so:
277
+
278
+ ```ruby
279
+ TTY::Editor.open(text: "Some text")
280
+ ```
281
+
282
+ You can also provide filename that will be created with specified content before editor is opened:
283
+
284
+ ```ruby
285
+ TTY::Editor.open("/path/to/new-file", text: "Some text")
286
+ ```
287
+
288
+ If you open a filename with already existing content then the new content will be appended at the end of the file.
289
+
290
+ You can also open multiple existing and non-existing files providing them as consecutive arguments:
291
+
292
+ ```ruby
293
+ TTY::Editor.open("file_1", "file_2", "new_file_3")
294
+ ```
295
+
296
+ ## 3. Default Editors
297
+
298
+ 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:
299
+
300
+ * `Atom`
301
+ * `Emacs`
302
+ * `gedit`
303
+ * `JED`
304
+ * `Kate`
305
+ * `Mg`
306
+ * `Nano`
307
+ * `Notepad`
308
+ * `Pico`
309
+ * `Sublime Text`
310
+ * `TextMate`
311
+ * `Vi`
312
+ * `Vim`
313
+ * `Visual Studio Code`
314
+
104
315
  ## Development
105
316
 
106
317
  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
109
320
 
110
321
  ## Contributing
111
322
 
112
- 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.
323
+ 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).
113
324
 
114
325
  ## License
115
326
 
116
327
  The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
117
328
 
329
+ ## Code of Conduct
330
+
331
+ 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).
332
+
118
333
  ## Copyright
119
334
 
120
- Copyright (c) 2017-2018 Piotr Murach. See LICENSE for further details.
335
+ Copyright (c) 2017 Piotr Murach. See LICENSE for further details.