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.

The optional arguments to solicit() are:

1. The first argument to the solicit() function contains an optional message to print in the external editor. The module supports different input formats, including a scalar, scalar reference, array, or objects with the getlines method (IO::Handle or IO::All, for example).

2. If the optional second parameter to solicit() is set to true, the module will skip the check whether the terminal is interactive. This may be necessary if the EDITOR can run in some non-terminal environment, and the code is not running under a terminal.

On error, solicit() returns undef. Consult $Term::CallEditor::errstr for details.

EXAMPLES

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 the sake
  FOO: 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.

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

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 File::Temp-safe_level), whether system() can actually run the EDITOR environment variable, and so forth.

AUTHOR

Jeremy Mates, <jmates@sial.org>

COPYRIGHT

Copyright 2004-2005,2009-2010 Jeremy Mates

This program is free software; you can redistribute it and/or modify it under the Artistic license.

HISTORY

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