Hash::DefHash(3pm)

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.071 of Hash::DefHash (from Perl
10       distribution Hash-DefHash), released on 2020-01-04.
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

FUNCTIONS

100   defhash([ $hash ]) => OBJ
101       Shortcut for "Hash::DefHash->new($hash)". As a bonus, can also detect
102       if $hash is already a defhash and returns it immediately instead of
103       wrapping it again. Exported by default.
104

METHODS

106   new
107       Usage:
108
109        $dh = Hash::DefHash->new([ $hash ],[ %opts ]);
110
111       Constructor. Create a new Hash::DefHash object, which is a thin OO skin
112       over the regular Perl hash. If $hash is not specified, a new anonymous
113       hash is created.
114
115       Internally, the object contains a hash reference which contains
116       reference to the hash ("bless({hash=>$orig_hash, ...},
117       'Hash::DefHash')"). It does not create a copy of the hash or bless the
118       hash directly. Be careful not to assume that the two are the same!
119
120       Will check the keys of hash for invalid properties/attributes and will
121       die if one is found, e.g..
122
123        $dh = Hash::DefHash->new({"contains space" => 1}); # dies!
124
125       Known options:
126
127       ·   check => BOOL (default: 1)
128
129           Whether to check that hash is a valid defhash. Will die if hash
130           turns out to contain invalid keys/values.
131
132       ·   parent => HASH/DEFHASH_OBJ
133
134           Set defhash's parent. Default language ("default_lang") will follow
135           parent's if unset in the current hash.
136
137   hash
138       Usage:
139
140        $hashref = $dh->hash;
141
142       Return the original hashref.
143
144   check
145       Usage:
146
147        $dh->check;
148
149   contents
150       Usage:
151
152        my %contents = $dh->contents;
153
154   default_lang
155       Usage:
156
157        $default_lang = $dh->default_lang;
158
159   props
160       Usage:
161
162        @props = $dh->props;
163
164       Return list of properties. Will ignore properties that begin with
165       underscore, e.g.:
166
167        $dh = defhash({a=>1, _b=>2});
168        $dh->props;
169
170   prop
171       Usage:
172
173        $val = $dh->prop($name);
174
175       Get property value, will die if property does not exist.
176
177   get_prop
178        $val = $dh->get_prop($name);
179
180       Like "prop"(), but will return undef if property does not exist.
181
182   prop_exists
183       Usage:
184
185        $exists = $dh->prop_exists;
186
187   add_prop
188   set_prop
189   del_prop
190   del_all_props
191   attrs
192   attr
193   get_attr
194   attr_exists
195   add_attr
196   set_attr
197   del_attr
198   del_all_attrs
199   defhash_v
200   v
201   name
202   summary
203   description
204   tags
205   get_prop_lang
206   get_prop_all_langs
207   set_prop_lang

HOMEPAGE

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

SOURCE

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

BUGS

217       Please report any bugs or feature requests on the bugtracker website
218       <https://rt.cpan.org/Public/Dist/Display.html?Name=Hash-DefHash>
219
220       When submitting a bug or request, please include a test-file or a patch
221       to an existing test-file that illustrates the bug or desired feature.
222

AUTHOR

227       perlancar <perlancar@cpan.org>
228

COPYRIGHT AND LICENSE

230       This software is copyright (c) 2020, 2018, 2016, 2015, 2014, 2012 by
231       perlancar@cpan.org.
232
233       This is free software; you can redistribute it and/or modify it under
234       the same terms as the Perl 5 programming language system itself.
235
236
237
238perl v5.32.0                      2020-07-28                  Hash::DefHash(3)