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.

The content of this page is automatically generated from the source distribution of Sympa. For details about this document see original source file.

Theme originally designed by orderedlist