1Hash::DefHash(3) User Contributed Perl Documentation Hash::DefHash(3)
2
6 Hash::DefHash - Manipulate defhash
7
9 This document describes version 0.072 of Hash::DefHash (from Perl
10 distribution Hash-DefHash), released on 2021-07-21.
11
13 use Hash::DefHash; # imports defhash()
14 # create a new defhash object, die when hash is invalid defhash
16 $dh = Hash::DefHash->new; # creates an empty defhash
17 $dh = Hash::DefHash->new({a=>1}); # use the hashref
18 $dh = Hash::DefHash->new({"contains space"=>1}); # dies!
19 # defhash() is a synonym for Hash::DefHash->new().
21 $dh = defhash({foo=>1});
22 # return the original hash
24 $hash = $dh->hash;
25 # list properties
27 @props = $dh->props;
28 # list property names, values, and attributes, will return ($prop => $attrs,
30 # ...). Property values will be put in $attrs with key "". For example:
31 %content = DefHash::Hash->new({p1=>1, "p1.a"=>2, p2=>3})->contents;
32 # => (p1 => {""=>1, a=>2}, p2=>3)
33 # get property value, will die if property does not exist
35 $propval = $dh->prop($prop);
36 # like prop(), but will return undef if property does not exist
38 $propval = $dh->get_prop($prop);
39 # check whether property exists
41 say "exists" if $dh->prop_exists($prop);
42 # add a new property, will die if property already exists
44 $dh->add_prop($prop, $propval);
45 # add new property, or set value for existing property
47 $oldpropval = $dh->set_prop($prop, $propval);
48 # delete property, noop if property already does not exist. set $delattrs to
50 # true to delete all property's attributes.
51 $oldpropval = $dh->del_prop($prop, $delattrs);
52 # delete all properties, set $delattrs to true to delete all properties's
54 # attributes too.
55 $dh->del_all_props($delattrs);
56 # get property's attributes. to list defhash attributes, set $prop to undef or
58 # ""
59 %attrs = $dh->attrs($prop);
60 # get attribute value, will die if attribute does not exist
62 $attrval = $dh->attr($prop, $attr);
63 # like attr(), but will return undef if attribute does not exist
65 $attrval = $dh->get_attr($prop, $attr);
66 # check whether an attribute exists
68 @attrs = $dh->attr_exists($prop, $attr);
69 # add attribute to a property, will die if attribute already exists
71 $dh->add_attr($prop, $attr, $attrval);
72 # add attribute to a property, or set value of existing attribute
74 $oldatrrval = $dh->set_attr($prop, $attr, $attrval);
75 # delete property's attribute, noop if attribute already does not exist
77 $oldattrval = $dh->del_attr($prop, $attr, $attrval);
78 # delete all attributes of a property
80 $dh->del_all_attrs($prop);
81 # get predefined properties
83 say $dh->v; # shortcut for $dh->get_prop('v')
84 say $dh->default_lang; # shortcut for $dh->get_prop('default_lang')
85 say $dh->name; # shortcut for $dh->get_prop('name')
86 say $dh->summary; # shortcut for $dh->get_prop('summary')
87 say $dh->description; # shortcut for $dh->get_prop('description')
88 say $dh->tags; # shortcut for $dh->get_prop('tags')
89 # get value in alternate languages
91 $propval = $dh->get_prop_lang($prop, $lang);
92 # get value in all available languages, result is a hash mapping lang => val
94 %vals = $dh->get_prop_all_langs($prop);
95 # set value for alternative language
97 $oldpropval = $dh->set_prop_lang($prop, $lang, $propval);
98
100 Steven Haryanto <sharyanto@cpan.org>
101
103 defhash([ $hash ]) => OBJ
104 Shortcut for "Hash::DefHash->new($hash)". As a bonus, can also detect
105 if $hash is already a defhash and returns it immediately instead of
106 wrapping it again. Exported by default.
107
109 new
110 Usage:
111 $dh = Hash::DefHash->new([ $hash ],[ %opts ]);
113 Constructor. Create a new Hash::DefHash object, which is a thin OO skin
115 over the regular Perl hash. If $hash is not specified, a new anonymous
116 hash is created.
117 Internally, the object contains a hash reference which contains
119 reference to the hash ("bless({hash=>$orig_hash, ...},
120 'Hash::DefHash')"). It does not create a copy of the hash or bless the
121 hash directly. Be careful not to assume that the two are the same!
122 Will check the keys of hash for invalid properties/attributes and will
124 die if one is found, e.g..
125 $dh = Hash::DefHash->new({"contains space" => 1}); # dies!
127 Known options:
129 • check => BOOL (default: 1)
131 Whether to check that hash is a valid defhash. Will die if hash
133 turns out to contain invalid keys/values.
134 • parent => HASH/DEFHASH_OBJ
136 Set defhash's parent. Default language ("default_lang") will follow
138 parent's if unset in the current hash.
139 hash
141 Usage:
142 $hashref = $dh->hash;
144 Return the original hashref.
146 check
148 Usage:
149 $dh->check;
151 contents
153 Usage:
154 my %contents = $dh->contents;
156 default_lang
158 Usage:
159 $default_lang = $dh->default_lang;
161 props
163 Usage:
164 @props = $dh->props;
166 Return list of properties. Will ignore properties that begin with
168 underscore, e.g.:
169 $dh = defhash({a=>1, _b=>2});
171 $dh->props;
172 prop
174 Usage:
175 $val = $dh->prop($prop [ , \%opts ]);
177 Get property value, will die if property does not exist.
179 Known options:
181 • die
183 Bool. Default true. Whether to die when requested property is not
185 found.
186 • alt
188 Hashref.
190 • mark_different_lang
192 Bool. Default false. If set to true, then when a requested property
194 is found but differs (only) in the language it will be returned but
195 with a mark. For example, with this defhash:
196 {name=>"Chair", "name.alt.lang.id_ID"=>"Kursi"}
198 then:
200 $dh->prop("name", {lang=>"fr_FR"});
202 will die. But:
204 $dh->prop("name", {lang=>"fr_FR", mark_different_lang=>1});
206 will return:
208 "{en_US Chair}"
210 or:
212 "{id_ID Kursi}"
214 get_prop
216 Usage:
217 my $val = $dh->get_prop($prop [ , \%opts ]);
219 Like "prop"(), but will return undef if property does not exist.
221 prop_exists
223 Usage:
224 $exists = $dh->prop_exists;
226 add_prop
228 set_prop
229 del_prop
230 del_all_props
231 attrs
232 attr
233 get_attr
234 attr_exists
235 add_attr
236 set_attr
237 del_attr
238 del_all_attrs
239 defhash_v
240 v
241 name
242 summary
243 description
244 tags
245 get_prop_lang
246 Usage:
247 my $val = $dh->get_prop_lang($prop, $lang [ , \%opts ]);
249 This is just a special case for:
251 $dh->prop($prop, {alt=>{lang=>$lang}, mark_different_lang=>1, %opts});
253 get_prop_all_langs
255 set_prop_lang
257 Please visit the project's homepage at
258 <https://metacpan.org/release/Hash-DefHash>.
259
261 Source repository is at
262 <https://github.com/perlancar/perl-Hash-DefHash>.
263
265 Please report any bugs or feature requests on the bugtracker website
266 <https://rt.cpan.org/Public/Dist/Display.html?Name=Hash-DefHash>
267 When submitting a bug or request, please include a test-file or a patch
269 to an existing test-file that illustrates the bug or desired feature.
270
272 DefHash specification
273
275 perlancar <perlancar@cpan.org>
276
278 This software is copyright (c) 2021, 2020, 2018, 2016, 2015, 2014, 2012
279 by perlancar@cpan.org.
280 This is free software; you can redistribute it and/or modify it under
282 the same terms as the Perl 5 programming language system itself.
283perl v5.38.0 2023-07-20 Hash::DefHash(3)