1Hash::DefHash(3)      User Contributed Perl Documentation     Hash::DefHash(3)
2
3
4

NAME

6       Hash::DefHash - Manipulate defhash
7

VERSION

9       This document describes version 0.072 of Hash::DefHash (from Perl
10       distribution Hash-DefHash), released on 2021-07-21.
11

SYNOPSIS

13        use Hash::DefHash; # imports defhash()
14
15        # 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
20        # defhash() is a synonym for Hash::DefHash->new().
21        $dh = defhash({foo=>1});
22
23        # return the original hash
24        $hash = $dh->hash;
25
26        # list properties
27        @props = $dh->props;
28
29        # 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
34        # get property value, will die if property does not exist
35        $propval = $dh->prop($prop);
36
37        # like prop(), but will return undef if property does not exist
38        $propval = $dh->get_prop($prop);
39
40        # check whether property exists
41        say "exists" if $dh->prop_exists($prop);
42
43        # add a new property, will die if property already exists
44        $dh->add_prop($prop, $propval);
45
46        # add new property, or set value for existing property
47        $oldpropval = $dh->set_prop($prop, $propval);
48
49        # 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
53        # delete all properties, set $delattrs to true to delete all properties's
54        # attributes too.
55        $dh->del_all_props($delattrs);
56
57        # get property's attributes. to list defhash attributes, set $prop to undef or
58        # ""
59        %attrs = $dh->attrs($prop);
60
61        # get attribute value, will die if attribute does not exist
62        $attrval = $dh->attr($prop, $attr);
63
64        # like attr(), but will return undef if attribute does not exist
65        $attrval = $dh->get_attr($prop, $attr);
66
67        # check whether an attribute exists
68        @attrs = $dh->attr_exists($prop, $attr);
69
70        # add attribute to a property, will die if attribute already exists
71        $dh->add_attr($prop, $attr, $attrval);
72
73        # add attribute to a property, or set value of existing attribute
74        $oldatrrval = $dh->set_attr($prop, $attr, $attrval);
75
76        # delete property's attribute, noop if attribute already does not exist
77        $oldattrval = $dh->del_attr($prop, $attr, $attrval);
78
79        # delete all attributes of a property
80        $dh->del_all_attrs($prop);
81
82        # 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
90        # get value in alternate languages
91        $propval = $dh->get_prop_lang($prop, $lang);
92
93        # get value in all available languages, result is a hash mapping lang => val
94        %vals = $dh->get_prop_all_langs($prop);
95
96        # set value for alternative language
97        $oldpropval = $dh->set_prop_lang($prop, $lang, $propval);
98

CONTRIBUTOR

100       Steven Haryanto <sharyanto@cpan.org>
101

FUNCTIONS

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

METHODS

109   new
110       Usage:
111
112        $dh = Hash::DefHash->new([ $hash ],[ %opts ]);
113
114       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
118       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
123       Will check the keys of hash for invalid properties/attributes and will
124       die if one is found, e.g..
125
126        $dh = Hash::DefHash->new({"contains space" => 1}); # dies!
127
128       Known options:
129
130       •   check => BOOL (default: 1)
131
132           Whether to check that hash is a valid defhash. Will die if hash
133           turns out to contain invalid keys/values.
134
135       •   parent => HASH/DEFHASH_OBJ
136
137           Set defhash's parent. Default language ("default_lang") will follow
138           parent's if unset in the current hash.
139
140   hash
141       Usage:
142
143        $hashref = $dh->hash;
144
145       Return the original hashref.
146
147   check
148       Usage:
149
150        $dh->check;
151
152   contents
153       Usage:
154
155        my %contents = $dh->contents;
156
157   default_lang
158       Usage:
159
160        $default_lang = $dh->default_lang;
161
162   props
163       Usage:
164
165        @props = $dh->props;
166
167       Return list of properties. Will ignore properties that begin with
168       underscore, e.g.:
169
170        $dh = defhash({a=>1, _b=>2});
171        $dh->props;
172
173   prop
174       Usage:
175
176        $val = $dh->prop($prop [ , \%opts ]);
177
178       Get property value, will die if property does not exist.
179
180       Known options:
181
182       •   die
183
184           Bool. Default true. Whether to die when requested property is not
185           found.
186
187       •   alt
188
189           Hashref.
190
191       •   mark_different_lang
192
193           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
197            {name=>"Chair", "name.alt.lang.id_ID"=>"Kursi"}
198
199           then:
200
201            $dh->prop("name", {lang=>"fr_FR"});
202
203           will die. But:
204
205            $dh->prop("name", {lang=>"fr_FR", mark_different_lang=>1});
206
207           will return:
208
209            "{en_US Chair}"
210
211           or:
212
213            "{id_ID Kursi}"
214
215   get_prop
216       Usage:
217
218        my $val = $dh->get_prop($prop [ , \%opts ]);
219
220       Like "prop"(), but will return undef if property does not exist.
221
222   prop_exists
223       Usage:
224
225        $exists = $dh->prop_exists;
226
227   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
248        my $val = $dh->get_prop_lang($prop, $lang [ , \%opts ]);
249
250       This is just a special case for:
251
252        $dh->prop($prop, {alt=>{lang=>$lang}, mark_different_lang=>1, %opts});
253
254   get_prop_all_langs
255   set_prop_lang

HOMEPAGE

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

SOURCE

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

BUGS

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
268       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

SEE ALSO

272       DefHash specification
273

AUTHOR

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
281       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.
283
284
285
286perl v5.34.0                      2022-01-21                  Hash::DefHash(3)
Impressum