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.