| Sympa::WWW::SharedDocument(3Sympa) | sympa 6.2.72 | 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.
| 2024-07-15 | 6.2.72 |