Provided by: sympa_6.2.70~dfsg-2_amd64 
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.
6.2.70 2023-01-26 Sympa::WWW::SharedDocument(3Sympa)