lib/MooseX/Types/Path/Class.pm

   1 package MooseX::Types::Path::Class;
   2
   3 use warnings FATAL => 'all';
   4 use strict;
   5
   6 use Path::Class ();
   7 # TODO: export dir() and file() from Path::Class? (maybe)
   8
   9 use MooseX::Types
  10     -declare => [qw( Dir File ExistingDir ExistingFile NonExistingDir NonExistingFile )];
  11
  12 use MooseX::Types::Moose qw(Str ArrayRef);
  13
  14 class_type('Path::Class::Dir');
  15 class_type('Path::Class::File');
  16
  17 subtype Dir, as 'Path::Class::Dir';
  18 subtype File, as 'Path::Class::File';
  19
  20 subtype ExistingFile, as File, where { -e $_->stringify },
  21     message { "File '$_' must exist." };
  22
  23 subtype NonExistingFile, as File, where { !-e $_->stringify },
  24     message { "File '$_' must not exist." };
  25
  26 subtype ExistingDir, as Dir,
  27     where { -e $_->stringify && -d $_->stringify },
  28     message { "Directory '$_' must exist" };
  29
  30 subtype NonExistingDir, as Dir,
  31     where { !-e $_->stringify },
  32     message { "Directory '$_' not must exist" };
  33
  34 for my $type ( 'Path::Class::Dir', Dir, ExistingDir, NonExistingDir ) {
  35     coerce $type,
  36         from Str,      via { Path::Class::Dir->new("$_") },
  37         from ArrayRef, via { Path::Class::Dir->new(@$_) };
  38 }
  39
  40 for my $type ( 'Path::Class::File', File, ExistingFile, NonExistingFile ) {
  41     coerce $type,
  42         from Str,      via { Path::Class::File->new("$_") },
  43         from ArrayRef, via { Path::Class::File->new(@$_) };
  44 }
  45
  46 # optionally add Getopt option type
  47 eval { require MooseX::Getopt; };
  48 if ( !$@ ) {
  49     MooseX::Getopt::OptionTypeMap->add_option_type_to_map( $_, '=s', )
  50         for (
  51             'Path::Class::Dir', 'Path::Class::File',
  52             Dir,                 File,
  53             ExistingDir,         ExistingFile,
  54             NonExistingFile,     NonExistingDir,
  55         );
  56 }
  57
  58 1;
  59 __END__
  60
  61
  62 =head1 NAME
  63
  64 MooseX::Types::Path::Class - A Path::Class type library for Moose
  65
  66
  67 =head1 SYNOPSIS
  68
  69   package MyClass;
  70   use Moose;
  71   use MooseX::Types::Path::Class;
  72   with 'MooseX::Getopt';  # optional
  73
  74   has 'dir' => (
  75       is       => 'ro',
  76       isa      => 'Path::Class::Dir',
  77       required => 1,
  78       coerce   => 1,
  79   );
  80
  81   has 'file' => (
  82       is       => 'ro',
  83       isa      => 'Path::Class::File',
  84       required => 1,
  85       coerce   => 1,
  86   );
  87
  88   # these attributes are coerced to the
  89   # appropriate Path::Class objects
  90   MyClass->new( dir => '/some/directory/', file => '/some/file' );
  91
  92
  93 =head1 DESCRIPTION
  94
  95 MooseX::Types::Path::Class creates common L<Moose> types,
  96 coercions and option specifications useful for dealing
  97 with L<Path::Class> objects as L<Moose> attributes.
  98
  99 Coercions (see L<Moose::Util::TypeConstraints>) are made
 100 from both 'Str' and 'ArrayRef' to both L<Path::Class::Dir> and
 101 L<Path::Class::File> objects.  If you have L<MooseX::Getopt> installed,
 102 the Getopt option type ("=s") will be added for both
 103 L<Path::Class::Dir> and L<Path::Class::File>.
 104
 105
 106 =head1 EXPORTS
 107
 108 None of these are exported by default.  They are provided via
 109 L<MooseX::Types>.
 110
 111 =over
 112
 113 =item Dir, File
 114
 115 These exports can be used instead of the full class names.  Example:
 116
 117   package MyClass;
 118   use Moose;
 119   use MooseX::Types::Path::Class qw(Dir File);
 120
 121   has 'dir' => (
 122       is       => 'ro',
 123       isa      => Dir,
 124       required => 1,
 125       coerce   => 1,
 126   );
 127
 128   has 'file' => (
 129       is       => 'ro',
 130       isa      => File,
 131       required => 1,
 132       coerce   => 1,
 133   );
 134
 135 Note that there are no quotes around Dir or File.
 136
 137 =item ExistingDir, ExistingFile
 138
 139 Like File and Dir, but the files or directories must exist on disk
 140 when the type is checked, and the object on disk must be a file (for
 141 ExistingFile) or directory (for ExistingDir).
 142
 143 At no point will this library attempt to coerce a path into existence
 144 by creating directories or files.  The coercions for ExistingDir and ExistingFile
 145 simply coerce 'Str' and 'ArrayRef' to L<Path::Class> objects.
 146
 147 These types do rely on I/O.  The case could be made that this makes them not
 148 suitable to be called "types".  Consider a file that gets removed after the
 149 ExistingFile type is checked.  This can be a source of difficult to find bugs
 150 (you've been warned).  Often, you're going to check (either explicitly or implicitly)
 151 whether a path exists at the point where you're actually going to use it
 152 anyway.  In such cases you may be better off using the Dir or File type and then
 153 later (say, in some method) check for existence yourself instead of using these types
 154 constraints that you can't really trust to remain true indefinitely.
 155
 156
 157 =item NonExistingDir, NonExistingFile
 158
 159 Like File and Dir, but the path must not exist on disk
 160 when the type is checked.
 161
 162 At no point will this library attempt to coerce a path into non-existence
 163 by removing directories or files.  The coercions for NonExistingDir and NonExistingFile
 164 simply coerce 'Str' and 'ArrayRef' to L<Path::Class> objects.
 165
 166 The same caveats regarding I/O for the Existing* types above apply here as well.
 167
 168 =item is_$type($value)
 169
 170 Returns true or false based on whether $value passes the constraint for $type.
 171
 172 =item to_$type($value)
 173
 174 Attempts to coerce $value to the given $type.  Returns the coerced value
 175 or false if the coercion failed.
 176
 177 =back
 178
 179
 180 =head1 SEE ALSO
 181
 182 L<MooseX::Types::Path::Class::MoreCoercions>
 183
 184
 185 =head1 DEPENDENCIES
 186
 187 L<Moose>, L<MooseX::Types>, L<Path::Class>
 188
 189
 190 =head1 BUGS AND LIMITATIONS
 191
 192 If you find a bug please either email the author, or add
 193 the bug to cpan-RT L<http://rt.cpan.org>.
 194
 195
 196 =head1 AUTHOR
 197
 198 Todd Hepler  C<< <thepler@employees.org> >>
 199
 200
 201 =head1 LICENCE AND COPYRIGHT
 202
 203 Copyright (c) 2007-2009, Todd Hepler C<< <thepler@employees.org> >>.
 204
 205 This module is free software; you can redistribute it and/or
 206 modify it under the same terms as Perl itself. See L<perlartistic>.
 207
 208