1 | # External Editor
|
2 |
|
3 | [![ExternalEditor on Travis CI](https://img.shields.io/travis/mrkmg/node-external-editor.svg?style=flat-square)](https://travis-ci.org/mrkmg/node-external-editor/branches)
|
4 | [![ExternalEditor on NPM](https://img.shields.io/npm/v/external-editor.svg?style=flat-square)](https://www.npmjs.com/package/external-editor)
|
5 | [![ExternalEditor uses the MIT](https://img.shields.io/npm/l/external-editor.svg?style=flat-square)](https://opensource.org/licenses/MIT)
|
6 |
|
7 |
|
8 | A node module to edit a string with a users preferred text editor using $VISUAL or $ENVIRONMENT.
|
9 |
|
10 | Version: 2.0.1
|
11 |
|
12 | As of version 2.0.0, node 0.10 is no longer support. Minimum node version is now 0.12.
|
13 |
|
14 | ##Install
|
15 |
|
16 | `npm install external-editor --save`
|
17 |
|
18 | ##Usage
|
19 |
|
20 | A simple example using the `.edit` convenience method
|
21 |
|
22 | var ExternalEditor = require('external-editor')
|
23 | var data = ExternalEditor.edit('\n\n# Please write your text above');
|
24 | console.log(data);
|
25 |
|
26 | A full featured example
|
27 |
|
28 | var ExternalEditor = require('external-editor');
|
29 |
|
30 | try {
|
31 | var editor = new ExternalEditor();
|
32 | var text = editor.run()
|
33 | // the text is also available in editor.text
|
34 | } catch (err) {
|
35 | if (err instanceOf ExternalEditor.CreateFileError) {
|
36 | console.log('Failed to create the temporary file');
|
37 | } else if (err instanceOf ExternalEditor.ReadFileError) {
|
38 | console.log('Failed to read the temporary file');
|
39 | } else if (err instanceOf ExternalEditor.LaunchEditorError) {
|
40 | console.log('Failed to launch your editor');
|
41 | } else {
|
42 | throw err;
|
43 | }
|
44 | }
|
45 |
|
46 | // Do things with the text
|
47 |
|
48 | // Eventually call the cleanup to remove the temporary file
|
49 | try {
|
50 | editor.cleanup();
|
51 | } catch (err) {
|
52 | if (err instanceOf ExternalEditor.RemoveFileError) {
|
53 | console.log('Failed to remove the temporary file');
|
54 | } else {
|
55 | throw err
|
56 | }
|
57 | }
|
58 |
|
59 |
|
60 | ####API
|
61 | **Static Methods**
|
62 | - `edit(text)`
|
63 | - `text` (string) *Optional* Defaults to empty string
|
64 | - **Returns** (string) The contents of the file
|
65 | - Could throw `CreateFileError`, `ReadFileError`, or `LaunchEditorError`, or `RemoveFileError`
|
66 | - `editAsync(text, callback)`
|
67 | - `text` (string) *Optional* Defaults to empty string
|
68 | - `callback` (function (error, text))
|
69 | - `error` could be of type `CreateFileError`, `ReadFileError`, or `LaunchEditorError`, or `RemoveFileError`
|
70 | - `text`(string) The contents of the file
|
71 |
|
72 |
|
73 | **Static Properties**
|
74 | - `CreateFileError` Error thrown if the temporary file could not be created.
|
75 | - `ReadFileError` Error thrown if the temporary file could not be read.
|
76 | - `RemoveFileError` Error thrown if the temporary file could not be removed during cleanup.
|
77 | - `LaunchEditorError` Error thrown if the editor could not be launched.
|
78 |
|
79 | **Public Methods**
|
80 | - `new ExternalEditor(text)`
|
81 | - `text` (string) *Optional* Defaults to empty string
|
82 | - Could throw `CreateFileError`
|
83 | - `run()` Launches the editor.
|
84 | - **Returns** (string) The contents of the file
|
85 | - Could throw `LaunchEditorError` or `ReadFileError`
|
86 | - `runAsync(callback)` Launches the editor in an async way
|
87 | - `callback` (function (error, text))
|
88 | - `error` could be of type `ReadFileError` or `LaunchEditorError`
|
89 | - `text`(string) The contents of the file
|
90 | - `cleanup()` Removes the temporary file.
|
91 | - Could throw `RemoveFileError`
|
92 |
|
93 | **Public Properties**
|
94 | - `text` (string) *readonly* The text in the temporary file.
|
95 | - `editor.bin` (string) The editor determined from the environment.
|
96 | - `editor.args` (array) Default arguments for the bin
|
97 | - `temp_file` (string) Path to temporary file. Can be changed, but be careful as the temporary file probably already
|
98 | exists and would need be removed manually.
|
99 |
|
100 | ##Errors
|
101 |
|
102 | All errors have a simple message explaining what went wrong. They all also have an `original_error` property containing
|
103 | the original error thrown for debugging purposes.
|
104 |
|
105 | ##Why Synchronous?
|
106 |
|
107 | Everything is synchronous to make sure the editor has complete control of the stdin and stdout. Testing has shown
|
108 | async launching of the editor can lead to issues when using readline or other packages which try to read from stdin or
|
109 | write to stdout. Seeing as this will be used in an interactive CLI environment, I made the decision to force the package
|
110 | to be synchronous. If you know a reliable way to force all stdin and stdout to be limited only to the child_process,
|
111 | please submit a PR.
|
112 |
|
113 | If async is really needed, you can use `editAsync` or `runAsync`. If you are using readline or have anything else
|
114 | listening to the stdin or you write to stdout, you will most likely have problem, so make sure to remove any other
|
115 | listeners on stdin, stdout, or stdin.
|
116 |
|
117 | ##Demo
|
118 |
|
119 | [![asciicast](https://asciinema.org/a/a1qh9lypbe65mj0ivfuoslz2s.png)](https://asciinema.org/a/a1qh9lypbe65mj0ivfuoslz2s)
|
120 |
|
121 | ##License
|
122 |
|
123 | The MIT License (MIT)
|
124 |
|
125 | Copyright (c) 2016 Kevin Gravier
|
126 |
|
127 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
128 | of this software and associated documentation files (the "Software"), to deal
|
129 | in the Software without restriction, including without limitation the rights
|
130 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
131 | copies of the Software, and to permit persons to whom the Software is
|
132 | furnished to do so, subject to the following conditions:
|
133 |
|
134 | The above copyright notice and this permission notice shall be included in all
|
135 | copies or substantial portions of the Software.
|
136 |
|
137 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
138 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
139 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
140 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
141 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
142 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
143 | SOFTWARE.
|