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 <sharyanto@cpan.org>

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

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.