Sympa::WWW::SharedDocument(3Sympa)

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.