NAME

ClearCase::ClearPrompt - Handle clearprompt in a portable, convenient way

SYNOPSIS

use ClearCase::ClearPrompt qw(clearprompt clearprompt_dir);

# boolean usage
my $rc = clearprompt(qw(yes_no -mask y,n -type ok -prompt), 'Well?');

# returns text into specified variable (context sensitive).
my $txt = clearprompt(qw(text -pref -pro), 'Enter text data here: ');

# asynchronous usage - show dialog box and continue
clearprompt(qw(proceed -mask p -type ok -prompt), "You said: $txt");

# prompt for a directory (not supported natively by clearprompt cmd)
my $dir = clearprompt_dir('/tmp', "Please choose a directory");

DESCRIPTION

Native ClearCase provides a utility (clearprompt) for collecting user input or displaying messages within triggers. However, usage of this tool is awkward and error-prone, especially in multi-platform environments. Often you must create temp files, invoke clearprompt to write into them, open them and read the data, then unlink them. In many cases this code must run seamlessly on both Unix and Windows systems and is replicated throughout many trigger scripts. ClearCase::ClearPrompt abstracts this dirty work without changing the interface to clearprompt.

The clearprompt() function takes the exact same set of flags as the eponymous ClearCase command, e.g.:

my $response = clearprompt('text', '-def', '0', '-pro', 'Well? ');

except that the -outfile flag is unnecessary since creation, reading, and removal of this temp file is managed internally.

In a void context, clearprompt() behaves asynchronously; i.e. it displays the dialog box and returns so that execution can continue. In any other context it waits for the dialog's button to be pushed and returns the appropriate data type.

The clearprompt() function always leaves the return code of the clearprompt command in $? just as system() would. If the prompt was interrupted via a signal, the function returns the undefined value.

DIRECTORY PROMPTING

The clearprompt command has no way to prompt for a directory, so this module provides a separate clearprompt_dir() function which implements it via "clearprompt list" and opendir/readdir/closedir. Usage is

use ClearCase::ClearPrompt qw(clearprompt_dir);
$dir = clearprompt_dir($starting_dir, $prompt_string);

This is a little awkward to use since it doesn't use a standard directory-chooser interface but it works. There's no way to create a directory within this interface, though.

NOTE

An apparent undocumented "feature" of clearprompt(1) is that it catches SIGINT (Ctrl-C) and provides a status of 4 rather than returning the signal number in $? according to normal (UNIX) signal semantics. We fix that up here so it looks like a normal signal 2. Thus, if clearprompt() returns undef the signal number is reliably in $? as it's documented to be.

PORTING

This package is known to work fine on Solaris 2.5.1/perl5.004_04, Solaris 7/perl5.6, and Windows NT 4.0SP3/5.005_02. As these platforms are quite different, this should take care of any significant portability issues but please send reports of tweaks needed for other platforms to the address below.

AUTHOR

David Boyce <dsb@world.std.com>

Copyright (c) 1999,2000 David Boyce. All rights reserved. This Perl program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

clearprompt(1), perl(1)