Proc::...Editor(3pm)

💖 Proc::InvokeEditor — bestie edition 💖

okay so this is the Proc::...Editor(3pm) page from the User Contributed Perl Documentation, and honestly? it's a bop. it's Proc::InvokeEditor, a Perl extension for starting a text editor, and it is exactly as useful as it sounds. let's get into it 🫶

---

✨ NAME ✨

Proc::InvokeEditor — a Perl extension for starting a text editor. that's it, that's the whole vibe 💅

---

🌸 SYNOPSIS 🌸

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

look at her. three lines. iconic. 👑

---

🦋 DESCRIPTION 🦋

so what does this actually do? this module gives you the ability to hand some text off to an external text editor, let the user go to town on it, and then get the results back. that's the whole deal, no cap.

The File::Temp module is used to provide secure, safe temporary files, and File::Temp is set to its highest available level of security. heads up though: this may cause problems on some systems where no secure temporary directory is available. so like, if your box is weird about temp dirs, that's on the box, not on you 😭

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. lowkey clever ngl 🧚

---

🎀 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. (yes, the heading says "two optional arguments" and then lists three things. we don't ask questions, we just vibe 🙈)
• "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. simple, clean, does what it says 💜

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. that's it. go off ✨

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. (the double "the the" is in the source, bestie, we are simply respecting the author's choices 🫶)

if this method can not find any usable editor, it will die. like, actually die. rest in peace.

edit($unedited_text)

this can be called as either a class method or an object method.

class method energy 👑

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);

object method energy 👑

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);

the optional second argument 🌟

a optional second argument is available $suff — example usage:

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

(yes, $reuslt. keeping it exactly as written. we love a typo that made it to prod 💀)

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. cute, right? 🌈

---

🖥️ 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

"might work" is doing a lot of heavy lifting in that sentence but we support her 💅

---

📝 TODO 📝

1. Write a test suite.

that's the whole list. one item. the confidence. the audacity. honestly? obsessed 🔥

---

👑 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.

---

and that's the whole page, bestie!! this one's from perl v5.36.0, dated 2022-11-19, and it lives under the name Proc::...Editor(3pm) in the User Contributed Perl Documentation. go edit some text, you absolute main character 💖✨🎀