path: root/bin/cil

#!/usr/bin/perl
## ----------------------------------------------------------------------------
# cil is a Command line Issue List
# Copyright (C) 2008 Andrew Chilton
#
# 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.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
## ----------------------------------------------------------------------------

use strict;
use warnings;

use Getopt::Mixed "nextOption";
use File::Touch;
use File::Glob ':glob';
use File::Basename;
use File::Slurp qw(read_file write_file);
use Email::Simple;
use Email::Date qw(find_date);

use CIL;
use CIL::Issue;
use CIL::Comment;
use CIL::Attachment;
use CIL::Utils;

## ----------------------------------------------------------------------------
# constants

my @IN_OPTS = (
    # strings
    'p=s',          # p = path
    'path>p',       # for 'add'
    'f=s',          # f = filename
    'filename>f',   # for 'extract'
    's=s',          # s = status
    'status>s',     # for 'summary', 'list'
    'l=s',          # l = label
    'label>l',      # for 'summary, 'list'
    'c=s',          # c = created-by
    'created-by>c', # for 'summary', 'list'
    'a=s',          # a = assigned_to
    'assigned-to>a',# for 'summary', 'list'
    'r=s',          # r = revision
    'revision>s',   # for all query commands

    # booleans
    'bare',         # for 'init'
    'is-open',      # for 'summary', 'list'
    'is-closed',    # for 'summary', 'list'
    'is-mine',      # for 'summary', 'list'
    'mine',         # for 'add'
    'add',          # for 'add', 'comment'
    'commit',       # for 'add', 'comment'
    'batch',        # for 'am'
    'remove',       # for 'label'
    'help',
    'version',
);

my %BOOLEAN_ARGS = (
    'help'      => 1,
    'version'   => 1,
    'bare'      => 1,
    'is-open'   => 1,
    'is-closed' => 1,
    'is-mine'   => 1,
    'mine'      => 1,
    'add'       => 1,
    'commit'    => 1,
    'batch'     => 1,
    'remove'    => 1,
);

## ----------------------------------------------------------------------------
# main program

{
    my $args = get_options(\@IN_OPTS, \%BOOLEAN_ARGS);

    # do the version and help
    if ( exists $args->{version} ) {
        print "cil version " . $CIL::VERSION . "\n";
        exit;
    }

    if ( exists $args->{help} ) {
        usage();
        exit;
    }

    # make sure that the command given is valid
    Getopt::Mixed::abortMsg('specify a command')
       if @ARGV == 0;

    my $command_name = shift @ARGV;
    my( $command ) =  grep { $command_name eq $_->name } CIL->commands
        or Getopt::Mixed::abortMsg("'$command_name' is not a valid cil command.");

    # make a new $cil object
    my $cil = CIL->new();

    # for all commands (except init), we need to know we can see the proper paths
    # (ie. issues/)
    CIL::Utils->check_paths( $cil )
        unless $command_name eq 'init';

    $cil->read_config_user();
    $cil->read_config_file();

    # add any hooks we want
    # none yet

    $command->run($cil, $args, @ARGV);
}

## ----------------------------------------------------------------------------
# hooks

# none yet

## ----------------------------------------------------------------------------
# helper functions for this command line tool

sub get_options {
    my ($in_opts, $booleans) = @_;

    my $args = {};
    Getopt::Mixed::init( @$in_opts );
    while( my($opt, $val) = nextOption() ) {
        # if boolean, keep a count of how many there is only
        if ( exists $booleans->{$opt} ) {
            $args->{$opt}++;
            next;
        }
        # normal 'string' value
        if ( defined $args->{$opt} ) {
            unless ( ref $args->{$opt} eq 'ARRAY' ) {
                $args->{$opt} = [ $args->{$opt} ];
            }
            push @{$args->{$opt}}, $val;
        }
        else {
            $args->{$opt} = $val;
        }
    }
    Getopt::Mixed::cleanup();
    return $args;
}

## ----------------------------------------------------------------------------
# program info

sub usage {
   print <<"END_USAGE";
Usage: $0 COMMAND [options]

Commands:
   init    [--path=PATH]
   add
   summary [FILTERS...]
   list    [FILTERS...]
   show    ISSUE
   status  NEW_STATUS [ISSUES...]
   label   NEW_LABEL [ISSUES...]
   steal   ISSUE
   edit    ISSUE
   comment ISSUE
   attach  ISSUE FILENAME
   extract ATTACHMENT [--filename=FILENAME]
   am      EMAIL.TXT [--batch]
   track   ISSUE
   fsck

Filters:
   --status=?
   --is-open
   --is-closed
   --label=?
   --assigned-to=?
   --is-mine

See <http://www.chilts.org/project/cil/> for further information.
Report bugs to <andychilton\@gmail.com>.
END_USAGE
}

## ----------------------------------------------------------------------------

=head1 NAME

cil - the command-line issue list

=head1 SYNOPSIS

    $ cil init
    $ cil summary
    $ cil list
    $ cil list --status=New
    $ cil list --label=Release-v0.1
    $ cil list --is-open

    $ cil add
    ... added issue 'cafebabe' ...
    $ cil show cafebabe
    $ cil edit cafebabe
    $ cil status cafebabe InProgress

    $ cil comment cafebabe
    ... added comment 'deadbeef' ...

    $ cil attach cafebabe filename.txt
    ... added attachment 'decaf7ea' ...

    $ cil extract decaf7ea
    $ cil extract decaf7ea --filename=other_filename.txt

    $ cil am email.txt

    $ cil track
    $ cil fsck

=head1 DESCRIPTION

Cil is a small but useful command-line issue list. It saves issues, comments
and attachments as local files which you can check in to your repository.

=over

=item init [--path=PATH] [--bare]

Creates a local '.cil' file and an 'issues' directory. If PATH is specified,
the config file and directory will be created in the destination directory.

Usually, cil will write a small C<.cil> file such that you can use various
filter commands immediately and can also serve as an example config file. Using
C<--bare> just touches the C<.cil> config file ready for your own manipulation.

=item summary [filters]

Displays a one line summary for each issue. You may filter on both the Status
and Label fields.

=item list [filters]

Shows each issue with more information. You may filter on both the Status and
Label fields.

=item add [--mine] [summary]

Adds an issues after you have edited the input.  Text passed
after 'add' will be used as the bug summary line.

If you use the --mine flag, the AssignedTo field is automatically set to you
(saves having to copy and paste the CreatedBy field).

=item show ISSUE

Shows the issue name with more detail.

=item status ISSUE NEW_STATUS

Shortcut so that you can set a new status on an issue without having to edit
it.

=item depends-on ISSUE1 ISSUE2

Shortcut so that cil will add a 'DependsOn' from issue 1 to issue
2. Conversley, issue 2 will also then contain a 'Precedes' pointer to issue 1.

=item precedes ISSUE1 ISSUE2

This is the exact opposite of C<depends-on> and is here for convenience and
completeness. ie. issue 1 has to be completed before issue 2.

=item status ISSUE NEW_STATUS

Shortcut so that you can set a new status on an issue without having to edit
it.

=item steal ISSUE

Shortcut to assign this issue to yourself. It reads your C<~/.cilrc> file for
your UserName and UserEmail and uses this to populate the C<AssignedTo> field
in the issue.

=item edit ISSUE

Edits the issue. If it changes, set the updates time to now.

=item comment ISSUE

Adds a comment to an issues after you have edited the input.

=item attach ISSUE FILENAME

Adds that particular filename to an existing issue.

=item extract ATTACHMENT [--filename=FILENAME]

Extracts the file from the attachment number. If filename if given uses that,
otherwise it will use the original one saved along with the attachment.

=item am

Applies an email message to the issue list. It tries to figure out the type of
email it is, whether it is a new issue or a comment on an already existing
issue. For example, if it can find valid issue names in the subject or body of
the message, it adds it as a comment to that issue. If it can't find any valid
issue names, it presumes it's a new issue and adds that.

Note: this command will deal with Mailbox format files later on.

=item track ISSUE

This command outputs one or more command which you should run so that your VCS
knows about your issue. It makes sure all the comments and attachments are done
too.

=item fsck

Tries to help you organise your issues if any aren't valid or have broken
relationships.

=back

=head1 FILTERS

Filters can be used on both the C<summary> and C<list> commands. Most can be
combined. See each individual filter for details.

=over

=item --status=STATUS

You can choose any of the Statuses which might appear in your issues. This
status does not have to be defined in your C<.cil> file, even if you have
C<StatusStrict> turned on.

=item --label=LABEL

You can choose any of the Labels which might appear in your issues. This
label does not have to be defined in your C<.cil> file, even if you have
C<LabelStrict> turned on.

=item --is-open, --is-closed

These check both C<StatusOpenList> and C<StatusClosedList> from your C<.cil>
file. If both are specified, you're likely to get no issues unless you
explicitly defined a status as being in both lists (for whatever reason you
have).

=item --assigned-to=EMAIL_ADDRESS, --is-mine

These items are mutually exclusive. The C<--assigned-to> just checks the email
address in the AssignedTo field. It does not match anything else in that field,
including any preceding name or any angle brackets.

The C<--is-mine> filter is a shortcut to asking if AssignedTo is you. Cil knows
your email address if you define it in your user's C<~/.cilrc> file as
C<UserEmail>.

=back

=head1 .cil

The C<.cil> file is used to configure bits and pieces within cil for this
particular issue list. The following options are available and where stated,
may be declared multiple times:

The C<.cil> file is fairly simple and an example can be seen here:

    UseGit: 1
    StatusStrict: 1
    StatusOpenList: New
    StatusOpenList: InProgress
    StatusClosedList: Finished
    LabelStrict: 1
    LabelAllowedList: Type-Enhancement
    LabelAllowedList: Type-Defect
    LabelAllowedList: Priority-High
    LabelAllowedList: Priority-Medium
    LabelAllowedList: Priority-Low

=over

=item UseGit

Default: 0, Type: Boolean (0/1)

Determines whether to use Git or not. Some features require Git though Cil is
perfectly usable without.

=item StatusStrict

Default: 0, Type: Boolean (0/1)

If this is set to a true value then cil checks that the status you enter into
an issue (after adding or editing) is also in the allowed list (see
StatusAllowedList).

=item StatusOpenList

Default: empty, Type: List

This list is checked against when filtering with --is-open.

=item StatusClosedList

Default: empty, Type: List

This list is checked against when filtering with --is-closed.

=item StatusAllowedList

This list is automatically generated from the StatusOpenList and the
StatusClosedList. It does not have to appear in the config file.

=item LabelStrict

Default: 0, Type: Boolean (0/1)

This determines that labels you enter are checked against LabelAllowedList. Set
to 1 if you require this feature.

=item LabelAllowedList

Default: empty, Type: List

This determines which labels are allowed if you have turned on LabelStrict.

=back

=head1 ~/.cilrc

The C<~/.cilrc> file is read to configure the user's preferences for all cil
lists they're using. It is of the same format as the C<.cil> file and contains
the following options:

    UserName: Andrew Chilton
    UserEmail: andychilton@gmail.com

=over

=item UserName

Default: 'Name', Type: String

This is used as a default in the C<CreatedBy> and C<AssignedTo> fields in any
issues/comments/attachments you add.

=item UserEmail

Default: 'Email', Type: String

This is used as a default in the C<CreatedBy> and C<AssignedTo> fields in any
issues/comments/attachments you add.

=back

=head1 BUGS

Probably. Let me know :-)

=head1 TODO

To get a ToDo list for cil, clone the repo, find the issues/ dir and type:

    $ cil --is-open

This gives the current outstanding issues in cil.

=head1 AUTHOR

Andrew Chilton <andychilton@gmail.com>

=head1 COPYRIGHT

Copyright (C) 2008 by Andrew Chilton

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/> or write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.

=cut
## ----------------------------------------------------------------------------