Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Proc::InvokeEditor(3) User Contributed Perl DocumentationProc::InvokeEditor(3)

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
       o   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.32.1			  2017-08-16		 Proc::InvokeEditor(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | WINDOWS SUPPORT | TODO | AUTHOR | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Proc::InvokeEditor&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help