.\" 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
.\" ========================================================================
.\"
.IX Title "Hash::DefHash 3pm"
.TH Hash::DefHash 3pm "2021-09-29" "perl v5.32.1" "User Contributed Perl Documentation"
.\" 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"
Hash::DefHash \- Manipulate defhash
.SH "VERSION"
.IX Header "VERSION"
This document describes version 0.072 of Hash::DefHash (from Perl distribution Hash-DefHash), released on 2021\-07\-21.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Hash::DefHash; # imports defhash()
\&
\& # create a new defhash object, die when hash is invalid defhash
\& $dh = Hash::DefHash\->new;                        # creates an empty defhash
\& $dh = Hash::DefHash\->new({a=>1});                # use the hashref
\& $dh = Hash::DefHash\->new({"contains space"=>1}); # dies!
\&
\& # defhash() is a synonym for Hash::DefHash\->new().
\& $dh = defhash({foo=>1});
\&
\& # return the original hash
\& $hash = $dh\->hash;
\&
\& # list properties
\& @props = $dh\->props;
\&
\& # list property names, values, and attributes, will return ($prop => $attrs,
\& # ...). Property values will be put in $attrs with key "". For example:
\& %content = DefHash::Hash\->new({p1=>1, "p1.a"=>2, p2=>3})\->contents;
\& # => (p1 => {""=>1, a=>2}, p2=>3)
\&
\& # get property value, will die if property does not exist
\& $propval = $dh\->prop($prop);
\&
\& # like prop(), but will return undef if property does not exist
\& $propval = $dh\->get_prop($prop);
\&
\& # check whether property exists
\& say "exists" if $dh\->prop_exists($prop);
\&
\& # add a new property, will die if property already exists
\& $dh\->add_prop($prop, $propval);
\&
\& # add new property, or set value for existing property
\& $oldpropval = $dh\->set_prop($prop, $propval);
\&
\& # delete property, noop if property already does not exist. set $delattrs to
\& # true to delete all property\*(Aqs attributes.
\& $oldpropval = $dh\->del_prop($prop, $delattrs);
\&
\& # delete all properties, set $delattrs to true to delete all properties\*(Aqs
\& # attributes too.
\& $dh\->del_all_props($delattrs);
\&
\& # get property\*(Aqs attributes. to list defhash attributes, set $prop to undef or
\& # ""
\& %attrs = $dh\->attrs($prop);
\&
\& # get attribute value, will die if attribute does not exist
\& $attrval = $dh\->attr($prop, $attr);
\&
\& # like attr(), but will return undef if attribute does not exist
\& $attrval = $dh\->get_attr($prop, $attr);
\&
\& # check whether an attribute exists
\& @attrs = $dh\->attr_exists($prop, $attr);
\&
\& # add attribute to a property, will die if attribute already exists
\& $dh\->add_attr($prop, $attr, $attrval);
\&
\& # add attribute to a property, or set value of existing attribute
\& $oldatrrval = $dh\->set_attr($prop, $attr, $attrval);
\&
\& # delete property\*(Aqs attribute, noop if attribute already does not exist
\& $oldattrval = $dh\->del_attr($prop, $attr, $attrval);
\&
\& # delete all attributes of a property
\& $dh\->del_all_attrs($prop);
\&
\& # get predefined properties
\& say $dh\->v;            # shortcut for $dh\->get_prop(\*(Aqv\*(Aq)
\& say $dh\->default_lang; # shortcut for $dh\->get_prop(\*(Aqdefault_lang\*(Aq)
\& say $dh\->name;         # shortcut for $dh\->get_prop(\*(Aqname\*(Aq)
\& say $dh\->summary;      # shortcut for $dh\->get_prop(\*(Aqsummary\*(Aq)
\& say $dh\->description;  # shortcut for $dh\->get_prop(\*(Aqdescription\*(Aq)
\& say $dh\->tags;         # shortcut for $dh\->get_prop(\*(Aqtags\*(Aq)
\&
\& # get value in alternate languages
\& $propval = $dh\->get_prop_lang($prop, $lang);
\&
\& # get value in all available languages, result is a hash mapping lang => val
\& %vals = $dh\->get_prop_all_langs($prop);
\&
\& # set value for alternative language
\& $oldpropval = $dh\->set_prop_lang($prop, $lang, $propval);
.Ve
.SH "CONTRIBUTOR"
.IX Header "CONTRIBUTOR"
Steven Haryanto <sharyanto@cpan.org>
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "defhash([ $hash ]) => \s-1OBJ\s0"
.el .SS "defhash([ \f(CW$hash\fP ]) => \s-1OBJ\s0"
.IX Subsection "defhash([ $hash ]) => OBJ"
Shortcut for \f(CW\*(C`Hash::DefHash\->new($hash)\*(C'\fR. As a bonus, can also detect if
\&\f(CW$hash\fR is already a defhash and returns it immediately instead of wrapping it
again. Exported by default.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Usage:
.PP
.Vb 1
\& $dh = Hash::DefHash\->new([ $hash ],[ %opts ]);
.Ve
.PP
Constructor. Create a new Hash::DefHash object, which is a thin \s-1OO\s0 skin over the
regular Perl hash. If \f(CW$hash\fR is not specified, a new anonymous hash is
created.
.PP
Internally, the object contains a hash reference which contains reference to the
hash (\f(CW\*(C`bless({hash=>$orig_hash, ...}, \*(AqHash::DefHash\*(Aq)\*(C'\fR). It does not
create a copy of the hash or bless the hash directly. Be careful not to assume
that the two are the same!
.PP
Will check the keys of hash for invalid properties/attributes and will die if
one is found, e.g..
.PP
.Vb 1
\& $dh = Hash::DefHash\->new({"contains space" => 1}); # dies!
.Ve
.PP
Known options:
.IP "\(bu" 4
check => \s-1BOOL\s0 (default: 1)
.Sp
Whether to check that hash is a valid defhash. Will die if hash turns out to
contain invalid keys/values.
.IP "\(bu" 4
parent => \s-1HASH/DEFHASH_OBJ\s0
.Sp
Set defhash's parent. Default language (\f(CW\*(C`default_lang\*(C'\fR) will follow parent's if
unset in the current hash.
.SS "hash"
.IX Subsection "hash"
Usage:
.PP
.Vb 1
\& $hashref = $dh\->hash;
.Ve
.PP
Return the original hashref.
.SS "check"
.IX Subsection "check"
Usage:
.PP
.Vb 1
\& $dh\->check;
.Ve
.SS "contents"
.IX Subsection "contents"
Usage:
.PP
.Vb 1
\& my %contents = $dh\->contents;
.Ve
.SS "default_lang"
.IX Subsection "default_lang"
Usage:
.PP
.Vb 1
\& $default_lang = $dh\->default_lang;
.Ve
.SS "props"
.IX Subsection "props"
Usage:
.PP
.Vb 1
\& @props = $dh\->props;
.Ve
.PP
Return list of properties. Will ignore properties that begin with underscore,
e.g.:
.PP
.Vb 2
\& $dh = defhash({a=>1, _b=>2});
\& $dh\->props;
.Ve
.SS "prop"
.IX Subsection "prop"
Usage:
.PP
.Vb 1
\& $val = $dh\->prop($prop [ , \e%opts ]);
.Ve
.PP
Get property value, will die if property does not exist.
.PP
Known options:
.IP "\(bu" 4
die
.Sp
Bool. Default true. Whether to die when requested property is not found.
.IP "\(bu" 4
alt
.Sp
Hashref.
.IP "\(bu" 4
mark_different_lang
.Sp
Bool. Default false. If set to true, then when a requested property is found but
differs (only) in the language it will be returned but with a mark. For example,
with this defhash:
.Sp
.Vb 1
\& {name=>"Chair", "name.alt.lang.id_ID"=>"Kursi"}
.Ve
.Sp
then:
.Sp
.Vb 1
\& $dh\->prop("name", {lang=>"fr_FR"});
.Ve
.Sp
will die. But:
.Sp
.Vb 1
\& $dh\->prop("name", {lang=>"fr_FR", mark_different_lang=>1});
.Ve
.Sp
will return:
.Sp
.Vb 1
\& "{en_US Chair}"
.Ve
.Sp
or:
.Sp
.Vb 1
\& "{id_ID Kursi}"
.Ve
.SS "get_prop"
.IX Subsection "get_prop"
Usage:
.PP
.Vb 1
\& my $val = $dh\->get_prop($prop [ , \e%opts ]);
.Ve
.PP
Like \*(L"prop\*(R"(), but will return undef if property does not exist.
.SS "prop_exists"
.IX Subsection "prop_exists"
Usage:
.PP
.Vb 1
\& $exists = $dh\->prop_exists;
.Ve
.SS "add_prop"
.IX Subsection "add_prop"
.SS "set_prop"
.IX Subsection "set_prop"
.SS "del_prop"
.IX Subsection "del_prop"
.SS "del_all_props"
.IX Subsection "del_all_props"
.SS "attrs"
.IX Subsection "attrs"
.SS "attr"
.IX Subsection "attr"
.SS "get_attr"
.IX Subsection "get_attr"
.SS "attr_exists"
.IX Subsection "attr_exists"
.SS "add_attr"
.IX Subsection "add_attr"
.SS "set_attr"
.IX Subsection "set_attr"
.SS "del_attr"
.IX Subsection "del_attr"
.SS "del_all_attrs"
.IX Subsection "del_all_attrs"
.SS "defhash_v"
.IX Subsection "defhash_v"
.SS "v"
.IX Subsection "v"
.SS "name"
.IX Subsection "name"
.SS "summary"
.IX Subsection "summary"
.SS "description"
.IX Subsection "description"
.SS "tags"
.IX Subsection "tags"
.SS "get_prop_lang"
.IX Subsection "get_prop_lang"
Usage:
.PP
.Vb 1
\& my $val = $dh\->get_prop_lang($prop, $lang [ , \e%opts ]);
.Ve
.PP
This is just a special case for:
.PP
.Vb 1
\& $dh\->prop($prop, {alt=>{lang=>$lang}, mark_different_lang=>1, %opts});
.Ve
.SS "get_prop_all_langs"
.IX Subsection "get_prop_all_langs"
.SS "set_prop_lang"
.IX Subsection "set_prop_lang"
.SH "HOMEPAGE"
.IX Header "HOMEPAGE"
Please visit the project's homepage at <https://metacpan.org/release/Hash\-DefHash>.
.SH "SOURCE"
.IX Header "SOURCE"
Source repository is at <https://github.com/perlancar/perl\-Hash\-DefHash>.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Hash\-DefHash>
.PP
When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DefHash specification
.SH "AUTHOR"
.IX Header "AUTHOR"
perlancar <perlancar@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2021, 2020, 2018, 2016, 2015, 2014, 2012 by perlancar@cpan.org.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.