.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DBIx::Class::DigestColumns 3"
.TH DBIx::Class::DigestColumns 3 "2008-01-01" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
DBIx::Class::DigestColumns \- Automatic digest columns
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In your DBIx::Class table class:
.PP
.Vb 1
\&  __PACKAGE__->load_components(qw/DigestColumns ... Core/);
.Ve
.PP
.Vb 14
\&  #automatically generate a method "check_password" in result class
\&  __PACKAGE__->add_columns(
\&    'password' => {
\&      data_type => 'char',
\&      size      => 32,
\&      digest_check_method => 'check_password',
\&  }
\&  __PACKAGE__->digestcolumns(
\&      columns   => [qw/ password /],
\&      algorithm => 'MD5',
\&      encoding  => 'base64',
\&      dirty     => 1,
\&      auto      => 1,
\&  );
.Ve
.PP
\&\fBNote:\fR The component needs to be loaded \fIbefore\fR Core.
.PP
Alternatively you could call each method individually  
.PP
.Vb 5
\&  __PACKAGE__->digest_columns(qw/ password /);
\&  __PACKAGE__->digest_algorithm('MD5');
\&  __PACKAGE__->digest_encoding('base64');
\&  __PACKAGE__->digest_dirty(1);
\&  __PACKAGE__->digest_auto(1);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This DBIx::Class component can be used to automatically insert a message
digest of selected columns. By default DigestColumns will use
Digest::MD5 to insert a 128\-bit hexadecimal message digest of the column
value.
.PP
The length of the inserted string will be 32 and it will only contain characters
from this set: '0'..'9' and 'a'..'f'.
.PP
If you would like to use a specific digest module to create your message
digest, you can set \*(L"digest_algorithm\*(R":
.PP
.Vb 1
\&  __PACKAGE__->digest_algorithm('SHA-1');
.Ve
.SH "Options added to add_column"
.IX Header "Options added to add_column"
.ie n .Sh "digest_check_method => $method_name"
.el .Sh "digest_check_method => \f(CW$method_name\fP"
.IX Subsection "digest_check_method => $method_name"
By using the digest_check_method attribute when you declare a column you
can create a check method for that column. The check method accepts a 
plain text string, performs the correct digest on it and returns a boolean
value indicating whether this method matches the currently_stored value.
.PP
.Vb 6
\&  $row->password('old_password');
\&  $row->update;
\&  $row->password('new_password');
\&  $row->check_password('new_password'); #returns true
\&  $row->check_password('old_password'); #returns false
\&  $row->update;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.Sh "digestcolumns"
.IX Subsection "digestcolumns"
.Vb 7
\&  __PACKAGE__->digestcolumns(
\&      columns   => [qw/ password /],
\&      algorithm => $algorithm',
\&      encoding  => $encoding,
\&      dirty     => 1,
\&      auto      => 1,
\&  );
.Ve
.PP
Calls \*(L"digest_columns\*(R", \*(L"digest_algorithm\*(R", and \*(L"digest_encoding\*(R" and \*(L"digest_auto\*(R" if the
corresponding argument is defined.
.Sh "register_column"
.IX Subsection "register_column"
Override the original register_column to handle the creation of
check methods.
.Sh "digest_columns"
.IX Subsection "digest_columns"
Takes a list of columns to be convert to a message digest during insert.
.PP
.Vb 1
\&  __PACKAGE__->digest_columns(qw/ password /);
.Ve
.Sh "digest_algorithm"
.IX Subsection "digest_algorithm"
Takes the name of a digest algorithm to be used to calculate the message digest.
.PP
.Vb 1
\&  __PACKAGE__->digest_algorithm('SHA-1');
.Ve
.PP
If a suitible digest module could not be loaded an exception will be thrown.
.PP
Supported digest algorithms are:
.PP
.Vb 14
\&  MD5
\&  MD4
\&  MD2
\&  SHA-1
\&  SHA-256
\&  SHA-384
\&  SHA-512
\&  CRC-16
\&  CRC-32
\&  CRC-CCITT
\&  HMAC-SHA-1
\&  HMAC-MD5
\&  Whirlpool
\&  Adler-32
.Ve
.PP
digest_algorithm defaults to \f(CW\*(C`MD5\*(C'\fR.
.Sh "digest_encoding"
.IX Subsection "digest_encoding"
Selects the encoding to use for the message digest.
.PP
.Vb 1
\&  __PACKAGE__->digest_encoding('base64');
.Ve
.PP
Possilbe encoding schemes are:
.PP
.Vb 3
\&  binary
\&  hex
\&  base64
.Ve
.PP
digest_encoding defaults to \f(CW\*(C`hex\*(C'\fR.
.ie n .Sh "_get_digest_string $value"
.el .Sh "_get_digest_string \f(CW$value\fP"
.IX Subsection "_get_digest_string $value"
Handles the actual encoding of column values into digests.
When given a \f(CW$value\fR it will return the digest string for
that value. This is the method used by \f(CW\*(C`_digest_column_values\*(C'\fR
So you can use it to create an identical digest if you need one
for comparison (e.g. password authentication).
.Sh "_digest_column_values"
.IX Subsection "_digest_column_values"
Go through the columns and digest the values that need it.
.PP
This method is called by insert and update when automatic digests
are turned on. If dirty is enabled it will only digest the values
of dirtied columns.
.Sh "digest_auto"
.IX Subsection "digest_auto"
.Vb 1
\&  __PACKAGE__->digest_auto(1);
.Ve
.PP
Turns on and off automatic digest columns.  When on, this feature makes all
UPDATEs and INSERTs automatically insert a message digest of selected columns.
.PP
The default is for digest_auto is to be on.
.Sh "digest_dirty"
.IX Subsection "digest_dirty"
.Vb 1
\&  __PACKAGE__->digest_dirty(1);
.Ve
.PP
Turns on and off the limiting of automatic digests to only dirty columns.
When on, only columns that have been dirtied will have their values digested
during UPDATEs and INSERTs. If auto is set to off this option does nothing.
.PP
The default is for digest_dirty is to be off to mantain compatibility with older
versions of this module.
.SH "EXTENDED METHODS"
.IX Header "EXTENDED METHODS"
The following DBIx::Class::Row methods are extended by this module:\-
.IP "insert" 4
.IX Item "insert"
.PD 0
.IP "update" 4
.IX Item "update"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DBIx::Class,
Digest
.SH "AUTHOR"
.IX Header "AUTHOR"
Tom Kirkpatrick (tkp) <tkp@cpan.org>
.PP
With contributions from
Guillermo Roditi (groditi) <groditi@cpan.org>
and Marc Mims <marc@questright.com>
.SH "LICENSE"
.IX Header "LICENSE"
You may distribute this code under the same terms as Perl itself.