NAME

App::bif::Context - A context class for App::bif::* commands

VERSION

0.1.0 (yyyy-mm-dd)

SYNOPSIS

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

sub run {
    my $ctx  = App::bif::Context->new(shift);
    my $db   = $ctx->db;
    my $data = $db->xarray(...);

    return $ctx->err( 'SomeFailure', 'something failed' )
      if ($ctx->{command_option});

    $ctx->start_pager;

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

    $ctx->end_pager;

    return $ctx->ok('CommandName');
}

DESCRIPTION

App::bif::Context provides a context/configuration object for bif commands. It is a blessed hashref, and commands are expected to grab configuration keys and call methods on it.

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 App::bif::Context-new> to set up a bif context which sets up logging and merges the user and repository configurations with the command-line options.

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

CONSTRUCTOR

App::bif::Context->new( $ctx ) -> $ctx

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::Context::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.

METHODS

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.

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.

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.

db -> Bif::DB::db

Returns a handle for the SQLite database in the current respository (as found by bif_repo). The handle is only good for read operations - use $ctx-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.

dbw -> Bif::DB::RW::db

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

You should manually import any DBIx::ThinSQL functions you need only after calling $ctx-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-2014 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.