Subversion Repositories DevTools

########################################################################
# COPYRIGHT - VIX IP PTY LTD ("VIX"). ALL RIGHTS RESERVED.
#
# Module name   : jats_ignore.pl
# Module type   : JATS Utility
# Compiler(s)   : Perl
# Environment(s): jats
#
# Description   : Utility to:
#                 1) Parse the .jatsignore file
#                    Sanity test it
#                 2) Display those files and folder ignored by it
#                 3) Zero the ignored files
#                    For use by LXR
#                 4) Generate sutable information for the 'cloc' utility used by
#                    jats metrics
#
#                 This is simply a wrapper around a Perl Module
#                 Implement the body in a perl module so that we can use it from 
#                 within jats_metrics
#
# Usage         : See POD at the end of this file
#
#......................................................................#

require 5.008_002;
use strict;
use warnings;

use Pod::Usage;
use Getopt::Long;

use JatsError;
use JatsIgnore;

################################################################################
#   Option variables
#
my $VERSION = "1.0.0";                      # Update this
my $opt_verbose = 0;
my $opt_debug = 0;
my $opt_help = 0;
my $opt_test;
my $opt_file;
my $opt_text;
my $opt_examine;

#
#   Option parsing
#
my $result = GetOptions (
                "help|h:+"          => \$opt_help,
                "manual:3"          => \$opt_help,
                "verbose|v:+"       => \$opt_verbose,
                "debug:+"           => \$opt_debug,
                "examine:s"         => \$opt_examine,      
                "test"              => \$opt_test,      
                "file:s"            => \$opt_file,      
                "text:s"            => \$opt_text,      
                );

#
#   Process help and manual options
#
pod2usage(-verbose => 0, -message => "Version: $VERSION")  if ($opt_help == 1  || ! $result);
pod2usage(-verbose => 1)  if ($opt_help == 2 );
pod2usage(-verbose => 2)  if ($opt_help > 2);

#
#   Configure the error reporting process now that we have the user options
#
ErrorConfig( 'name'    =>'IGNORE_BASE',
             'verbose' => $opt_verbose,
             'debug'   => $opt_debug
              );

#
#   Sanity test the user arguemnts
#
Error ("Too many command line arguments: @ARGV" )
    if ( $#ARGV >= 0 );
#Error ("No file specified") unless defined $opt_file;
#Error ("File not found: $opt_file") unless -f $opt_file;

#
#   Invoke required operations
#
if ($opt_test)
{
    JatsIgnore::Test();
#    JatsIgnore::ReadFilters($opt_file);
    JatsIgnore::TestFile($opt_text) if defined $opt_text && -f $opt_text;
    Message("All done");
}

#
#   Examine a path and report results
#
if ($opt_examine)
{
    Error ("No file specified") unless defined $opt_file;
    Error ("Path is not a directory") unless -d $opt_examine;

    JatsIgnore::ReadFilters($opt_file);
    JatsIgnore::AddFilter('*.zip', 'deskpkg', '*.pdf', '.git/**', '.svn/**');
    JatsIgnore::ScanDir($opt_examine, \&ShowScanData);
}

sub ShowScanData
{
    my ($rv, $absPath) = @_;
    print("$rv : $absPath\n");
}



#-------------------------------------------------------------------------------
#   Documentation
#

=pod

=for htmltoc    SYSUTIL::

=head1 NAME

jats_ignore - Test and use the .jatsignore file

=head1 SYNOPSIS

jats etool jats_ignore [options]

 Options:
    -help              - brief help message
    -help -help        - Detailed help message
    -man               - Full documentation
    -verbose[=n]       - Verbose operation

=head1 OPTIONS

=over 8

=item B<-help>

Print a brief help message and exits.

=item B<-help -help>

Print a detailed help message with an explanation for each option.

=item B<-man>

Prints the manual page and exits.

=item B<-verbose[=n]>

This option will increase the level of verbosity of the command.

If an argument is provided, then it will be used to set the level, otherwise the
existing level will be incremented. This option may be specified multiple times.

=back

=head1 DESCRIPTION

This program will use and check a ".jatsignore" file.

The file is used to:

=over 4

    1   Ignore files and folders for the purposes of Code Metrics generation

    2   Ignore files and folders for the purposes of LXR processing

=back

=head1 FILE FORMAT

The .jatsignore file has the following format:

=over 4

=item *

Lines starting with a '#' are treated as comments and will be ignored.

=item *

Blank lines will be ignored

=item *

Leading and trailing white space will be ignored

=item *

All other lines will be treated as a single 'ignore' specifications.

=item *

The '/' character is used a directory separator.

=back

An ignore' specifications can take one of the following forms:

=over 4

=item *
 
A line starting with a '+' is taken to be a regular expression (regexp), with the '+' removed, all others are simple exclusion patterns.

=item *

A simple exclusion may use '*' and '?' as wildcard characters.

Examples:

    *.pdf
    Test???.ini
    Test/*.ini

=item *

A simple exclusion ending in a / is taken to be a directory to be ignore. Only that directory will be ignored.

Examples:

        Test/
        Test/Data

=item *

A simple exclusion ending in a /* is taken to be a directory to be ignore. The directory and all subdirectories will be ignored.

Examples:

        Test/*

=item *

A regexp ending in a / will have the '/' removed and it will be applied to directories. If the regexp matches then 
the entry will be removed. This can be used to remove individial directories as well as directory trees.

Examples:

        +/Test/             - Will ignore a directory called Test and all subdirs
        +/Test$/            - Will ignore a directory called Test but not its subdirs

=item *

A regexp not ending in a / is used to ignore files. All files match the regexp will be ignored.
 
Examples:

        +/.*pdf$
        +/Test...\.ini$
        +/Test/.*ini$

=back

=head1 EXAMPLE

=head2 Testing

 jats etool jats_ignore -test

This command will locate the .jatsignore file, examine each line for correctness.

=head2 Display

 jats etool jats_ignore -display

This command will locate the .jatsignore file, examine each line for correctness 
and then display the files and folders ignored by the files specifications.

=cut