File Coverage

blib/lib/Jenkins/i18n.pm

Criterion	Covered	Total	%
statement	87	102	85.2
branch	34	52	65.3
condition	6	12	50.0
subroutine	14	16	87.5
pod	5	5	100.0
total	146	187	78.0

package Jenkins::i18n;

use 5.014004;
use strict;
use warnings;
use Carp qw(confess);
use File::Find;
use File::Spec;
use Set::Tiny;

use Jenkins::i18n::Properties;

=pod

=head1 NAME

Jenkins::i18n - functions for the jtt CLI

=head1 SYNOPSIS

  use Jenkins::i18n qw(remove_unused find_files load_properties load_jelly find_langs);

=head1 DESCRIPTION

C is a CLI program used to help translating the Jenkins properties file.

This module implements some of the functions used by the CLI.

=cut

use Exporter 'import';
our @EXPORT_OK = (
    'remove_unused', 'find_files', 'load_properties', 'load_jelly',
    'find_langs'
);

our $VERSION = '0.08';

=head2 EXPORT

None by default.

=head2 FUNCTIONS

=head3 remove_unused

Remove unused keys from a properties file.

Each translation in every language depends on the original properties files
that are written in English.

This function gets a set of keys and compare with those that are stored in the
translation file: anything that exists outside the original set in English is
considered deprecated and so removed.

Expects as positional parameters:

=over

=item 1

file: the complete path to the translation file to be checked.

=item 2

keys: a L instance of the keys from the original English properties
file.

=item 3

license: a scalar reference with a license to include the header of the
translated properties file.

=item 4

backup: a boolean (0 or 1) if a backup file should be created in the same path
of the file parameter. Optional.

=back

Returns the number of keys removed (as an integer).

=cut

sub remove_unused {
    my $file = shift;
    confess "file is a required parameter\n" unless ( defined($file) );
    my $keys = shift;
    confess "keys is a required parameter\n" unless ( defined($keys) );
    confess "keys must be a Set::Tiny instance\n"
        unless ( ref($keys) eq 'Set::Tiny' );
    my $license_ref = shift;
    confess "license must be an array reference"
        unless ( ref($license_ref) eq 'ARRAY' );
    my $use_backup = shift;
    $use_backup = 0 unless ( defined($use_backup) );

    my $props_handler;

    if ($use_backup) {
        my $backup = "$file.bak";
        rename( $file, $backup )
            or confess "Cannot rename $file to $backup: $!\n";
        $props_handler = Jenkins::i18n::Properties->new( file => $backup );
    }
    else {
        $props_handler = Jenkins::i18n::Properties->new( file => $file );
    }

    my $curr_keys = Set::Tiny->new( $props_handler->propertyNames );
    my $to_delete = $curr_keys->difference($keys);

    foreach my $key ( $to_delete->members ) {
        $props_handler->deleteProperty($key);
    }

    open( my $out, '>', $file ) or confess "Cannot write to $file: $!\n";
    $props_handler->save( $out, $license_ref );
    close($out) or confess "Cannot save $file: $!\n";

    return $to_delete->size;
}

=head2 find_files

Find all Jelly and Java Properties files that could be translated from English,
i.e., files that do not have a ISO 639-1 standard language based code as a
filename prefix (before the file extension).

Expects as parameter a complete path to a directory that might contain such
files.

Returns an sorted array reference with the complete path to those files.

=cut

# Relative paths inside the Jenkins project repository
my $src_test_path = File::Spec->catfile( 'src',    'test' );
my $target_path   = File::Spec->catfile( 'target', '' );
my $src_regex     = qr/$src_test_path/;
my $target_regex  = qr/$target_path/;
my $msgs_regex    = qr/Messages\.properties$/;
my $jelly_regex   = qr/\.jelly$/;

sub find_files {
    my $dir = shift;
    confess 'Must provide a string, invalid directory parameter'
        unless ($dir);
    confess 'Must provide a string as directory, not a reference'
        unless ( ref($dir) eq '' );
    confess "Directory $dir must exists" unless ( -d $dir );
    my @files;

    find(
        sub {
            my $file = $File::Find::name;

            unless ( ( $file =~ $src_regex ) or ( $file =~ $target_regex ) ) {
                push( @files, $file )
                    if ( ( $file =~ $msgs_regex )
                    or ( $file =~ $jelly_regex ) );
            }
        },
        $dir
    );
    my @sorted = sort(@files);
    return \@sorted;
}

my $regex = qr/_([a-z]{2})(_[A-Z]{2})?\.properties$/;

=head2 find_langs

Finds all ISO 639-1 standard language based codes available in the Jenkins
repository based on the filenames sufix (before the file extension) of the
translated files.

This is basically the opposite of C does.

It expect as parameters the complete path to a directory to search for the
files.

Returns a instance of the L class containing all the language codes
that were identified.

=cut

sub find_langs {
    my $dir = shift;
    confess 'Must provide a string, invalid directory parameter'
        unless ($dir);
    confess 'Must provide a string as directory, not a reference'
        unless ( ref($dir) eq '' );
    confess "Directory $dir must exists" unless ( -d $dir );
    my $langs = Set::Tiny->new;

    find(
        sub {
            my $file = $File::Find::name;

            unless ( ( $file =~ $src_regex ) or ( $file =~ $target_regex ) ) {
                if ( $file =~ $regex ) {
                    my $lang;

                    if ($2) {
                        $lang = $1 . $2;
                    }
                    else {
                        $lang = $1;
                    }

                    $langs->insert($lang);
                }
            }
        },
        $dir
    );

    return $langs;
}

=head2 load_properties

Loads the content of a Java Properties file into a hash.

Expects as position parameters:

=over

=item 1

The complete path to a Java Properties file.

=item 2

True (1) or false (0) if a warn should be printed to C in case the file
is missing.

=back

Returns an hash reference with the file content. If the file doesn't exist,
returns an empty hash reference.

=cut

sub load_properties {
    my ( $file, $must_warn ) = @_;
    confess 'The complete path to the properties file is required'
        unless ($file);
    confess 'Must pass if a warning is required or not'
        unless ( defined($must_warn) );

    unless ( -f $file ) {
        warn "File $file doesn't exist, skipping it...\n" if ($must_warn);
        return {};
    }

    my $props_handler = Jenkins::i18n::Properties->new( file => $file );
    return $props_handler->getProperties;
}

=head2 load_jelly

Fill a hash with key/1 pairs from a C<.jelly> file.

Expects as parameter the path to a Jelly file.

Returns a hash reference.

=cut

# TODO: replace regex with XML parser
sub load_jelly {
    my $file = shift;
    my %ret;

    open( my $fh, '<', $file ) or confess "Cannot read $file: $!\n";

    while (<$fh>) {
        next if ( !/\$\{.*?\%([^\(]+?).*\}/ );
        my $line = $_;
        while ($line =~ /^.*?\$\{\%([^\(\}]+)(.*)$/
            || $line =~ /^.*?\$\{.*?['"]\%([^\(\}\"\']+)(.*)$/ )
        {
            $line = $2;
            my $word = $1;
            $word =~ s/\(.+$//g;
            $word =~ s/'+/''/g;
            $word =~ s/ /\\ /g;
            $word =~ s/\>/>/g;
            $word =~ s/\</
            $word =~ s/\&/&/g;
            $word =~ s/([#:=])/\\$1/g;
            $ret{$word} = 1;
        }
    }

    close($fh);
    return \%ret;
}

1;

__END__