NAME

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

VERSION

0.1.0_25 (2014-06-14)

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

uuid2id( $try ) -> Int

Returns $try unless a $ctx->{uuid} option has been set. Returns Bif::DB->uuid2id($try) if the lookup succeeds or else raises an error.

get_project( $path, [ $hub ]) -> HashRef

Calls get_projects from Bif::DB and raises an error if more than one project is found. Otherwise it passes back the the single hashref returned.

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.

lprint( $msg ) -> Int

If a pager is not active this method prints $msg to STDOUT and returns the cursor to the beginning of the line. The next call over-writes the previously printed text before printing the new $msg. In this way a continually updating status can be displayed.

get_topic( $TOKEN ) -> HashRef

Looks up the topic identified by $TOKEN and returns undef or a hash reference containg the following keys:

• id - the topic ID

• first_update_id - the update_id that created the topic

• kind - the type of the topic

• uuid - the universally unique identifier of the topic

If the found topic is an issue then the following keys will also contain valid values:

• project_issue_id - the project-specific topic ID

• project_id - the project ID matching the project_issue_id

update_repo($hashref)

Create an update of the local repo from a hashref containing a ruid (an update_id), user name, a user email, and a message. $hashref can optionally contain an update_id which will be converted into a uuid, used for uniqueness in the event that multiple calls to update_repo with the same values occur in the same second.

SEE ALSO

Bif::DB, Bif::DBW

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.