Sympa::WWW::SharedDocument.3Sympa - Man Page

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.

Info

2021-03-02 sympa 6.2.60