lib/MooseX/Types/Path/Class.pm

   1 package MooseX::Types::Path::Class;
   2
   3 use warnings FATAL => 'all';
   4 use strict;
   5
   6 our $VERSION = '0.05';
   7 our $AUTHORITY = 'cpan:THEPLER';
   8
   9 use Path::Class ();
  10 # TODO: export dir() and file() from Path::Class? (maybe)
  11
  12 use MooseX::Types
  13     -declare => [qw( Dir File ExistingDir ExistingFile )];
  14
  15 use MooseX::Types::Moose qw(Str ArrayRef);
  16
  17 class_type('Path::Class::Dir');
  18 class_type('Path::Class::File');
  19
  20 subtype Dir, as 'Path::Class::Dir';
  21 subtype File, as 'Path::Class::File';
  22
  23 subtype ExistingFile, as File, where { -e $_->stringify },
  24   message { "File '$_' must exist." };
  25
  26 subtype ExistingDir, as Dir, where { -e $_->stringify && -d $_->stringify },
  27   message { "Directory '$_' must exist" };
  28
  29 for my $type ( 'Path::Class::Dir', Dir, ExistingDir ) {
  30     coerce $type,
  31         from Str,      via { Path::Class::Dir->new($_) },
  32         from ArrayRef, via { Path::Class::Dir->new(@$_) };
  33 }
  34
  35 for my $type ( 'Path::Class::File', File, ExistingFile ) {
  36     coerce $type,
  37         from Str,      via { Path::Class::File->new($_) },
  38         from ArrayRef, via { Path::Class::File->new(@$_) };
  39 }
  40
  41 # optionally add Getopt option type
  42 eval { require MooseX::Getopt; };
  43 if ( !$@ ) {
  44     MooseX::Getopt::OptionTypeMap->add_option_type_to_map( $_, '=s', )
  45         for ( 'Path::Class::Dir', 'Path::Class::File', Dir, File, ExistingDir, ExistingFile );
  46 }
  47
  48 1;
  49 __END__
  50
  51
  52 =head1 NAME
  53
  54 MooseX::Types::Path::Class - A Path::Class type library for Moose
  55
  56
  57 =head1 SYNOPSIS
  58
  59   package MyClass;
  60   use Moose;
  61   use MooseX::Types::Path::Class;
  62   with 'MooseX::Getopt';  # optional
  63
  64   has 'dir' => (
  65       is       => 'ro',
  66       isa      => 'Path::Class::Dir',
  67       required => 1,
  68       coerce   => 1,
  69   );
  70
  71   has 'file' => (
  72       is       => 'ro',
  73       isa      => 'Path::Class::File',
  74       required => 1,
  75       coerce   => 1,
  76   );
  77
  78   # these attributes are coerced to the
  79   # appropriate Path::Class objects
  80   MyClass->new( dir => '/some/directory/', file => '/some/file' );
  81
  82
  83 =head1 DESCRIPTION
  84
  85 MooseX::Types::Path::Class creates common L<Moose> types,
  86 coercions and option specifications useful for dealing
  87 with L<Path::Class> objects as L<Moose> attributes.
  88
  89 Coercions (see L<Moose::Util::TypeConstraints>) are made
  90 from both 'Str' and 'ArrayRef' to both L<Path::Class::Dir> and
  91 L<Path::Class::File> objects.  If you have L<MooseX::Getopt> installed,
  92 the Getopt option type ("=s") will be added for both
  93 L<Path::Class::Dir> and L<Path::Class::File>.
  94
  95
  96 =head1 EXPORTS
  97
  98 None of these are exported by default.  They are provided via
  99 L<MooseX::Types>.
 100
 101 =over
 102
 103 =item Dir, File
 104
 105 These exports can be used instead of the full class names.  Example:
 106
 107   package MyClass;
 108   use Moose;
 109   use MooseX::Types::Path::Class qw(Dir File);
 110
 111   has 'dir' => (
 112       is       => 'ro',
 113       isa      => Dir,
 114       required => 1,
 115       coerce   => 1,
 116   );
 117
 118   has 'file' => (
 119       is       => 'ro',
 120       isa      => File,
 121       required => 1,
 122       coerce   => 1,
 123   );
 124
 125 =item ExistingDir, ExistingFile
 126
 127 Like File and Dir, but the files or directories must exist on disk
 128 when the type is checked, and the object on disk must be a file (for
 129 ExistingFile) or directory (for ExistingDir).
 130
 131 Note that there are no quotes around Dir or File.
 132
 133 =item is_Dir($value), is_File($value)
 134
 135 Returns true or false based on whether $value is a valid Dir or File.
 136
 137 =item to_Dir($value), to_File($value)
 138
 139 Attempts to coerce $value to a Dir or File.  Returns the coerced value
 140 or false if the coercion failed.
 141
 142 =back
 143
 144
 145 =head1 DEPENDENCIES
 146
 147 L<Moose>, L<MooseX::Types>, L<Path::Class>
 148
 149
 150 =head1 BUGS AND LIMITATIONS
 151
 152 If you find a bug please either email the author, or add
 153 the bug to cpan-RT L<http://rt.cpan.org>.
 154
 155
 156 =head1 AUTHOR
 157
 158 Todd Hepler  C<< <thepler@employees.org> >>
 159
 160
 161 =head1 LICENCE AND COPYRIGHT
 162
 163 Copyright (c) 2007-2008, Todd Hepler C<< <thepler@employees.org> >>.
 164
 165 This module is free software; you can redistribute it and/or
 166 modify it under the same terms as Perl itself. See L<perlartistic>.
 167
 168