NAME
CAF::ObjectText - Base class for handling text
SYNOPSIS
Define subclass via package SubClass; use parent qw(CAF::ObjectText);
sub _get_text
{
my ($self) = @_;
return "actual text";
}
And use it via my $sc = SubClass->new(log => $self); print "$sc"; # stringification
$sc = SubClass->new(log => $self);
# return CAF::FileWriter instance (text already added)
my $fh = $sc->filewriter('/some/path');
if (!defined($fh)) {
$self->error("Failed to retrieve filewriter: $sc->{fail}");
return;
}
$fh->close();
DESCRIPTION
This class simplifies text handling via stringification and produces a FileWriter instance.
Methods
-
_initialize_textopts
Handle some common options in the subclass
_initialize
method.-
log
A Reporter object to log to.
-
eol
If
eol
is true, the produced text will be verified that it ends with an end-of-line, and if missing, a newline character will be added. By default,eol
is true.eol
set to false will not strip trailing newlines (usechomp
or something similar for that). -
usecache
If
usecache
is false, the text is always re-produced. Default is to cache the produced text (usecache
is true).
-
-
_get_text_test
Run additional tests before the actual text is produced via
get_text
. Returns undef in case of failure, SUCCESS otherwise.The method is called in
get_text
before the caching is checked.Default implementation does not test anything, always returns SUCCESS. This method should be redefined in the subclass.
-
_get_text
Produce the actual text in
get_text
(or call another method that does so).Returns 2 element tuple with first element the resulting text (or undef in case of failure). The second element is an error message prefix (ideally, real error message is set via the
fail
attribute).This method needs to be defined in the subclass.
-
get_text
get_text
produces and returns the text.In case of an error,
get_text
returnsundef
(no error is logged). This is the main difference from the auto-stringification that returns an empty string in case of a rendering error.By default, the result is cached. To force re-producing the text, clear the current cache by passing
1
as first argument (or disable caching completely with the optionusecache
set to false during the initialisation). -
filewriter
Create and return an open FileWriter instance with first argument as the filename. If the
get_text
method fails (i.e. returns undef),undef
is returned.The text is added to the filehandle. It's up to the consumer to cancel and/or close the instance.
All FileWriter initialisation options are supported and passed on. (If no
log
option is provided, the one from the current instance is passed).Two new options
header
andfooter
are supported to respectively prepend and append to the text.If
eol
was set during initialisation, the header and footer will also be checked for EOL. (EOL is still added to theget_text
ifeol
is set during initialisation, even if there is a footer defined.)