Text::Prefix - Prepend strings with timestamps and potentially other contextually-relevant information.
use Text::Prefix; # Simple case: prepend strings with timestamps. # my $px = Text::Prefix->new(); # default just prepends timestamp my $s = $px->prefix("some string"); # # $s is now: "Fri Jun 9 16:45:25 2017 1497051925 some string" # More complex case: ISO timestamp, no epoch timestamp, high-resolution # TAI-10 time, hostname, and length of string, in CSV format # my $px = Text::Prefix->new( format => 'csv', host => 1, iso => 1, no_epoch => 1, perl => 'length($s)', tai => 1 ); my $s = $px->prefix("another string"); # # $s is now: '"2017-06-09 16:50:59.9161","xiombarg","14","another string"'
Text::Prefix contains the logic implementing the prefix(1) utility (included in this package). It takes arbitrary strings as input and produces output with various contextually-relevant information preceding the string. A variety of output formats are also supported, as well as output field reordering.
This is handy, for instance, when tailing a logfile which does not contain timestamps. prefix adds a timestamp prefix to each line it is given.
There are only two methods provided by this package, new and prefix.
new
prefix
(Class method) Returns a new instance of Text::Prefix. The object's default attributes are overridden by any options given.
Currently the following attributes may be set:
format => kvp, tab, csv, space
Format the output as a kvp (tab-delimited "key=value" pairs), tab-delimited, comma-delimited, or space-delimited values.
(default: "space")
hires => 0, 1
Set to 1 to use high-resolution timestamps.
(default: 0)
host => 0, 1
Set to 1 to prefix output with the local hostname.
host_sans => regular expression string
Set to a string to exclude the matching part of the hostname from prefix. Implies setting host.
(default: none)
iso => 0, 1
Set to 1 to use ISO-8601 formatted timestamps (more or less).
label => string
When output format is "kvp", use the provided string as the key value for the field containing the input string.
(default: "d")
no_date => 0, 1
Set to 1 to omit any timestamps from prefixed text (corresponding to output fields "lt" and "tm").
no_human_date => 0, 1
Set to 1 to omit human-readable timestamps from prefixed text (corresponding to output field "lt").
no_epoch => 0, 1
Set to 1 to omit epoch timestamps from prefixed text (corresponding to output field "tm").
order => CSV string
Given a comma-separated list of key names, change the ordering of the named output fields.
Currently supported output fields are:
lt - Human-readable timestamp string (mnemonic, "localtime")
tm - Epoch timestamp
hn - Hostname
st - Literal string provided via passing with parameter to new
with
pl - Value returned by evaluating perl provided via perl or perlf parameters passed to new
perl
perlf
d - Original input string, potentially modified via perl or perlf side-effects. Key may be renamed via label parameter.
label
(default: "lt, tm, hn, st, pl, d")
perl => string containing perl code
The provided string will be eval()'d for every line of input, and its return value included in the output prefix. The input string is available to this code in the variable "$s".
eval()
perlf => filename
Just like perl except the perl code is read from the given file.
pretee => filename
When provided, input is appended to the file of the given name before perl evaluation or any other reformatting.
short => 0, 1
Set to 1 to shorten the human-readable timestamp field somewhat.
shorter => 0, 1
Set to 1 to shorten the human-readable timestamp to only the hour and minute (HH:MM).
tai => 0, 10, 35
When provided, timestamps will reflect TAI-0, TAI-10, or TAI-35 time instead of system time. If option's value is anything other than 0 or 10 or 35, TAI-10 will be assumed. See also: https://metacpan.org/pod/Time::TAI::Simple. TAI time is a high-resolution time, so a fractional second will be included in prefix timestamps.
tee => filename
Just like pretee, but the output string will be appended to the named file.
pretee
with => string
When provided, the output will include the literal string in its prefix.
Returns the given string after applying the formatting and prefixing rules passed to new.
Since this module was implemented specifically to support the functionality of the prefix(1) tool, it lacks some obvious features which a programmer using the module directly might expect:
prefix(1)
new should probably take a coderef option, to supplement perl and perlf.
coderef
new should support a format option which causes prefix to return a hashref or arrayref instead of a string.
prefix(1) started life in 2001 as an extremely simple throwaway script. Like many "throwaway" scripts, this one grew haphazardly with little regard to best practices. The author has used it almost every day since then, and was intensely embarrassed by the state of its source code, but it took him until 2017 to get around to refactoring it into Text::Prefix.
Text::Prefix
TTKCIAR <ttk@ciar.org>
Copyright (C) 2017 Bill "TTK" Moyer. All rights reserved.
This library is free software. You may use it, redistribute it and/or modify it under the same terms as Perl itself.
To install Text::Prefix, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Prefix
CPAN shell
perl -MCPAN -e shell install Text::Prefix
For more information on module installation, please visit the detailed CPAN module installation guide.