view release on metacpan or  search on metacpan

lib/Any/Daemon/HTTP/Directory.pod  view on Meta::CPAN

=encoding utf8

=head1 NAME

Any::Daemon::HTTP::Directory - describe a server directory 

=head1 INHERITANCE

 Any::Daemon::HTTP::Directory
   is an 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.

Extends L<"DESCRIPTION" in Any::Daemon::HTTP::Source|Any::Daemon::HTTP::Source/"DESCRIPTION">.
 
=head1 METHODS

Extends L<"METHODS" in Any::Daemon::HTTP::Source|Any::Daemon::HTTP::Source/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in Any::Daemon::HTTP::Source|Any::Daemon::HTTP::Source/"Constructors">.
 
=over 4

=item Any::Daemon::HTTP::Directory-E<gt>B<new>(%options|\%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

Extends L<"Attributes" in Any::Daemon::HTTP::Source|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>()

Inherited, see L<Any::Daemon::HTTP::Source/"Attributes">

=item $obj-E<gt>B<path>()

Inherited, see L<Any::Daemon::HTTP::Source/"Attributes">

=back

=head2 Permissions

Extends L<"Permissions" in Any::Daemon::HTTP::Source|Any::Daemon::HTTP::Source/"Permissions">.
 
=over 4

=item $obj-E<gt>B<allow>($session, $request, $uri)

Inherited, see L<Any::Daemon::HTTP::Source/"Permissions">

=item $obj-E<gt>B<collect>($vhost, $session, $request, $uri)

Inherited, see L<Any::Daemon::HTTP::Source/"Permissions">

=back

=head2 Actions

Extends L<"Actions" in Any::Daemon::HTTP::Source|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