NAME

Text::Prefix - Prepend strings with timestamps and potentially other contextually-relevant information.

SYNOPSIS

    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"'

DESCRIPTION

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.

METHODS

There are only two methods provided by this package, new and prefix.

new (%options)

(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.

(default: 0)

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).

(default: 0)

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").

(default: 0)

no_human_date => 0, 1

Set to 1 to omit human-readable timestamps from prefixed text (corresponding to output field "lt").

(default: 0)

no_epoch => 0, 1

Set to 1 to omit epoch timestamps from prefixed text (corresponding to output field "tm").

(default: 0)

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

pl - Value returned by evaluating perl provided via perl or perlf parameters passed to new

d - Original input string, potentially modified via perl or perlf side-effects. Key may be renamed via label parameter.

(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".

(default: none)

perlf => filename

Just like perl except the perl code is read from the given file.

(default: none)

pretee => filename

When provided, input is appended to the file of the given name before perl evaluation or any other reformatting.

(default: none)

short => 0, 1

Set to 1 to shorten the human-readable timestamp field somewhat.

(default: 0)

shorter => 0, 1

Set to 1 to shorten the human-readable timestamp to only the hour and minute (HH:MM).

(default: 0)

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.

(default: none)

tee => filename

Just like pretee, but the output string will be appended to the named file.

(default: none)

with => string

When provided, the output will include the literal string in its prefix.

(default: none)

prefix (string)

Returns the given string after applying the formatting and prefixing rules passed to new.

TODO

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:

new should probably take a coderef option, to supplement perl and perlf.

new should support a format option which causes prefix to return a hashref or arrayref instead of a string.

HISTORY

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.

AUTHORS

TTKCIAR <ttk@ciar.org>

COPYRIGHT AND LICENSE

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.