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.

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.