/ 
Term-CallEditor-0.65
River stage one • 2 direct dependents • 2 total dependents
/ Term::CallEditor

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 <$fh>;

DESCRIPTION

This module calls an external editor with an optional text message via the solicit() function, then returns any data from this editor as a file handle. By default, the EDITOR environment variable will be used, otherwise vi.

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

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.

binmode_layer => binmode layer

If set, enables binmode on the filehandle prior to writing the message to it. Useful if one needs to write UTF-8 or some other encoded data as a message to the EDITOR.

safe_level => NUMBER

Set a custom safe_level value for the File::Temp method of that name. The default safe_level is number 2. Be seeing you.

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.

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
Support bbedit(1) on Mac OS X

To use BBEdit as the external editor, create a shell script wrapper to call bbedit(1), then set this wrapper as the EDITOR environment variable. The -t option to bbedit(1) can be used to set a custom title, if desired.

#!/bin/sh
exec bbedit -w "$@"

Any editor that requires arguments will require a wrapper like this.

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.

http://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.

SEE ALSO

vipe(1) of moreutils to use vi(1) in pipes.

AUTHOR

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

COPYRIGHT

Copyright 2004-2005,2009-2010,2012 Jeremy Mates

This module is free software; you can redistribute it and/or modify it under the Artistic License (2.0).

HISTORY

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