File Coverage

blib/lib/Pod/Readme/Types.pm

Criterion	Covered	Total	%
statement	55	61	90.1
branch	7	8	87.5
condition	4	6	66.6
subroutine	28	34	82.3
pod	8	8	100.0
total	102	117	87.1

package Pod::Readme::Types;

use v5.10.1;

use feature 'state';

use strict;
use warnings;

our $VERSION = 'v1.2.2';

use Exporter qw/ import /;
use IO qw/ Handle /;
use Path::Tiny;
use Scalar::Util qw/ blessed /;
use Type::Tiny;
use Types::Standard qw/ FileHandle Str /;

# RECOMMEND PREREQ: Type::Tiny::XS

our @EXPORT_OK =
  qw/ Dir File Indentation IO ReadIO WriteIO HeadingLevel TargetName DistZilla /;

=head1 NAME

Pod::Readme::Types - Types used by Pod::Readme

=head1 SYNOPSIS

  use Pod::Readme::Types qw/ Indentation /;

  has verbatim_indent => (
    is      => 'ro',
    isa     => Indentation,
    default => 2,
  );

=head1 DESCRIPTION

This module provides types for use with the modules in L.

It is intended for internal use, although some of these may be useful
for writing plugins (see L).

=head1 EXPORTS

None by default. All functions must be explicitly exported.

=head2 C

The indentation level used for verbatim text. Must be an integer
greater than or equal to 2.

=cut

sub Indentation {
    state $type = Type::Tiny->new(
        name       => 'Indentation',
        constraint => sub { $_ =~ /^\d+$/ && $_ >= 2 },
        message => sub { 'must be an integer >= 2' },
    );
    return $type;
}

=head2 C

A heading level, used for plugin headings.

Must be either 1, 2 or 3. (Note that C<=head4> is not allowed, since
some plugins use subheadings.)

=cut

sub HeadingLevel {
    state $type = Type::Tiny->new(
        name       => 'HeadingLevel',
        constraint => sub { $_ =~ /^[123]$/ },
        message    => sub { 'must be an integer between 1 and 3' },
    );
    return $type;
}

=head2 C

A name of a target, e.g. "readme".

=cut

sub TargetName {
    state $type = Type::Tiny->new(
        name       => 'TargetName',
        constraint => sub { $_ =~ /^\w+$/ },
        message    => sub { 'must be an alphanumeric string' },
    );
    return $type;
}

=head2 C

A directory. Can be a string or L object.

=cut

sub Dir {
    state $type = Type::Tiny->new(
        name       => 'Dir',
        constraint => sub {
            blessed($_)
              && $_->isa('Path::Tiny')
              && -d $_;
        },
        message => sub { "$_ must be be a directory" },
    );
    return $type->plus_coercions( Str, sub { path($_) }, );
}

=head2 C

A file. Can be a string or L object.

=cut

sub File {
    state $type = Type::Tiny->new(
        name       => 'File',
        constraint => sub {
            blessed($_)
              && $_->isa('Path::Tiny');
        },
        message => sub { "$_ must be be a file" },
    );
    return $type->plus_coercions( Str, sub { path($_) }, );
}

=head2 C

An L or L object.

=cut

sub IO {
    state $type = Type::Tiny->new(
        name       => 'IO',
        constraint => sub {
            blessed($_)
              && ( $_->isa('IO::Handle') || $_->isa('IO::String') );
        },
        message => sub { 'must be be an IO::Handle or IO::String' },
    );
    return $type;
}

=head2 C

=head2 C

L types, which coerce filehandles to read/write L,
respectively.

=cut

sub ReadIO {
    state $type = IO->plus_coercions(    #
        FileHandle, sub { IO::Handle->new_from_fd( $_, 'r' ) },
    );
    return $type;
}

sub WriteIO {
    state $type = IO->plus_coercions(    #
        FileHandle, sub { IO::Handle->new_from_fd( $_, 'w' ) },
    );
    return $type;
}

1;