NAME

App::bif::Util - Utility functions for App::bif::* scripts

VERSION

0.1.0 (yyyy-mm-dd)

SYNOPSIS

# In App/bif/command/name.pm
use strict;
use warnings;
use App::bif::Util;

sub run {
    my $opts = bif_init(shift);
    my $db   = bif_db;
    my $data = $db->xarray(...);

    bif_err('SomeFailure', 'something failed')
      if ($some_failure);

    start_pager;

    print render_table(
        ' r  l  l ',
        [ qw/ ID Title Status / ],
        $data,
    );

    stop_pager;

    return bif_ok('CommandName');
}

DESCRIPTION

The above synopsis is the basic template for any bif command. At run time the run function is called by OptArgs::dispatch with the options hashref as the first argument. The first thing the bif command should do it call bif_init to set up logging. Everything after that is a matter of reading or writing to the terminal and/or the database.

The following utility functions are all automatically exported into the calling package. App::bif::Util sets the encoding of STDOUT and STDIN to utf-8 when it is loaded.

bif_err( $err, $message, [ @args ])

Throws an exception that stringifies to $message prefixed with "fatal: ". The exception is an object from the Bif::Error::$err class which is used by test scripts to reliably detect the type of error. If @args exists then $message is assumed to be a format string to be converted with sprintf.

bif_ok( $type, [ $arg ])

Returns a Bif::OK::$type object, either as a reference to $arg or as a reference to the class name. Every App::Bif::* command should return such an object, which can be tested for by tests.

start_pager([ $rows ])

Start a pager (less, more, etc) on STDOUT using IO::Pager, provided that --no-pager has not been used. The pager handle encoding is set to utf-8. If the optional $rows has been given then the pager will only be started if Term::Size reports the height of the terminal as being less than $rows.

end_pager

Stops the pager on STDOUT if it was previously started.

bif_init( $opts ) -> $opts

Initializes the common elements of all bif scripts. Requires the options hashref as provided by OptArgs but also returns it.

• Sets the package variable $App::bif::Util::STDOUT_TERMINAL to true if STDOUT is connected to a terminal.

• Sets the environment variable ANSI_COLORS_DISABLED to 1 if STDOUT is not connected to a terminal, in order to disable Term::ANSIColor functions.

• Starts a pager if --debug is true, unless --no-pager is also set to true or STDOUT is not connected to a terminal.

• Adds unfiltered logging via Log::Any::Adapter::Stdout.

bif_repo -> Path::Tiny

Return the path to the first '.bif' directory found starting from the current working directory and searching upwards. Raises a 'RepoNotFound' error on failure.

bif_user_conf -> HashRef

Returns the user configuration. Will prompt for values and construct the file if it doesn't exist first.

bif_conf -> HashRef

Returns the configuration for the current repository, a merge of the user configuration file and the repository configuration file.

bif_db( [$directory] ) -> Bif::DB::db

Returns a handle for the SQLite database in the current respository (as found by bif_repo) or in the repository given as $directory. The handle is only good for read operations - use bif_dbw when inserting,updating or deleting from the database.

You should manually import any DBIx::ThinSQL functions you need only after calling bif_db, in order to keep startup time short for cases such as when the repository is not found.

bif_dbw( [$directory] ) -> Bif::DB::RW::db

Returns a handle for the SQLite database in the current respository (as found by bif_repo) or in the repository given as $directory. The handle is good for INSERT, UPDATE and DELETE operations.

You should manually import any DBIx::ThinSQL functions you need only after calling bif_dbw, in order to keep startup time short for cases such as when the repository is not found.

render_table( $format, \@header, \@data, [ $indent ] ) -> Str

Uses Text::FormatTable to construct a table of <@data>, aligned and spaced according to $format, preceded by a @header. If $indent is greater than zero then the entire table is indented by that number of spaces.

prompt_edit( %options ) -> Str

If the environment is interactive this function will invoke an editor and return the result. All comment lines (beginning with '#') are removed. TODO: describe %options.

SEE ALSO

Bif::DB, Bif::DB::RW

AUTHOR

Mark Lawrence <nomad@null.net>

COPYRIGHT AND LICENSE

Copyright 2013 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.