Hash::DefHash(3pm)

💖 NAME 💖

Hash::DefHash — manipulate defhash. That's it, that's the whole vibe. It's the Hash::DefHash(3pm) page, bestie, and it's all about wrangling defhash objects. 🦋

---

🌸 VERSION 🌸

This doc is for version 0.072 of Hash::DefHash (from the Perl distribution Hash-DefHash), released on 2021-07-21. ✨

---

✨ SYNOPSIS ✨

okay so here's the whole thing in action, no cap:

 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 <sharyanto@cpan.org> — thank you for your service, king. 👑

---

🔥 FUNCTIONS 🔥

defhash([ $hash ]) => OBJ

Shortcut for Hash::DefHash->new($hash), periodt. And as a lil bonus ✨ it can also clock whether $hash is already a defhash and just hands it right back to you instead of wrapping it up all over again. Exported by default, so it's just there. 🎀

---

👑 METHODS 👑

new

Usage:

 $dh = Hash::DefHash->new([ $hash ],[ %opts ]);

Constructor, bestie. Makes a brand new Hash::DefHash object, which is honestly just a thin OO skin stretched over a regular Perl hash. If you don't pass $hash, a fresh anonymous hash gets created for you. 💅

Internally, the object holds a hash reference that itself holds a reference to your hash: bless({hash=>$orig_hash, ...}, 'Hash::DefHash'). It does not copy the hash, and it does not bless the hash directly. So please, do not assume those two are the same thing!! 🚨

It will check the keys of the hash for invalid properties/attributes and will die if it finds one, e.g.:

 $dh = Hash::DefHash->new({"contains space" => 1}); # dies!

Known options:

• check => BOOL (default: 1) — whether to check that the hash is a valid defhash. Will die if the hash turns out to contain invalid keys/values.
• parent => HASH/DEFHASH_OBJ — set the defhash's parent. Default language (default_lang) will follow the parent's if it's unset in the current hash. 🧚

hash

Usage:

 $hashref = $dh->hash;

Returns the original hashref. The real one. No copy. 🫶

check

Usage:

 $dh->check;

contents

Usage:

 my %contents = $dh->contents;

default_lang

Usage:

 $default_lang = $dh->default_lang;

props

Usage:

 @props = $dh->props;

Returns the list of properties. It will ignore properties that begin with an underscore, e.g.:

 $dh = defhash({a=>1, _b=>2});
 $dh->props;

(so _b is giving invisible. 🙈)

prop

Usage:

 $val = $dh->prop($prop [ , \%opts ]);

Get a property value — will die if the property does not exist. Dramatic, but fair. 💀

Known options:

• die — bool. Default true. Whether to die when the requested property is not found.
• alt — hashref.
• mark_different_lang — bool. Default false. If you set it to true, then when a requested property is found but differs (only) in the language, it will still 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 it returns undef if the property doesn't exist instead of yelling at you. Softer energy. 🌸

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

ngl bestie, that whole run of method names above (add_prop through tags, plus get_prop_all_langs and set_prop_lang) is listed exactly like that in the original — just names, no usage blocks attached. Not me hiding anything, that's genuinely all the doc says for those. 🫣

---

🌈 HOMEPAGE 🌈

Please visit the project's homepage at <https://metacpan.org/release/Hash-DefHash>.

---

🦋 SOURCE 🦋

Source repository is at <https://github.com/perlancar/perl-Hash-DefHash>.

---

🚨 BUGS 🚨

Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Hash-DefHash>

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. fr fr, a failing test is the whole love language here. 💖

---

👀 SEE ALSO 👀

DefHash specification

---

💜 AUTHOR 💜

perlancar <perlancar@cpan.org>

---

🎀 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. Slay. 💅

---

okay that's the whole page, we ate and left no crumbs ✨ — this was Hash::DefHash(3pm) from perl v5.32.1, dated 2021-09-29. bye bestie, go manipulate some defhashes responsibly. 🦋💖