NAME

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

SYNOPSIS

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

DESCRIPTION

       This module provides the ability to supply some text to an external text editor, have it edited by the
       user, and retrieve the results.

       The File::Temp module is used to provide secure, safe temporary files, and File::Temp is set to its
       highest available level of security. This may cause problems on some systems where no secure temporary
       directory is available.

       When the editor is started, no subshell is used. Your path will be scanned to find the binary to use for
       each editor if the string given does not exist as a file, and if a named editor contains whitespace, eg)
       if you try to use the editor "xemacs -nw", then the string will be split on whitespace and anything after
       the editor name will be passed as arguments to your editor. A shell is not used but this should cover
       most simple cases.

METHODS

   new(editors => [ editor list ], cleanup => 1)
       This method creates a new Proc::InvokeEditor object. It takes two optional arguments in key => value
       form:

       "editors"
           This  should  be a reference to an array of possible editor filenames to use. Each editor listed will
           be tried in turn until a working editor is found. If this  argument  is  not  supplied,  an  internal
           default list will be used.

       "cleanup"
           This  specifies  whether  the  temporary  file created should be unlinked when the program exits. The
           default is to unlink the file.

       "keep_file"
           This specifies whether to reuse the same temporary file between invocations of  "edit"  on  the  same
           Proc::InvokeEditor object. The default is to use a new file each time.

   editors()
       This  method gets or sets the list of editors to use.  If no argument is supplied, it returns the current
       value from the object, if an argument is supplied, it changes the value and returns the new  value.   The
       argument should be a reference to a list of text editor filenames.

   editors_env($arrayref)
       Takes  a  reference  to  an array of %ENV keys to use as possible editors.  Each $ENV{$key} value is only
       used if that key exits in %ENV and the value is defined. The new values are prepended  to  the  currently
       stored list of editors to use.

   editors_prepend($arrayref)
       Takes a reference to an array of editors to use, and prepends them to the currently stored list.

   cleanup()
       This  method  gets  or sets whether to cleanup temporary files after the program exits. If no argument is
       supplied, it returns the current value from the object. If an argument is supplied, it changes the  value
       and returns the new object. The argument should be any true or false value.

   keep_file()
       This  method  gets  or  sets whether to reuse temporary files. If no argument is supplied, it returns the
       current value from the object. If an argument is supplied, it changes  the  value  and  returns  the  new
       object. The argument should be any true or false value.

   first_usable()
       This  method  can  be called either as a class method, in which it returns the first usable editor of the
       default list of editors, or as an object method, in which case it returns the first usable editor of  the
       currently configured list.

       The  return  is a reference to an array, the first element of which is a filename, and the other elements
       of which are appropriate arguments to the the command.

       If this method can not find any usable editor, it will die.

   edit($unedited_text)
       This can be called as either a class method or an object method.

       When called as a class method, it starts an external text editor in the text supplied,  and  returns  the
       result to you. The text to edit can be supplied either as a scalar, in which case it will be treated as a
       simple string, or as a reference to an array, in which case it will be treated as an array of lines.

       Example use of this form is as follows:

         my $result = Proc::InvokeEditor->edit($string);

         my @lines = Proc::InvokeEditor->edit(\@unedited_lines);

         my @lines = Proc::InvokeEditor->edit($string);

       When  called  as  an  object  method,  it behaves identically, but uses configuration parameters from the
       object:

         my $editor = new Proc::InvokeEditor(editors => [ '/usr/bin/emacs' ]);
         $editor->cleanup(0);
         my $result = $editor->edit($string);

       A optional second argument is available $suff - example usage:

               my $reuslt = Proc::InvokeEditor->edit($string, '.xml');

       This specifies a filename suffix to be used when the editor is launched - this can be useful if the  data
       in the file is of a particular type and you want to trigger an editor's syntax highlighting mode.

WINDOWS SUPPORT

       On  Windows,  the parsing is a bit different and uses shell parsing respecting double quoted paths as the
       first item for the editor.

       The following might work to use Notepad++ as your editor with this module or "git"

           set EDITOR="c:\Program Files\Notepad++\notepad++.exe" -multiInst -nosession -notabbar

TODO

       •   Write a test suite.

AUTHOR

       Michael Stevens <mstevens@etla.org>. Also incorporating suggestions and feedback from  Leon  Brocard  and
       Phil Pennock.

       Patches supplied by Tim Booth.

SEE ALSO

       perl.

LICENSE

       This is free software; you can redistribute it and/or modify it under the same terms as Perl 5.

perl v5.36.0                                       2022-11-19                            Proc::InvokeEditor(3pm)