SYMPA::WWW::SHAREDDOCUMENT(3Sympa)

💖 Sympa::WWW::SharedDocument(3Sympa) 💖

okay bestie, welcome to the manual page for Sympa::WWW::SharedDocument — aka Shared document repository and its nodes ✨. This is from the sympa 6.2.80 era, and it's genuinely one of the cutest little OO modules out there, no cap.

---

🌸 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. that's the whole vibe. it's giving "your list's shared docs, fully object-oriented" 💅

---

🎀 Methods 🎀

new ( $list, [ $path, [ allow_empty => 1 ] ] )

Constructor. Creates new instance. iconic behavior honestly.

Parameters, bestie:

• $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. (zero-byte files deserve love too 🥺)

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. literally the ✨glow-up✨ into a plain hash.

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. (they're in time-out 🫶)

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. collecting the whole friend group 👑

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. (context matters, iykyk ✨)

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. freeing it from mod jail 🔓

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. (no surprise evictions allowed, it has to be empty first 💀)

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. every instance is a main character with its own ID 💅

---

🧚 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. the comeback arc we deserved 🌈

---

👑 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. drink water, then read them all, bestie 💧

• {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. (the ✨magic✨ is behind the curtain, you don't have to think about it)

---

💜 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.

---

okay that's the whole thing, you ate that reading session fr fr 💅✨ this was sympa 6.2.80, dated 2026-10-19, and it's the Sympa::WWW::SharedDocument(3Sympa) page 🎀 go create some shared docs, bestie 🦋🫶