1Proc::InvokeEditor(3) User Contributed Perl DocumentationProc::InvokeEditor(3)
2
3
4

NAME

6       Proc::InvokeEditor - Perl extension for starting a text editor
7

SYNOPSIS

9         use Proc::InvokeEditor;
10         my $edited_text = Proc::InvokeEditor->edit($unedited_text);
11

DESCRIPTION

13       This module provides the ability to supply some text to an external
14       text editor, have it edited by the user, and retrieve the results.
15
16       The File::Temp module is used to provide secure, safe temporary files,
17       and File::Temp is set to its highest available level of security. This
18       may cause problems on some systems where no secure temporary directory
19       is available.
20
21       When the editor is started, no subshell is used. Your path will be
22       scanned to find the binary to use for each editor if the string given
23       does not exist as a file, and if a named editor contains whitespace,
24       eg) if you try to use the editor "xemacs -nw", then the string will be
25       split on whitespace and anything after the editor name will be passed
26       as arguments to your editor. A shell is not used but this should cover
27       most simple cases.
28

METHODS

30   new(editors => [ editor list ], cleanup => 1)
31       This method creates a new Proc::InvokeEditor object. It takes two
32       optional arguments in key => value form:
33
34       "editors"
35           This should be a reference to an array of possible editor filenames
36           to use. Each editor listed will be tried in turn until a working
37           editor is found. If this argument is not supplied, an internal
38           default list will be used.
39
40       "cleanup"
41           This specifies whether the temporary file created should be
42           unlinked when the program exits. The default is to unlink the file.
43
44       "keep_file"
45           This specifies whether to reuse the same temporary file between
46           invocations of "edit" on the same Proc::InvokeEditor object. The
47           default is to use a new file each time.
48
49   editors()
50       This method gets or sets the list of editors to use.  If no argument is
51       supplied, it returns the current value from the object, if an argument
52       is supplied, it changes the value and returns the new value.  The
53       argument should be a reference to a list of text editor filenames.
54
55   editors_env($arrayref)
56       Takes a reference to an array of %ENV keys to use as possible editors.
57       Each $ENV{$key} value is only used if that key exits in %ENV and the
58       value is defined. The new values are prepended to the currently stored
59       list of editors to use.
60
61   editors_prepend($arrayref)
62       Takes a reference to an array of editors to use, and prepends them to
63       the currently stored list.
64
65   cleanup()
66       This method gets or sets whether to cleanup temporary files after the
67       program exits. If no argument is supplied, it returns the current value
68       from the object. If an argument is supplied, it changes the value and
69       returns the new object. The argument should be any true or false value.
70
71   keep_file()
72       This method gets or sets whether to reuse temporary files. If no
73       argument is supplied, it returns the current value from the object. If
74       an argument is supplied, it changes the value and returns the new
75       object. The argument should be any true or false value.
76
77   first_usable()
78       This method can be called either as a class method, in which it returns
79       the first usable editor of the default list of editors, or as an object
80       method, in which case it returns the first usable editor of the
81       currently configured list.
82
83       The return is a reference to an array, the first element of which is a
84       filename, and the other elements of which are appropriate arguments to
85       the the command.
86
87       If this method can not find any usable editor, it will die.
88
89   edit($unedited_text)
90       This can be called as either a class method or an object method.
91
92       When called as a class method, it starts an external text editor in the
93       text supplied, and returns the result to you. The text to edit can be
94       supplied either as a scalar, in which case it will be treated as a
95       simple string, or as a reference to an array, in which case it will be
96       treated as an array of lines.
97
98       Example use of this form is as follows:
99
100         my $result = Proc::InvokeEditor->edit($string);
101
102         my @lines = Proc::InvokeEditor->edit(\@unedited_lines);
103
104         my @lines = Proc::InvokeEditor->edit($string);
105
106       When called as an object method, it behaves identically, but uses
107       configuration parameters from the object:
108
109         my $editor = new Proc::InvokeEditor(editors => [ '/usr/bin/emacs' ]);
110         $editor->cleanup(0);
111         my $result = $editor->edit($string);
112
113       A optional second argument is available $suff - example usage:
114
115               my $reuslt = Proc::InvokeEditor->edit($string, '.xml');
116
117       This specifies a filename suffix to be used when the editor is launched
118       - this can be useful if the data in the file is of a particular type
119       and you want to trigger an editor's syntax highlighting mode.
120

WINDOWS SUPPORT

122       On Windows, the parsing is a bit different and uses shell parsing
123       respecting double quoted paths as the first item for the editor.
124
125       The following might work to use Notepad++ as your editor with this
126       module or "git"
127
128           set EDITOR="c:\Program Files\Notepad++\notepad++.exe" -multiInst -nosession -notabbar
129

TODO

131       •   Write a test suite.
132

AUTHOR

134       Michael Stevens <mstevens@etla.org>. Also incorporating suggestions and
135       feedback from Leon Brocard and Phil Pennock.
136
137       Patches supplied by Tim Booth.
138

SEE ALSO

140       perl.
141

LICENSE

143       This is free software; you can redistribute it and/or modify it under
144       the same terms as Perl 5.
145
146
147
148perl v5.36.0                      2023-01-20             Proc::InvokeEditor(3)
Impressum