--- name: "Hash::DefHash" section: "3pm" platform: "linux" package: "libhash-defhash-perl" version: "0.072-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Hash::DefHash" --- # Hash::DefHash(3pm) Manipulate defhash ## NAME Hash::DefHash - Manipulate defhash ## VERSION This document describes version 0.072 of Hash::DefHash (from Perl distribution Hash-DefHash), released on 2021-07-21. ## SYNOPSIS ``` 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's attributes. $oldpropval = $dh->del_prop($prop, $delattrs); # delete all properties, set $delattrs to true to delete all properties's # attributes too. $dh->del_all_props($delattrs); # get property's 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's 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('v') say $dh->default_lang; # shortcut for $dh->get_prop('default_lang') say $dh->name; # shortcut for $dh->get_prop('name') say $dh->summary; # shortcut for $dh->get_prop('summary') say $dh->description; # shortcut for $dh->get_prop('description') say $dh->tags; # shortcut for $dh->get_prop('tags') # 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); ``` ## CONTRIBUTOR Steven Haryanto \ ## FUNCTIONS ### defhash(\[ $hash \]) =\> OBJ Shortcut for `"Hash::DefHash->new($hash)"`. As a bonus, can also detect if `$hash` is already a defhash and returns it immediately instead of wrapping it again. Exported by default. ## METHODS ### new Usage: ``` $dh = Hash::DefHash->new([ $hash ],[ %opts ]); ``` Constructor. Create a new Hash::DefHash object, which is a thin OO skin over the regular Perl hash. If `$hash` is not specified, a new anonymous hash is created. Internally, the object contains a hash reference which contains reference to the hash (`"bless({hash=>$orig_hash, ...}, 'Hash::DefHash')"`). 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! Will check the keys of hash for invalid properties/attributes and will die if one is found, e.g.. ``` $dh = Hash::DefHash->new({"contains space" => 1}); # dies! ``` Known options: - • check =\> BOOL (default: 1) Whether to check that hash is a valid defhash. Will die if hash turns out to contain invalid keys/values. - • parent =\> HASH/DEFHASH\_OBJ Set defhash's parent. Default language (`"default_lang"`) will follow parent's if unset in the current hash. ### hash Usage: ``` $hashref = $dh->hash; ``` Return the original hashref. ### check Usage: ``` $dh->check; ``` ### contents Usage: ``` my %contents = $dh->contents; ``` ### default\_lang Usage: ``` $default_lang = $dh->default_lang; ``` ### props Usage: ``` @props = $dh->props; ``` Return list of properties. Will ignore properties that begin with underscore, e.g.: ``` $dh = defhash({a=>1, _b=>2}); $dh->props; ``` ### prop Usage: ``` $val = $dh->prop($prop [ , \%opts ]); ``` Get property value, will die if property does not exist. Known options: - • die Bool. Default true. Whether to die when requested property is not found. - • alt Hashref. - • mark\_different\_lang 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: ``` {name=>"Chair", "name.alt.lang.id_ID"=>"Kursi"} ``` then: ``` $dh->prop("name", {lang=>"fr_FR"}); ``` will die. But: ``` $dh->prop("name", {lang=>"fr_FR", mark_different_lang=>1}); ``` will return: ``` "{en_US Chair}" ``` or: ``` "{id_ID Kursi}" ``` ### get\_prop Usage: ``` my $val = $dh->get_prop($prop [ , \%opts ]); ``` Like "prop"(), but will return undef if property does not exist. ### prop\_exists Usage: ``` $exists = $dh->prop_exists; ``` ### add\_prop ### set\_prop ### del\_prop ### del\_all\_props ### attrs ### attr ### get\_attr ### attr\_exists ### add\_attr ### set\_attr ### del\_attr ### del\_all\_attrs ### defhash\_v ### v ### name ### summary ### description ### tags ### get\_prop\_lang Usage: ``` my $val = $dh->get_prop_lang($prop, $lang [ , \%opts ]); ``` This is just a special case for: ``` $dh->prop($prop, {alt=>{lang=>$lang}, mark_different_lang=>1, %opts}); ``` ### get\_prop\_all\_langs ### set\_prop\_lang ## HOMEPAGE Please visit the project's homepage at \. ## SOURCE Source repository is at \. ## BUGS Please report any bugs or feature requests on the bugtracker website \ 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. ## SEE ALSO DefHash specification ## AUTHOR perlancar \ ## COPYRIGHT AND LICENSE This software is copyright (c) 2021, 2020, 2018, 2016, 2015, 2014, 2012 by perlancar@cpan.org. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.