1 package MooseX::Types::Path::Class;
3 use warnings FATAL => 'all';
7 # TODO: export dir() and file() from Path::Class? (maybe)
10 -declare => [qw( Dir File ExistingDir ExistingFile NonExistingDir NonExistingFile )];
12 use MooseX::Types::Moose qw(Str ArrayRef);
14 class_type('Path::Class::Dir');
15 class_type('Path::Class::File');
17 subtype Dir, as 'Path::Class::Dir';
18 subtype File, as 'Path::Class::File';
20 subtype ExistingFile, as File, where { -e $_->stringify },
21 message { "File '$_' must exist." };
23 subtype NonExistingFile, as File, where { !-e $_->stringify },
24 message { "File '$_' must not exist." };
26 subtype ExistingDir, as Dir,
27 where { -e $_->stringify && -d $_->stringify },
28 message { "Directory '$_' must exist" };
30 subtype NonExistingDir, as Dir,
31 where { !-e $_->stringify },
32 message { "Directory '$_' not must exist" };
34 for my $type ( 'Path::Class::Dir', Dir, ExistingDir, NonExistingDir ) {
36 from Str, via { Path::Class::Dir->new("$_") },
37 from ArrayRef, via { Path::Class::Dir->new(@$_) };
40 for my $type ( 'Path::Class::File', File, ExistingFile, NonExistingFile ) {
42 from Str, via { Path::Class::File->new("$_") },
43 from ArrayRef, via { Path::Class::File->new(@$_) };
46 # optionally add Getopt option type
47 eval { require MooseX::Getopt; };
49 MooseX::Getopt::OptionTypeMap->add_option_type_to_map( $_, '=s', )
51 'Path::Class::Dir', 'Path::Class::File',
53 ExistingDir, ExistingFile,
54 NonExistingFile, NonExistingDir,
64 MooseX::Types::Path::Class - A Path::Class type library for Moose
71 use MooseX::Types::Path::Class;
72 with 'MooseX::Getopt'; # optional
76 isa => 'Path::Class::Dir',
83 isa => 'Path::Class::File',
88 # these attributes are coerced to the
89 # appropriate Path::Class objects
90 MyClass->new( dir => '/some/directory/', file => '/some/file' );
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.
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>.
108 None of these are exported by default. They are provided via
115 These exports can be used instead of the full class names. Example:
119 use MooseX::Types::Path::Class qw(Dir File);
135 Note that there are no quotes around Dir or File.
137 =item ExistingDir, ExistingFile
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).
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.
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.
157 =item NonExistingDir, NonExistingFile
159 Like File and Dir, but the path must not exist on disk
160 when the type is checked.
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.
166 The same caveats regarding I/O for the Existing* types above apply here as well.
168 =item is_$type($value)
170 Returns true or false based on whether $value passes the constraint for $type.
172 =item to_$type($value)
174 Attempts to coerce $value to the given $type. Returns the coerced value
175 or false if the coercion failed.
182 L<MooseX::Types::Path::Class::MoreCoercions>
187 L<Moose>, L<MooseX::Types>, L<Path::Class>
190 =head1 BUGS AND LIMITATIONS
192 If you find a bug please either email the author, or add
193 the bug to cpan-RT L<http://rt.cpan.org>.
198 Todd Hepler C<< <thepler@employees.org> >>
201 =head1 LICENCE AND COPYRIGHT
203 Copyright (c) 2007-2009, Todd Hepler C<< <thepler@employees.org> >>.
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>.