.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sympa::WWW::SharedDocument 3Sympa"
.TH Sympa::WWW::SharedDocument 3Sympa "2020-12-30" "6.2.58" "sympa 6.2.58"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sympa::WWW::SharedDocument \- Shared document repository and its nodes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Sympa::WWW::SharedDocument;
\&  
\&  $shared = Sympa::WWW::SharedDocument\->new($list, $path);
\&  
\&  %access = $shared\->get_privileges(\*(Aqread\*(Aq, $email, \*(Aqmd5\*(Aq, {...});
\&  @children = $shared\->get_children;
\&  $parent = $shared\->{parent};
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Sympa::WWW::SharedDocument implements shared document repository of lists.
.SS "Methods"
.IX Subsection "Methods"
.ie n .IP "new ( $list, [ $path, [ allow_empty => 1 ] ] )" 4
.el .IP "new ( \f(CW$list\fR, [ \f(CW$path\fR, [ allow_empty => 1 ] ] )" 4
.IX Item "new ( $list, [ $path, [ allow_empty => 1 ] ] )"
\&\fIConstructor\fR.
Creates new instance.
.Sp
Parameters:
.RS 4
.ie n .IP "$list" 4
.el .IP "\f(CW$list\fR" 4
.IX Item "$list"
A Sympa::List instance.
.ie n .IP "$path" 4
.el .IP "\f(CW$path\fR" 4
.IX Item "$path"
String to determine path or arrayref of path components.
The path is relative to repository root.
.IP "allow_empty => 1" 4
.IX Item "allow_empty => 1"
Don't omit files with zero size.
.RE
.RS 4
.Sp
Returns:
.Sp
If \f(CW$path\fR is empty or not specified, returns new instance of repository root;
{status} attribute will be set.
If \f(CW$path\fR is not empty and the path exists, returns new instance of node.
Otherwise returns false value.
.RE
.IP "as_hashref ( )" 4
.IX Item "as_hashref ( )"
\&\fIInstance method\fR.
Casts the instance to hashref.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
A hashref including attributes of instance (see \*(L"Attributes\*(R")
and following special items:
.RS 4
.IP "{ancestors}" 4
.IX Item "{ancestors}"
Arrayref of hashrefs including some attributes of all ancestor nodes.
.IP "{context}" 4
.IX Item "{context}"
Hashref including name and host of the list.
.IP "{date}" 4
.IX Item "{date}"
Localized form of {date_epoch}.
.IP "{parent}" 4
.IX Item "{parent}"
Hashref including attributes of parent node recursively.
.IP "{paths_d}" 4
.IX Item "{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 \fBjoin()\fR should be followed by
additional \*(L"/\*(R" character.
.RE
.RS 4
.RE
.IP "count_children ( )" 4
.IX Item "count_children ( )"
\&\fIInstance method\fR.
Returns number of child nodes.
.IP "count_moderated_descendants ( )" 4
.IX Item "count_moderated_descendants ( )"
\&\fIInstance method\fR.
Returns number of nodes waiting for moderation.
.ie n .IP "create_child ( $name, owner => $email, scenario => $scenario, type => $type, [ content => $content ] )" 4
.el .IP "create_child ( \f(CW$name\fR, owner => \f(CW$email\fR, scenario => \f(CW$scenario\fR, type => \f(CW$type\fR, [ content => \f(CW$content\fR ] )" 4
.IX Item "create_child ( $name, owner => $email, scenario => $scenario, type => $type, [ content => $content ] )"
\&\fIInstance method\fR.
Creates child node and returns it.
\&\s-1TBD.\s0
.ie n .IP "get_children ( [ moderate => boolean ], [ name => $name ], [ order_by => $order ], [ owner => $email ], [ allow_empty => 1 ] )" 4
.el .IP "get_children ( [ moderate => boolean ], [ name => \f(CW$name\fR ], [ order_by => \f(CW$order\fR ], [ owner => \f(CW$email\fR ], [ allow_empty => 1 ] )" 4
.IX Item "get_children ( [ moderate => boolean ], [ name => $name ], [ order_by => $order ], [ owner => $email ], [ allow_empty => 1 ] )"
\&\fIInstance method\fR.
Gets child nodes.
.Sp
Parameters:
.RS 4
.IP "moderate => boolean" 4
.IX Item "moderate => boolean"
.PD 0
.ie n .IP "name => $name" 4
.el .IP "name => \f(CW$name\fR" 4
.IX Item "name => $name"
.ie n .IP "owner => $email" 4
.el .IP "owner => \f(CW$email\fR" 4
.IX Item "owner => $email"
.PD
Filters results.
.ie n .IP "order_by => $order" 4
.el .IP "order_by => \f(CW$order\fR" 4
.IX Item "order_by => $order"
Sorts results.
\&\f(CW$order\fR may be one of
\&\f(CW\*(Aqorder_by_doc\*(Aq\fR (by name of nodes),
\&\f(CW\*(Aqorder_by_author\*(Aq\fR (by owner),
\&\f(CW\*(Aqorder_by_size\*(Aq\fR (by size),
\&\f(CW\*(Aqorder_by_date\*(Aq\fR (by modification time).
Default is ordering by names.
.IP "allow_empty => 1" 4
.IX Item "allow_empty => 1"
Don't omit nodes with zero size.
.RE
.RS 4
.Sp
Returns:
.Sp
(Possibly empty) list of child nodes.
.RE
.IP "get_moderated_descendants ( )" 4
.IX Item "get_moderated_descendants ( )"
\&\fIInstance method\fR.
Returns the list of nodes waiting for moderation.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
In array context, a list of nodes.
In scalar context, an arrayref of them.
.ie n .IP "get_privileges ( mode => $mode, sender => $sender, auth_method => $auth_method, scenario_context => $scenario_context )" 4
.el .IP "get_privileges ( mode => \f(CW$mode\fR, sender => \f(CW$sender\fR, auth_method => \f(CW$auth_method\fR, scenario_context => \f(CW$scenario_context\fR )" 4
.IX Item "get_privileges ( mode => $mode, sender => $sender, auth_method => $auth_method, scenario_context => $scenario_context )"
\&\fIInstance method\fR.
Gets privileges of a user on the node.
.Sp
\&\s-1TBD.\s0
.IP "get_size ( )" 4
.IX Item "get_size ( )"
\&\fIInstance method\fR.
Gets total size under current node.
.IP "install ( )" 4
.IX Item "install ( )"
\&\fIInstance method\fR.
Approves (install) file if it was held for moderation.
.Sp
Returns:
.Sp
True value.
If installation failed, returns false value and sets \f(CW$ERRNO\fR ($!).
.ie n .IP "rename ( $new_name )" 4
.el .IP "rename ( \f(CW$new_name\fR )" 4
.IX Item "rename ( $new_name )"
\&\fIInstance method\fR.
Renames file or directory.
.Sp
Parameters:
.RS 4
.ie n .IP "$new_name" 4
.el .IP "\f(CW$new_name\fR" 4
.IX Item "$new_name"
The name to be renamed to.
.RE
.RS 4
.Sp
Returns:
.Sp
True value.
If renaming failed, returns false value and sets \f(CW$ERRNO\fR ($!).
.RE
.IP "rmdir ( )" 4
.IX Item "rmdir ( )"
\&\fIinstance method\fR.
Removes directory from repository.
Directory must be empty.
.Sp
Returns:
.Sp
True value.
If removal failed, returns false value and sets \f(CW$ERRNO\fR ($!).
.IP "save_description ( )" 4
.IX Item "save_description ( )"
\&\fIInstance method\fR.
Creates or updates property description of the node.
.IP "unlink ( )" 4
.IX Item "unlink ( )"
\&\fIinstance method\fR.
Removes file from repository.
.Sp
Returns:
.Sp
True value.
If removal failed, returns false value and sets \f(CW$ERRNO\fR ($!).
.IP "get_id ( )" 4
.IX Item "get_id ( )"
\&\fIInstance method\fR.
Returns unique identifier of instance.
.PP
\fIMethods for repository root\fR
.IX Subsection "Methods for repository root"
.IP "create ( )" 4
.IX Item "create ( )"
\&\fIInstance method\fR.
Creates document repository on physical filesystem.
.IP "delete ( )" 4
.IX Item "delete ( )"
\&\fIInstance method\fR.
Deletes document repository.
.IP "restore ( )" 4
.IX Item "restore ( )"
\&\fIInstance method\fR.
Restores deleted document repository.
.SS "Functions"
.IX Subsection "Functions"
.ie n .IP "valid_name ( $new_name )" 4
.el .IP "valid_name ( \f(CW$new_name\fR )" 4
.IX Item "valid_name ( $new_name )"
\&\fIFunction\fR.
Check if the name is allowed for directory and file.
.Sp
Note:
This should be used with name of newly created node.
Existing files and directories may have the name not allowed by this function.
.SS "Attributes"
.IX Subsection "Attributes"
Instance of Sympa::WWW::SharedDocument may have following attributes.
.IP "{context}" 4
.IX Item "{context}"
\&\fIMandatory\fR.
Instance of Sympa::List class the shared document repository belongs to.
.IP "{date_epoch}" 4
.IX Item "{date_epoch}"
\&\fIMandatory\fR.
Modification time of node in Unix time.
.IP "{file_extension}" 4
.IX Item "{file_extension}"
File extension if any.
.IP "{fs_name}" 4
.IX Item "{fs_name}"
\&\fIMandatory\fR.
Name of node on physical filesystem,
i.e. the last part of {fs_path}.
.IP "{fs_path}" 4
.IX Item "{fs_path}"
\&\fIMandatory\fR.
Full path of node on physical filesystem.
.IP "{html}" 4
.IX Item "{html}"
Only in \s-1HTML\s0 file.
True value will be set.
.IP "{icon}" 4
.IX Item "{icon}"
\&\s-1URL\s0 to icon.
.IP "{label}" 4
.IX Item "{label}"
Only in bookmark file.
Label to be shown in hyperlink.
.IP "{mime_type}" 4
.IX Item "{mime_type}"
Only in regular file.
\&\s-1MIME\s0 content type of the file if it is known.
.IP "{moderate}" 4
.IX Item "{moderate}"
Set if node is held for moderation.
.IP "{name}" 4
.IX Item "{name}"
\&\fIMandatory\fR.
Name of node accessible by users,
i.e. the last item of {paths}.
.IP "{owner}" 4
.IX Item "{owner}"
Owner (author) of node,
given by property description.
.IP "{parent}" 4
.IX Item "{parent}"
Parent node if any.  Sympa::WWW::SharedDocument instance.
.IP "{paths}" 4
.IX Item "{paths}"
\&\fIMandatory\fR.
Arrayref to all path components of node accessible by users.
.IP "{scenario}{read}" 4
.IX Item "{scenario}{read}"
.PD 0
.IP "{scenario}{edit}" 4
.IX Item "{scenario}{edit}"
.PD
Scenario names to define privileges.
These may be given by property description.
.IP "{serial_desc}" 4
.IX Item "{serial_desc}"
Modification time of property description in Unix time.
Available if property description exists.
.IP "{size}" 4
.IX Item "{size}"
Size of file.
.IP "{status}" 4
.IX Item "{status}"
\&\fIOnly in repository root\fR.
Status of repository:
\&\f(CW\*(Aqexist\*(Aq\fR, \f(CW\*(Aqdeleted\*(Aq\fR or \f(CW\*(Aqnone\*(Aq\fR.
.IP "{title}" 4
.IX Item "{title}"
Description of node,
given by property description.
.IP "{type}" 4
.IX Item "{type}"
\&\fIMandatory\fR.
Type of node.
\&\f(CW\*(Aqroot\*(Aq\fR (the root of repository), \f(CW\*(Aqdirectory\*(Aq\fR (directory), \f(CW\*(Aqurl\*(Aq\fR
(bookmark file) or \f(CW\*(Aqfile\*(Aq\fR (other file).
.IP "{url}" 4
.IX Item "{url}"
Only in bookmark file.
\&\s-1URL\s0 to be linked.
.SH "FILES"
.IX Header "FILES"
.IP "\fIlist home\fR/shared/" 4
.IX Item "list home/shared/"
Root of repository.
.IP "\fI... path\fR/\fIname\fR" 4
.IX Item "... path/name"
Directory or file.
.IP "\fI... path\fR/.\fIname\fR.moderate" 4
.IX Item "... path/.name.moderate"
Moderated directory or file.
.IP "\fI... path\fR/\fIname\fR/.desc" 4
.IX Item "... path/name/.desc"
.PD 0
.IP "\fI... path\fR/.desc.\fIname\fR" 4
.IX Item "... path/.desc.name"
.IP "\fI... path\fR/.desc..\fIname\fR.moderate" 4
.IX Item "... path/.desc..name.moderate"
.PD
Property description of directories or files, not moderated or moderated.
.PP
Note:
The path components ("\fIname\fR" above) are encoded to the format suitable to
physical filesystem.
Such conversion will be hidden behind object methods.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sympa::List,
\&\*(L"qdecode_filename\*(R" in Sympa::Tools::Text,
\&\*(L"qencode_filename\*(R" in Sympa::Tools::Text.
.SH "HISTORY"
.IX Header "HISTORY"
SharedDocument module appeared on Sympa 5.2b.2.
.PP
Rewritten Sympa::SharedDocument began to provide \s-1OO\s0 interface on
Sympa 6.2.17.
.PP
It was renamed to Sympa::WWW::SharedDocument on Sympa 6.2.26.