NAME

Term::CallEditor - solicit data from an external editor

SYNOPSIS

  use Term::CallEditor qw/solicit/;

  my $fh = solicit('FOO: please replace this text');
  die "$Term::CallEditor::errstr\n" unless $fh;

  print while readline $fh;

DESCRIPTION

This module calls an external editor via the "solicit()" function, then returns any data from this editor as a file handle. The environment variables "VISUAL" and then "EDITOR" are consulted for a program name to run, otherwise falling back to vi(1). The Text::ParseWords "shellwords()" function is used to expand the environment variables.

"solicit()" returns a temporary file handle pointing to what was written in the editor (and also the filename in list context).

FUNCTION

solicit

"solicit()" as a second argument accepts a number of optional parameters as a hash reference.

  solicit(
      "\x{8ACB}",
      {   skip_interactive => 1,
          binmode_layer    => ':utf8'
      }
  );

BINMODE => BOOLEAN: If true, enables "binmode" on the filehandle prior to writing the message to it.
DEFAULT_EDITOR => string: What to use as the default editor instead of vi(1).
NOSYNC => BOOLEAN: If true, "sync()" from IO::Handle will not be called. "sync()" is not called when on Win32, but otherwise is called by default.
binmode_layer => binmode layer: If set, enables "binmode" on the filehandle prior to writing the message to it.
safe_level => NUMBER: Set a custom "safe_level" value for the File::Temp method of that name.
skip_interactive => BOOLEAN: If true, "solicit" skips making a test to see whether the terminal is interactive.

On error, "solicit()" returns "undef". Consult $Term::CallEditor::errstr for details. Note that File::Temp may throw a fatal error if the "safe_level" checks fail, so paranoid coders should wrap the "solicit" call in an "eval" block (or instead use something like Syntax::Keyword::Try).

EXAMPLES

See also the "eg/solicit" script under the module distribution.

Pass in a block of text to the editor

Use a here doc:

  my $fh = solicit(<< "END_BLARB");

  FOO: This is an example designed to span multiple lines for
  FOO: the sake of an example that span multiple lines.
  END_BLARB

Shell Exec Wrapper

A shell exec wrapper may be necessary as a target for EDITOR (or VISUAL) as not all programs that support EDITOR (or VISUAL) perform shell word splitting on the input, and the "shellword" splitting (now) done by this module may not suffice for complicated shell commands:

  #!/bin/sh
  exec youreditor --some-arg "$@"

BUGS

No known bugs.

Reporting Bugs

Newer versions of this module may be available from CPAN.

If the bug is in the latest version, send a report to the author. Patches that fix problems or add new features are welcome.

<https://github.com/thrig/Term-CallEditor>

Known Issues

This module relies heavily on the Unix terminal, permissions on the temporary directory (for the File::Temp module "safe_level" call), whether "system()" can actually run the "EDITOR" environment variable, and so forth.

AUTHOR

thrig - Jeremy Mates (cpan:JMATES) "<jmates at cpan.org>"

COPYRIGHT

This program is distributed under the (Revised) BSD License: <https://opensource.org/licenses/BSD-3-Clause>

HISTORY

Inspired from the CVS prompt-user-for-commit-message functionality.