#!/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 .
## ----------------------------------------------------------------------------
use strict;
use warnings;
use Getopt::Mixed "nextOption";
use Digest::MD5 qw(md5_hex);
use File::Touch;
use File::Glob ':glob';
use File::Basename;
use File::Slurp qw(read_file write_file);
use CIL;
use CIL::Issue;
use CIL::Comment;
use CIL::Attachment;
## ----------------------------------------------------------------------------
# constants
my $y = 'y';
use constant VERSION => '0.3.0';
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'
# booleans
'is-open', # for 'summary', 'list'
'is-closed', # for 'summary', 'list'
'help',
'version',
);
my %BOOLEAN_ARGS = (
'help' => 1,
'version' => 1,
'is-open' => 1,
'is-closed' => 1,
);
my $gan = $ENV{GIT_AUTHOR_NAME} || 'Your Name';
my $gae = $ENV{GIT_AUTHOR_EMAIL} || 'you@example.org';
## ----------------------------------------------------------------------------
# main program
{
my $args = get_options(\@IN_OPTS, \%BOOLEAN_ARGS);
# do the version and help
if ( exists $args->{version} ) {
print "cil version ".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 = shift @ARGV;
no strict 'refs';
if ( not defined &{"cmd_$command"} ) {
Getopt::Mixed::abortMsg("'$command' is not a valid cil command.");
}
my $cil = CIL->new();
$cil->read_config_file( '.cil' );
&{"cmd_$command"}($cil, $args, @ARGV);
}
## ----------------------------------------------------------------------------
# commands
sub cmd_init {
my ($cil, $args) = @_;
my $path = $args->{p} || '.'; # default path is right here
# error if $path doesn't exist
unless ( -d $path ) {
fatal("path '$path' doesn't exist");
}
# error if issues/ already exists
my $issues_dir = "$path/issues";
if ( -d $issues_dir ) {
fatal("issues directory '$issues_dir' already exists, not initialising issues");
}
# error if .cil already exists
my $config = "$path/.cil";
if ( -f $config ) {
fatal("config file '$config' already exists, not initialising issues");
}
# try to create the issues/ dir
unless ( mkdir $issues_dir ) {
fatal("Couldn't create '$issues_dir' directory: $!");
}
# create a .cil file here also
unless ( touch $config ) {
rmdir $issues_dir;
fatal("couldn't create a '$config' file");
}
# add a README.txt so people know what this is about
unless ( -f "$issues_dir/README.txt" ) {
write_file("$issues_dir/README.txt", <<'README');
This directory is used by CIL to track issues and feature requests.
The home page for CIL is at http://kapiti.geek.nz/software/cil.html
README
}
# $path/issues/ and $path/.cil create correctly
msg("initialised empty issue list inside '$path/'");
}
sub cmd_list {
my ($cil, $args) = @_;
check_paths($cil);
# find all the issues
my $issues = $cil->get_issues();
$issues = filter_issues( $cil, $issues, $args );
if ( @$issues ) {
foreach my $issue ( sort { $a->Inserted cmp $b->Inserted } @$issues ) {
separator();
display_issue_headers($cil, $issue);
}
separator();
}
else {
msg('no issues found');
}
}
sub cmd_summary {
my ($cil, $args) = @_;
check_paths($cil);
# find all the issues
my $issues = $cil->get_issues();
$issues = filter_issues( $cil, $issues, $args );
if ( @$issues ) {
separator();
foreach my $issue ( @$issues ) {
display_issue_summary($cil, $issue);
}
separator();
}
else {
msg('no issues found');
}
}
sub cmd_show {
my ($cil, undef, $issue_name) = @_;
# firstly, read the issue in
my $issue = CIL::Issue->new_from_name($cil, $issue_name);
unless ( defined $issue ) {
fatal("Couldn't load issue '$issue_name'");
}
display_issue_full($cil, $issue);
}
sub cmd_status {
my ($cil, undef, $issue_name, $status) = @_;
unless ( defined $status ) {
fatal("provide a status to set this issue to");
}
# firstly, read the issue in
my $issue = CIL::Issue->new_from_name($cil, $issue_name);
unless ( defined $issue ) {
fatal("Couldn't load issue '$issue_name'");
}
# set the status for this issue
$issue->Status( $status );
$issue->save($cil);
display_issue($cil, $issue);
}
sub cmd_add {
my ($cil, undef, $issue_name) = @_;
CIL::Utils->ensure_interactive();
my $issue = CIL::Issue->new('tmpname');
$issue->Status('New');
$issue->CreatedBy("$gan <$gae>");
$issue->AssignedTo("$gan <$gae>");
$issue->Description("Description ...");
my $edit = $y;
# keep going until we get a valid issue or we want to quit
while ( $edit eq $y ) {
# read in the new issue text
my $fh = CIL::Utils->solicit( $issue->as_output );
$issue = CIL::Issue->new_from_fh( 'tmp', $fh );
# check if the issue is valid
if ( $issue->is_valid($cil) ) {
$edit = 'n';
}
else {
msg($_) foreach @{ $issue->errors };
print 'Would you like to re-edit (y/n): ';
$edit = ;
chomp $edit;
print "\n";
}
}
# if the issue is still invalid, they quit without correcting it
return unless $issue->is_valid( $cil );
# we've got the issue, so let's name it
my $unique_str = $issue->Inserted . $issue->Summary . $issue->Description;
$issue->set_name( substr(md5_hex($unique_str), 0, 8) );
$issue->save($cil);
display_issue($cil, $issue);
}
sub cmd_edit {
my ($cil, undef, $issue_name) = @_;
my $issue = CIL::Issue->new_from_name($cil, $issue_name);
unless ( defined $issue ) {
fatal("Couldn't load issue '$issue_name'");
}
CIL::Utils->ensure_interactive();
my $edit = $y;
# keep going until we get a valid issue or we want to quit
while ( $edit eq $y ) {
# read in the new issue text
my $fh = CIL::Utils->solicit( $issue->as_output );
$issue = CIL::Issue->new_from_fh( $issue->name, $fh );
# check if the issue is valid
if ( $issue->is_valid($cil) ) {
$edit = 'n';
}
else {
msg($_) foreach @{ $issue->errors };
print 'Would you like to re-edit (y/n): ';
$edit = ;
chomp $edit;
print "\n";
}
}
# if the issue is still invalid, they quit without correcting it
return unless $issue->is_valid( $cil );
# save it
$issue->save($cil);
display_issue($cil, $issue);
}
sub cmd_comment {
my ($cil, undef, $issue_name) = @_;
my $issue = CIL::Issue->new_from_name($cil, $issue_name);
unless ( defined $issue ) {
fatal("couldn't load issue '$issue_name'");
}
CIL::Utils->ensure_interactive();
# create the new comment
my $comment = CIL::Comment->new('tmpname');
$comment->Issue( $issue->name );
$comment->CreatedBy("$gan <$gae>");
$comment->Description("Description ...");
my $edit = $y;
# keep going until we get a valid issue or we want to quit
while ( $edit eq $y ) {
# read in the new comment text
my $fh = CIL::Utils->solicit( $comment->as_output );
$comment = CIL::Comment->new_from_fh( 'tmp', $fh );
# check if the comment is valid
if ( $comment->is_valid($cil) ) {
$edit = 'n';
}
else {
msg($_) foreach @{ $issue->errors };
print 'Would you like to re-edit (y/n): ';
$edit = ;
chomp $edit;
print "\n";
}
}
# if the comment is still invalid, they quit without correcting it
return unless $comment->is_valid( $cil );
# we've got the comment, so let's name it
my $unique_str = $comment->Inserted . $issue->Description;
$comment->set_name( substr(md5_hex($unique_str), 0, 8) );
# finally, save it
$comment->save($cil);
# add the comment to the issue, update it's timestamp and save it out
$issue->add_comment( $comment );
$issue->save($cil);
display_issue_full($cil, $issue);
}
sub cmd_attach {
my ($cil, undef, $issue_name, $filename) = @_;
my $issue = CIL::Issue->new_from_name($cil, $issue_name);
unless ( defined $issue ) {
fatal("couldn't load issue '$issue_name'");
}
# check to see if the file exists
unless ( -r $filename ) {
fatal("couldn't read file '$filename'");
}
my $basename = basename( $filename );
my $add_attachment_text = <<"EOF";
Filename : $basename
CreatedBy : $gan <$gae>
File goes here ... this will be overwritten.
EOF
# read in the new issue text
CIL::Utils->ensure_interactive();
my $fh = CIL::Utils->solicit( $add_attachment_text );
my $attachment = CIL::Attachment->new_from_fh( 'tmp', $fh );
unless ( defined $attachment ) {
fatal("could not create new attachment");
}
# now add the file itself
my $contents = read_file( $filename );
$attachment->set_file_contents( $contents );
# set the size
my ($size) = (stat($filename))[7];
$attachment->Size( $size );
# we've got the attachment, so let's name it
my $unique_str = $attachment->Inserted . $attachment->File;
$attachment->set_name( substr(md5_hex($unique_str), 0, 8) );
# finally, tell it who it's parent is and then save
$attachment->Issue( $issue->name );
$attachment->save($cil);
# add the comment to the issue, update it's timestamp and save it out
$issue->add_attachment( $attachment );
$issue->save($cil);
display_issue_full($cil, $issue);
}
sub cmd_extract {
my ($cil, $args, $attachment_name) = @_;
my $attachment = CIL::Attachment->new_from_name($cil, $attachment_name);
unless ( defined $attachment ) {
fatal("Couldn't load attachment '$attachment_name'");
}
my $filename = $args->{f} || $attachment->Filename();
write_file( $filename, $attachment->as_binary );
}
sub cmd_fsck {
my ($cil, $args) = @_;
# this looks at all the issues it can find and checks for:
# * validity
# * all the comments are there
# * all the attachments are there
# then it checks each individual comment/attachment for:
# * ToDo: validity
# * it's parent exists
check_paths($cil);
# find all the issues, comments and attachments
my $issues = $cil->get_issues();
my $issue = {};
foreach my $i ( @$issues ) {
$issue->{$i->name} = $i;
}
my $comments = $cil->get_comments();
my $comment = {};
foreach my $c ( @$comments ) {
$comment->{$c->name} = $c;
}
my $attachments = $cil->get_attachments();
my $attachment = {};
foreach my $a ( @$attachments ) {
$attachment->{$a->name} = $a;
}
my $errors = {};
if ( @$issues ) {
foreach my $i ( sort { $a->Inserted cmp $b->Inserted } @$issues ) {
my $name = $i->name;
unless ( $i->is_valid($cil) ) {
foreach ( @{ $i->errors } ) {
push @{$errors->{$name}}, $_;
}
}
# check that all it's comments are there and that they have this parent
my $comments = $i->Comments;
foreach my $c ( @$comments ) {
# see if this comment exists at all
if ( exists $comment->{$c} ) {
# check the parent is this issue
push @{$errors->{$name}}, "comment '$c' is listed under issue '" . $i->name . "' but does not reciprocate"
unless $comment->{$c}->Issue eq $i->name;
}
else {
push @{$errors->{$name}}, "comment '$c' listed in issue '" . $i->name . "' does not exist";
}
}
# check that all it's attachments are there and that they have this parent
my $attachments = $i->Attachments;
foreach my $a ( @$attachments ) {
# see if this attachment exists at all
if ( exists $attachment->{$a} ) {
# check the parent is this issue
push @{$errors->{$name}}, "attachment '$a' is listed under issue '" . $i->name . "' but does not reciprocate"
unless $attachment->{$a}->Issue eq $i->name;
}
else {
push @{$errors->{$name}}, "attachment '$a' listed in issue '" . $i->name . "' does not exist";
}
}
}
}
print_fsck_errors('Issue', $errors);
# comments
$errors = {};
# loop through all the comments
if ( @$comments ) {
# check that their parent issues exist
foreach my $c ( sort { $a->Inserted cmp $b->Inserted } @$comments ) {
# check that the parent of each comment exists
unless ( exists $issue->{$c->Issue} ) {
push @{$errors->{$c->name}}, "comment '" . $c->name . "' refers to issue '" . $c->Issue . "' but issue does not exist";
}
}
}
print_fsck_errors('Comment', $errors);
# attachments
$errors = {};
# loop through all the attachments
if ( @$attachments ) {
# check that their parent issues exist
foreach my $a ( sort { $a->Inserted cmp $b->Inserted } @$attachments ) {
# check that the parent of each attachment exists
unless ( exists $issue->{$a->Issue} ) {
push @{$errors->{$a->name}}, "attachment '" . $a->name . "' refers to issue '" . $a->Issue . "' but issue does not exist";
}
}
}
print_fsck_errors('Attachment', $errors);
# nothing more to do
separator();
}
sub print_fsck_errors {
my ($entity, $errors) = @_;
separator();
foreach my $issue_name ( keys %$errors ) {
title( "$entity $issue_name ");
foreach my $error ( @{$errors->{$issue_name}} ) {
msg("* $error");
}
}
}
## ----------------------------------------------------------------------------
sub check_paths {
my ($cil) = @_;
# make sure an issue directory is available
unless ( -d $cil->IssueDir ) {
fatal("couldn't find '" . $cil->IssueDir . "' directory");
}
}
sub filter_issues {
my ($cil, $issues, $args) = @_;
# don't filter if we haven't been given anything
return $issues unless %$args;
# take a copy of the whole lot first (so we don't destroy the input list)
my @new_issues = @$issues;
# firstly, get out the Statuses we want
if ( defined $args->{s} ) {
@new_issues = grep { $_->Status eq $args->{s} } @new_issues;
}
# then see if we want a particular label (could be a bit nicer)
if ( defined $args->{l} ) {
my @tmp;
foreach my $issue ( @new_issues ) {
push @tmp, $issue
if grep { $_ eq $args->{l} } @{$issue->Labels};
}
@new_issues = @tmp;
}
# filter out dependent on open/closed
if ( defined $args->{'is-open'} ) {
# just get the open issues
@new_issues = grep { $_->is_open($cil) } @new_issues;
}
if ( defined $args->{'is-closed'} ) {
# just get the closed issues
@new_issues = grep { $_->is_closed($cil) } @new_issues;
}
# filter out 'created by'
if ( defined $args->{c} ) {
@new_issues = grep { $args->{c} eq $_->created_by_email } @new_issues;
}
# filter out 'assigned to'
if ( defined $args->{a} ) {
@new_issues = grep { $args->{a} eq $_->assigned_to_email } @new_issues;
}
return \@new_issues;
}
## ----------------------------------------------------------------------------
# input/output
sub display_issue_summary {
my ($cil, $issue) = @_;
my $msg = $issue->name();
$msg .= "\t";
$msg .= $issue->Status();
$msg .= "\t";
$msg .= $issue->Summary();
msg($msg);
}
sub display_issue_headers {
my ($cil, $issue) = @_;
title( 'Issue ' . $issue->name() );
field( 'Summary', $issue->Summary() );
field( 'CreatedBy', $issue->CreatedBy() );
field( 'AssignedTo', $issue->AssignedTo() );
field( 'Inserted', $issue->Inserted() );
field( 'Status', $issue->Status() );
field( 'Labels', join(' ', @{$issue->Label()}) );
}
sub display_issue {
my ($cil, $issue) = @_;
separator();
title( 'Issue ' . $issue->name() );
field( 'Summary', $issue->Summary() );
field( 'Status', $issue->Status() );
field( 'CreatedBy', $issue->CreatedBy() );
field( 'AssignedTo', $issue->AssignedTo() );
field( 'Label', $_ )
foreach sort @{$issue->Label()};
field( 'Comment', $_ )
foreach sort @{$issue->Comment()};
field( 'Attachment', $_ )
foreach sort @{$issue->Attachment()};
field( 'Inserted', $issue->Inserted() );
field( 'Updated', $issue->Inserted() );
text('Description', $issue->Description());
separator();
}
sub display_issue_full {
my ($cil, $issue) = @_;
separator();
title( 'Issue ' . $issue->name() );
field( 'Summary', $issue->Summary() );
field( 'Status', $issue->Status() );
field( 'CreatedBy', $issue->CreatedBy() );
field( 'AssignedTo', $issue->AssignedTo() );
field( 'Label', $_ )
foreach sort @{$issue->Label()};
field( 'Inserted', $issue->Inserted() );
field( 'Updated', $issue->Inserted() );
text('Description', $issue->Description());
my $comments = $cil->get_comments_for( $issue );
foreach my $comment ( @$comments ) {
title( 'Comment ' . $comment->name() );
field( 'CreatedBy', $comment->CreatedBy() );
field( 'Inserted', $comment->Inserted() );
field( 'Updated', $comment->Inserted() );
text('Description', $comment->Description());
}
my $attachments = $cil->get_attachments_for( $issue );
foreach my $attachment ( @$attachments ) {
title( 'Attachment ' . $attachment->name() );
field( 'Filename', $attachment->Filename() );
field( 'CreatedBy', $attachment->CreatedBy() );
field( 'Inserted', $attachment->Inserted() );
field( 'Updated', $attachment->Inserted() );
msg();
}
separator();
}
## ----------------------------------------------------------------------------
# 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;
}
sub msg {
print ( defined $_[0] ? $_[0] : '' );
print "\n";
}
sub separator {
msg('=' x 79);
}
sub title {
my ($title) = @_;
my $msg = "--- $title ";
$msg .= '-' x (74 - length($title));
msg($msg);
}
sub field {
my ($field, $value) = @_;
my $msg = "$field";
$msg .= " " x (12 - length($field));
msg("$msg: " . (defined $value ? $value : '') );
}
sub text {
my ($field, $value) = @_;
msg "";
msg($value);
msg "";
}
sub err {
print STDERR ( defined $_[0] ? $_[0] : '' );
print STDERR "\n";
}
sub fatal {
my ($msg) = @_;
chomp $msg;
print STDERR $msg, "\n";
exit 2;
}
## ----------------------------------------------------------------------------
# program info
sub usage {
print <<"END_USAGE";
Usage: $0 COMMAND [options]
Commands:
init [--path=PATH]
add
summary [--status=STATUS] [--label=LABEL] [--is-open] [--is-closed]
list [--status=STATUS] [--label=LABEL] [--is-open] [--is-closed]
show ISSUE
status ISSUE NEW_STATUS
edit ISSUE
comment ISSUE
attach ISSUE FILENAME
extract ATTACHMENT [--filename=FILENAME]
fsck
See for further information.
Report bugs to .
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 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]
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.
=item summary [--status=STATUS] [--label=LABEL] [--is-open] [--is-closed]
Displays a one line summary for each issue. You may filter on both the Status
and Label fields.
=item list [--status=STATUS] [--label=LABEL] [--is-open] [--is-closed]
Shows each issue with more information. You may filter on both the Status and
Label fields.
=item add
Adds an issues after you have edited the input.
=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 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.
=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:
StatusStrict: 1
StatusAllowedList: New
StatusAllowedList: InProgress
StatusAllowedList: Finished
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 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 StatusAllowedList
Default: empty, Type: List
This list is checked against when adding or editing issues but only if you have
StatusStrict on.
=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 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 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
=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 or write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
=cut
## ----------------------------------------------------------------------------