Provided by: sympa_6.2.70~dfsg-2_amd64 bug

NAME

       Sympa::WWW::SharedDocument - Shared document repository and its nodes

SYNOPSIS

         use Sympa::WWW::SharedDocument;

         $shared = Sympa::WWW::SharedDocument->new($list, $path);

         %access = $shared->get_privileges('read', $email, 'md5', {...});
         @children = $shared->get_children;
         $parent = $shared->{parent};

DESCRIPTION

       Sympa::WWW::SharedDocument implements shared document repository of lists.

   Methods
       new ( $list, [ $path, [ allow_empty => 1 ] ] )
           Constructor.  Creates new instance.

           Parameters:

           $list
               A Sympa::List instance.

           $path
               String to determine path or arrayref of path components.  The path is relative to
               repository root.

           allow_empty => 1
               Don't omit files with zero size.

           Returns:

           If $path is empty or not specified, returns new instance of repository root; {status}
           attribute will be set.  If $path is not empty and the path exists, returns new
           instance of node.  Otherwise returns false value.

       as_hashref ( )
           Instance method.  Casts the instance to hashref.

           Parameters:

           None.

           Returns:

           A hashref including attributes of instance (see "Attributes") and following special
           items:

           {ancestors}
               Arrayref of hashrefs including some attributes of all ancestor nodes.

           {context}
               Hashref including name and host of the list.

           {date}
               Localized form of {date_epoch}.

           {parent}
               Hashref including attributes of parent node recursively.

           {paths_d}
               Same as {paths} but, if the node is a directory, includes additional empty
               component at the end.  This is useful when the path created by join() should be
               followed by additional "/" character.

       count_children ( )
           Instance method.  Returns number of child nodes.

       count_moderated_descendants ( )
           Instance method.  Returns number of nodes waiting for moderation.

       create_child ( $name, owner => $email, scenario => $scenario, type => $type, [ content =>
       $content ] )
           Instance method.  Creates child node and returns it.  TBD.

       get_children ( [ moderate => boolean ], [ name => $name ], [ order_by => $order ], [ owner
       => $email ], [ allow_empty => 1 ] )
           Instance method.  Gets child nodes.

           Parameters:

           moderate => boolean
           name => $name
           owner => $email
               Filters results.

           order_by => $order
               Sorts results.  $order may be one of 'order_by_doc' (by name of nodes),
               'order_by_author' (by owner), 'order_by_size' (by size), 'order_by_date' (by
               modification time).  Default is ordering by names.

           allow_empty => 1
               Don't omit nodes with zero size.

           Returns:

           (Possibly empty) list of child nodes.

       get_moderated_descendants ( )
           Instance method.  Returns the list of nodes waiting for moderation.

           Parameters:

           None.

           Returns:

           In array context, a list of nodes.  In scalar context, an arrayref of them.

       get_privileges ( mode => $mode, sender => $sender, auth_method => $auth_method,
       scenario_context => $scenario_context )
           Instance method.  Gets privileges of a user on the node.

           TBD.

       get_size ( )
           Instance method.  Gets total size under current node.

       install ( )
           Instance method.  Approves (install) file if it was held for moderation.

           Returns:

           True value.  If installation failed, returns false value and sets $ERRNO ($!).

       rename ( $new_name )
           Instance method.  Renames file or directory.

           Parameters:

           $new_name
               The name to be renamed to.

           Returns:

           True value.  If renaming failed, returns false value and sets $ERRNO ($!).

       rmdir ( )
           instance method.  Removes directory from repository.  Directory must be empty.

           Returns:

           True value.  If removal failed, returns false value and sets $ERRNO ($!).

       save_description ( )
           Instance method.  Creates or updates property description of the node.

       unlink ( )
           instance method.  Removes file from repository.

           Returns:

           True value.  If removal failed, returns false value and sets $ERRNO ($!).

       get_id ( )
           Instance method.  Returns unique identifier of instance.

       Methods for repository root

       create ( )
           Instance method.  Creates document repository on physical filesystem.

       delete ( )
           Instance method.  Deletes document repository.

       restore ( )
           Instance method.  Restores deleted document repository.

   Functions
       valid_name ( $new_name )
           Function.  Check if the name is allowed for directory and file.

           Note: This should be used with name of newly created node.  Existing files and
           directories may have the name not allowed by this function.

   Attributes
       Instance of Sympa::WWW::SharedDocument may have following attributes.

       {context}
           Mandatory.  Instance of Sympa::List class the shared document repository belongs to.

       {date_epoch}
           Mandatory.  Modification time of node in Unix time.

       {file_extension}
           File extension if any.

       {fs_name}
           Mandatory.  Name of node on physical filesystem, i.e. the last part of {fs_path}.

       {fs_path}
           Mandatory.  Full path of node on physical filesystem.

       {html}
           Only in HTML file.  True value will be set.

       {icon}
           URL to icon.

       {label}
           Only in bookmark file.  Label to be shown in hyperlink.

       {mime_type}
           Only in regular file.  MIME content type of the file if it is known.

       {moderate}
           Set if node is held for moderation.

       {name}
           Mandatory.  Name of node accessible by users, i.e. the last item of {paths}.

       {owner}
           Owner (author) of node, given by property description.

       {parent}
           Parent node if any.  Sympa::WWW::SharedDocument instance.

       {paths}
           Mandatory.  Arrayref to all path components of node accessible by users.

       {scenario}{read}
       {scenario}{edit}
           Scenario names to define privileges.  These may be given by property description.

       {serial_desc}
           Modification time of property description in Unix time.  Available if property
           description exists.

       {size}
           Size of file.

       {status}
           Only in repository root.  Status of repository: 'exist', 'deleted' or 'none'.

       {title}
           Description of node, given by property description.

       {type}
           Mandatory.  Type of node.  'root' (the root of repository), 'directory' (directory),
           'url' (bookmark file) or 'file' (other file).

       {url}
           Only in bookmark file.  URL to be linked.

FILES

       list home/shared/
           Root of repository.

       ... path/name
           Directory or file.

       ... path/.name.moderate
           Moderated directory or file.

       ... path/name/.desc
       ... path/.desc.name
       ... path/.desc..name.moderate
           Property description of directories or files, not moderated or moderated.

       Note: The path components ("name" above) are encoded to the format suitable to physical
       filesystem.  Such conversion will be hidden behind object methods.

SEE ALSO

       Sympa::List, "qdecode_filename" in Sympa::Tools::Text, "qencode_filename" in
       Sympa::Tools::Text.

HISTORY

       SharedDocument module appeared on Sympa 5.2b.2.

       Rewritten Sympa::SharedDocument began to provide OO interface on Sympa 6.2.17.

       It was renamed to Sympa::WWW::SharedDocument on Sympa 6.2.26.