File Coverage

blib/lib/Perl/Critic/Freenode/Utils.pm

Criterion	Covered	Total	%
statement	27	27	100.0
branch	10	14	71.4
condition	13	23	56.5
subroutine	7	7	100.0
pod	2	2	100.0
total	59	73	80.8

package Perl::Critic::Freenode::Utils;

use strict;
use warnings;
use Carp 'croak';
use Exporter 'import';
use Scalar::Util 'blessed';

our $VERSION = '0.033';

our @EXPORT_OK = qw(is_empty_return is_structural_block);

my %modifiers = map { ($_ => 1) } qw(if unless while until for foreach when);
my %compound = map { ($_ => 1) } qw(if unless while until for foreach given);

sub is_empty_return {
	my $elem = shift;
	croak 'is_empty_return must be called with a PPI::Token::Word return element'
		unless blessed $elem and $elem->isa('PPI::Token::Word') and $elem eq 'return';

	my $next = $elem->snext_sibling || return 1;
	return 1 if $next->isa('PPI::Token::Structure') and $next eq ';';
	return 1 if $next->isa('PPI::Token::Word') and exists $modifiers{$next};

	return 0;
}

sub is_structural_block {
	my $elem = shift;
	croak 'is_structural_block must be called with a PPI::Structure::Block element'
		unless blessed $elem and $elem->isa('PPI::Structure::Block');

	if (my $parent = $elem->parent) {
		if ($parent->isa('PPI::Statement::Compound') and my $first = $parent->schild(0)) {
			return 1 if $first->isa('PPI::Token::Word') and exists $compound{$first};
		}
	}

	# TODO: Allow bare blocks or blocks with labels

	return 0;
}

1;

=head1 NAME

Perl::Critic::Freenode::Utils - Utility functions for the Freenode policy set

=head1 DESCRIPTION

This module contains utility functions for use in L<Perl::Critic::Freenode>
policies. All functions are exportable on demand.

=head1 FUNCTIONS

=head2 is_empty_return

 my $bool = is_empty_return($elem);

Tests whether a L<PPI::Token::Word> C<return> element represents an empty
C<return> statement. This function returns false for C<return()>.

=head2 is_structural_block

 my $bool = is_structural_block($elem);

Tests whether a L<PPI::Structure::Block> element is structural, and does not
introduce a new calling context. This function currently only returns true for
blocks in compound statements such as C<if> and C<foreach>, but may be extended
to cover more cases in the future.

=head1 AUTHOR

Dan Book, C<[e-mail]>

=head1 COPYRIGHT AND LICENSE

Copyright 2015, Dan Book.

This library is free software; you may redistribute it and/or modify it under
the terms of the Artistic License version 2.0.

=head1 SEE ALSO

L<Perl::Critic>