.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Hash::FieldHash 3pm"
.TH Hash::FieldHash 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
[![Build Status](https://travis\-ci.org/gfx/p5\-Hash\-FieldHash.svg?branch=master)](https://travis\-ci.org/gfx/p5\-Hash\-FieldHash)
.SH NAME
Hash::FieldHash \- Lightweight field hash for inside\-out objects
.SH VERSION
.IX Header "VERSION"
This document describes Hash::FieldHash version 0.15.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&        use Hash::FieldHash qw(:all);
\&
\&        fieldhash my %foo;
\&
\&        fieldhashes \emy(%bar, %baz);
\&
\&        {
\&                my $o = Something\->new();
\&
\&                $foo{$o} = 42;
\&
\&                print $foo{$o}; # => 42
\&        }
\&        # when $o is released, $foo{$o} is also deleted,
\&        # so %foo is empty in here.
\&
\&        # in a class
\&        {
\&                package Foo;
\&                use Hash::FieldHash qw(:all);
\&
\&                fieldhash my %bar, \*(Aqbar\*(Aq; # make an accessor
\&        }
\&
\&        my $obj = bless {}, \*(AqFoo\*(Aq;
\&        $obj\->bar(10); # does $bar{$obj} = 10
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Hash::FieldHash\*(C'\fR provides the field hash mechanism which supports
the inside-out technique.
.PP
You may know \f(CW\*(C`Hash::Util::FieldHash\*(C'\fR. It's a very useful module,
but too complex to understand the functionality and only available in 5.10.
\&\f(CW\*(C`H::U::F::Compat\*(C'\fR is available for pre\-5.10, but it is too slow to use.
.PP
This is a better alternative to \f(CW\*(C`H::U::F\*(C'\fR with following features:
.IP "Simpler interface" 4
.IX Item "Simpler interface"
\&\f(CW\*(C`Hash::FieldHash\*(C'\fR provides a few functions:  \f(CWfieldhash()\fR and \f(CWfieldhashes()\fR.
That's enough.
.IP "Higher performance" 4
.IX Item "Higher performance"
\&\f(CW\*(C`Hash::FieldHash\*(C'\fR is faster than \f(CW\*(C`Hash::Util::FieldHash\*(C'\fR, because
its internals use simpler structures.
.IP "Relic support" 4
.IX Item "Relic support"
Although \f(CW\*(C`Hash::FieldHash\*(C'\fR uses a new feature introduced in Perl 5.10,
\&\fIthe uvar magic for hashes\fR described in "GUTS" in Hash::Util::Fieldhash,
it supports Perl 5.8 using the traditional tie-hash layer.
.SH INTERFACE
.IX Header "INTERFACE"
.SS "Exportable functions"
.IX Subsection "Exportable functions"
.ie n .IP """fieldhash(%hash, ?$name, ?$package)""" 4
.el .IP "\f(CWfieldhash(%hash, ?$name, ?$package)\fR" 4
.IX Item "fieldhash(%hash, ?$name, ?$package)"
Creates a field hash. The first argument must be a hash.
.Sp
Optional \fR\f(CI$name\fR\fI\fR and \fI\fR\f(CI$package\fR\fI\fR indicate the name of the field, which will
create rw-accessors, using the same name as \fI\fR\f(CI$name\fR\fI\fR.
.Sp
Returns nothing.
.ie n .IP fieldhashes(@hash_refs) 4
.el .IP \f(CWfieldhashes(@hash_refs)\fR 4
.IX Item "fieldhashes(@hash_refs)"
Creates a number of field hashes. All the arguments must be hash references.
.Sp
Returns nothing.
.ie n .IP """from_hash($object, \e%fields)""" 4
.el .IP "\f(CWfrom_hash($object, \e%fields)\fR" 4
.IX Item "from_hash($object, %fields)"
Fills the named fields associated with \fR\f(CI$object\fR\fI\fR with \fI\fR\f(CI%fields\fR\fI\fR.
The keys of \fI\fR\f(CI%fields\fR\fI\fR can be simple or fully qualified.
.Sp
Returns \fR\f(CI$object\fR\fI\fR.
.ie n .IP """to_hash($object, ?\-fully_qualify)""" 4
.el .IP "\f(CWto_hash($object, ?\-fully_qualify)\fR" 4
.IX Item "to_hash($object, ?-fully_qualify)"
Serializes \fR\f(CI$object\fR\fI\fR into a hash reference.
.Sp
If the \f(CW\*(C`\-fully_qualify\*(C'\fR option is supplied , field keys are fully qualified.
.Sp
For example:
.Sp
.Vb 2
\&        package MyClass;
\&        use FieldHash qw(:all);
\&
\&        fieldhash my %foo => \*(Aqfoo\*(Aq;
\&
\&        sub new{
\&                my $class = shift;
\&                my $self  = bless {}, $class;
\&                return from_hash($self, @_);
\&        }
\&
\&        package MyDerivedClass;
\&        use parent \-norequire => \*(AqMyClass\*(Aq;
\&        use FieldHash qw(:all);
\&
\&        fieldhash my %bar => \*(Aqbar\*(Aq;
\&
\&        package main;
\&
\&        my $o = MyDerivedClass\->new(foo => 10, bar => 20);
\&        my $p = MyDerivedClass\->new(\*(AqMyClass::foo\*(Aq => 10, \*(AqMyDerivedClass::bar\*(Aq => 20);
\&
\&        use Data::Dumper;
\&        print Dumper($o\->to_hash());
\&        # $VAR1 = { foo => 10, bar => 20 }
\&
\&        print Dumper($o\->to_hash(\-fully_qualify));
\&        # $VAR1 = { \*(AqMyClass::foo\*(Aq => 10, \*(AqMyDerived::bar\*(Aq => 20 }
.Ve
.SH ROBUSTNESS
.IX Header "ROBUSTNESS"
.SS "Thread support"
.IX Subsection "Thread support"
As \f(CW\*(C`Hash::Util::FieldHash\*(C'\fR does, \f(CW\*(C`Hash::FieldHash\*(C'\fR fully supports threading
using the \f(CW\*(C`CLONE\*(C'\fR method.
.SS "Memory leaks"
.IX Subsection "Memory leaks"
\&\f(CW\*(C`Hash::FieldHash\*(C'\fR itself does not leak memory, but it may leak memory when
you uses hash references as field hash keys because of an issue of perl 5.10.0.
.SH NOTES
.IX Header "NOTES"
.SS "The type of field hash keys"
.IX Subsection "The type of field hash keys"
\&\f(CW\*(C`Hash::FieldHash\*(C'\fR accepts only references and registered addresses as its
keys, whereas \f(CW\*(C`Hash::Util::FieldHash\*(C'\fR accepts any type of scalars.
.PP
According to "The Generic Object" in Hash::Util::FieldHash,
Non-reference keys in \f(CW\*(C`H::U::F\*(C'\fR are used for class fields. That is,
all the fields defined by \f(CW\*(C`H::U::F\*(C'\fR act as both object fields and class fields
by default. It seems confusing; if you do not want them to be class fields,
you must check the type of \fR\f(CI$self\fR\fI\fR explicitly. In addition,
these class fields are never inherited.
This behavior seems problematic, so \f(CW\*(C`Hash::FieldHash\*(C'\fR
restricts the type of keys.
.SS "The ID of field hash keys"
.IX Subsection "The ID of field hash keys"
While \f(CW\*(C`Hash::Util::FieldHash\*(C'\fR uses \f(CW\*(C`refaddr\*(C'\fR as the IDs of field
hash keys, \f(CW\*(C`Hash::FieldHash\*(C'\fR allocates arbitrary integers as the
IDs.
.SS "What accessors return"
.IX Subsection "What accessors return"
The accessors \f(CWfieldhash()\fR creates are \fBchainable\fR accessors.
That is, it returns the \fR\f(CI$object\fR\fI\fR (i.e. \f(CW$self\fR) with a parameter,
where as it returns the \fI\fR\f(CI$value\fR\fI\fR without it.
.PP
For example:
.PP
.Vb 3
\&    my $o = YourClass\->new();
\&    $o\->foo(42);           # returns $o itself
\&    my $value = $o\->foo(); # retuns 42
.Ve
.SH DEPENDENCIES
.IX Header "DEPENDENCIES"
Perl 5.8.5 or later, and a C compiler.
.SH BUGS
.IX Header "BUGS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Hash::Util::FieldHash.
.PP
Hash::Util::FieldHash::Compat.
.PP
"Magic Virtual Tables" in perlguts.
.PP
Class::Std describes the inside-out technique.
.SH AUTHOR
.IX Header "AUTHOR"
Fuji, Goro (gfx) <gfuji(at)cpan.org>.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2009\-2010, Fuji, Goro. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.