=encoding utf8
=head1 NAME
Any::Daemon::HTTP::Directory - describe a server directory
=head1 INHERITANCE
Any::Daemon::HTTP::Directory
is a Any::Daemon::HTTP::Source
Any::Daemon::HTTP::Directory is extended by
Any::Daemon::HTTP::UserDirs
=head1 SYNOPSIS
# implicit creation of ::Directory object
my $vh = Any::Daemon::HTTP::VirtualHost
->new(directories => {path => '/', location => ...})
my $vh = Any::Daemon::HTTP::VirtualHost
->new(directories => [ \%dir1, \%dir2, $dir_obj ])
# explicit use
my $root = Any::Daemon::HTTP::Directory
->new(path => '/', location => '...');
my $vh = Any::Daemon::HTTP::VirtualHost
->new(directories => $root);
=head1 DESCRIPTION
Each L<Any::Daemon::HTTP::VirtualHost|Any::Daemon::HTTP::VirtualHost> will define where the files
are located. Parts of the URI path can map on different (virtual)
directories, with different access rights.
See L<documentation in the base class|Any::Daemon::HTTP::Source/"DESCRIPTION">.
=head1 METHODS
See L<documentation in the base class|Any::Daemon::HTTP::Source/"METHODS">.
=head2 Constructors
See L<documentation in the base class|Any::Daemon::HTTP::Source/"Constructors">.
=over 4
=item Any::Daemon::HTTP::Directory-E<gt>B<new>(OPTIONS|HASH-of-OPTIONS)
-Option --Defined in --Default
allow Any::Daemon::HTTP::Source <undef>
charset utf-8
deny Any::Daemon::HTTP::Source <undef>
directory_list <false>
index_file ['index.html', 'index.htm']
location <required>
name Any::Daemon::HTTP::Source path
path Any::Daemon::HTTP::Source '/'
=over 2
=item allow => CIDR|HOSTNAME|DOMAIN|CODE|ARRAY
=item charset => STRING
The character-set which is used all text-files on the system, used in
response headers of text-files.
=item deny => CIDR|HOSTNAME|DOMAIN|CODE|ARRAY
=item directory_list => BOOLEAN
Enables the display of a directory, when it does not contain one of the
C<index_file> prepared defaults.
=item index_file => STRING|ARRAY
When a directory is addressed, it is scanned whether one of these files
exist. If so, the content will be shown.
=item location => DIRECTORY|CODE
The DIRECTORY to be prefixed before the path of the URI, or a CODE
reference which will rewrite the path (passed as only parameter) into the
absolute file or directory name.
=item name => STRING
=item path => PATH
=back
=back
=head2 Attributes
See L<documentation in the base class|Any::Daemon::HTTP::Source/"Attributes">.
=over 4
=item $obj-E<gt>B<charset>()
=item $obj-E<gt>B<location>()
=item $obj-E<gt>B<name>()
See L<Any::Daemon::HTTP::Source/"Attributes">
=item $obj-E<gt>B<path>()
See L<Any::Daemon::HTTP::Source/"Attributes">
=back
=head2 Permissions
See L<documentation in the base class|Any::Daemon::HTTP::Source/"Permissions">.
=over 4
=item $obj-E<gt>B<allow>(SESSION, REQUEST, URI)
See L<Any::Daemon::HTTP::Source/"Permissions">
=item $obj-E<gt>B<collect>(VHOST, SESSION, REQUEST, URI)
See L<Any::Daemon::HTTP::Source/"Permissions">
=back
=head2 Actions
See L<documentation in the base class|Any::Daemon::HTTP::Source/"Actions">.
=over 4
=item $obj-E<gt>B<filename>(PATH)
Convert a URI PATH into a directory path. Return C<undef> if not possible.
=item $obj-E<gt>B<list>(DIRECTORY, OPTIONS)
Returns a HASH with information about the DIRECTORY content. This may
be passed into some template or the default template. See L</Return of
directoryList> about the returned output.
-Option --Default
filter <undef>
hide_symlinks <false>
names <skip hidden files>
=over 2
=item filter => CODE
For each of the selected names (see C<names> option) the lstat() is
called. That data is expanded into a HASH, but not all additional
fields are yet filled-in (only the ones which come for free).
=item hide_symlinks => BOOLEAN
=item names => CODE|Regexp
Reduce the returned list. The CODE reference is called with the found
filename, and should return true when the name is acceptable. The
default regexp (on UNIX) is C<< qr/^[^.]/ >>
=back
=back
=head1 DETAILS
See L<documentation in the base class|Any::Daemon::HTTP::Source/"DETAILS">.
=head2 Resource restrictions
See L<documentation in the base class|Any::Daemon::HTTP::Source/"Resource restrictions">.
=head2 Return of list()
The L<list()|Any::Daemon::HTTP::Directory/"Actions"> method returns a HASH of HASHes, where the
primary keys are the directory entries, each refering to a HASH
with details. It is designed to ease the connection to template
systems.
The details contain the C<lstat> information plus some additional
helpers. The lstat call provides the fields C<dev>, C<ino>, C<mode>,
C<nlink>, C<uid>, C<gid>, C<rdev>, C<size>, C<atime>, C<mtime>,
C<ctime>, C<blksize>, C<blocks> -as far as supported by your OS.
The entry's C<name> and C<path> are added.
The C<kind> field contains the string C<DIRECTORY>, C<FILE>, C<SYMLINK>,
or C<OTHER>. Besides, you get either an C<is_directory>, C<is_file>,
C<is_symlink>, or C<is_other> field set to true. Equivalent are:
if($entry->{kind} eq 'DIRECTORY')
if($entry->{is_directory})
It depends on the kind of entry which of the following fields are added
additionally. Symlinks will get C<symlink_dest>, C<symlink_dest_exists>.
Files hace the C<size_nice>, which is the size in pleasant humanly readable
format.
Files and directories have the C<mtime_nice> (in localtime). The C<user> and
C<group> which are textual representations of the numeric uid and gid are
added. The C<flags> represents the UNIX standard permission-bit display,
as produced by the "ls -l" command.
=head1 SEE ALSO
This module is part of Any-Daemon-HTTP distribution version 0.24,
built on January 05, 2014. Website: F<http://perl.overmeer.net/any-daemon/>
=head1 LICENSE
Copyrights 2013-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>