The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Finance-PaycheckRecords-1.001
River stage zero No dependents
++
/ Finance::PaycheckRecords

NAME

Finance::PaycheckRecords - Parse data from PaycheckRecords.com

VERSION

This document describes version 1.001 of Finance::PaycheckRecords, released October 24, 2015.

SYNOPSIS

  use Finance::PaycheckRecords;

  my $paystub = parse_paystub(file => $filename);

  print "!Type:Bank\n", paystub_to_QIF($paystub, {
    category => 'Assets:MyBank',
    memo     => $memo,
    income => {
      PAY => {
        Salary => [ 'Income:Salary' ],
      },
    },
    expenses => {
      'TAXES WITHHELD' => {
        'Federal Income Tax' => [ 'Expenses:Tax:Fed', 'Federal income tax' ],
        'Medicare'        => [ 'Expenses:Tax:Medicare', 'Medicare tax' ],
        'Social Security' => [ 'Expenses:Tax:Soc Sec', 'Social Security tax' ],
      },
    },
  });

DESCRIPTION

Finance::PaycheckRecords can parse paystubs from PaycheckRecords.com, so you can extract the information from them. It also includes a function to generate a Quicken Interchange Format (QIF) record from a paystub.

SUBROUTINES

parse_paystub

  $paystub = parse_paystub(file => $filename_or_filehandle);
  $paystub = parse_paystub(string => $html);

This parses an HTML printer-friendly paystub stored in a file or string and extracts the data from it. $paystub is a hashref with the following keys:

check_number

The check number, if available. May be omitted for direct deposits.

company

The name and address of the company as it appears on the paystub.

date

The date of the check, in whatever format it was displayed on the paystub.

pay_period

The pay period as it appears on the paystub. Usually two dates separated by a hyphen and whitespace.

payee

The name and address of the employee as it appears on the paystub.

split

A hashref keyed by section name (e.g. PAY or TAXES WITHHELD). Each value is another hashref with an entry for each row of the table, keyed by the first column. That value is a hashref keyed by column name.

totals

A hashref containing the totals from the bottom of the check, keyed by field name (e.g. 'Net This Check'). Dollar signs, commas, and whitespace are removed from the values.

An example should make this clearer. A paystub that looks like this:

                          Pay stub for period: 12/15/2012 - 12/28/2012
  Big Employer
  123 Any St.                                             Check # 3456
  Big City, ST 12345                                  Date: 01/04/2013

  John Q. Public                                Net Pay: $ 1111.11
  789 Main St.
  Apt. 234
  My Town, ST 12567

 PAY    Hours Rate Current    YTD    TAXES WITHHELD    Current    YTD
 Salary            1766.65 1766.65   Federal Income Tax 333.33  333.33
                                     Social Security    222.22  222.22
                                     Medicare            99.99   99.99

                                     SUMMARY           Current    YTD
                                     Total Pay         1766.65 1766.65
                                     Deductions           0.00    0.00
                                     Taxes              655.54  655.54
                                           Net This Check:   $1,111.11

Would produce this hashref:

 $paystub = {
  check_number => 3456,
  company      => "Big Employer\n123 Any St.\nBig City, ST 12345",
  date         => "01/04/2013",
  pay_period   => "12/15/2012 - 12/28/2012",
  payee        => "John Q. Public\n789 Main St.\n" .
                  "Apt. 234\nMy Town, ST 12567",
  split        => {
    'PAY' => {
      Salary => { Current => '1766.65', Hours => '', Rate => '',
                  YTD     => '1766.65' },
    },
    'TAXES WITHHELD' => {
      'Federal Income Tax' => {Current => '333.33', YTD => '333.33'},
      'Medicare'           => {Current =>  '99.99', YTD =>  '99.99'},
      'Social Security'    => {Current => '222.22', YTD => '222.22'},
    },
    'SUMMARY' => {
      'Deductions' => { Current =>    '0.00', YTD =>    '0.00' },
      'Taxes'      => { Current =>  '655.54', YTD =>  '655.54' },
      'Total Pay'  => { Current => '1766.65', YTD => '1766.65' },
    },
  },
  totals       => { 'Net This Check' => '1111.11' },
 };

paystub_to_QIF

  $qif_entry = paystub_to_QIF($paystub, \%config);

This function takes a $paystub hashref as returned from parse_paystub and returns a QIF record with data from the paystub. It returns only a single record; you'll need to add a header (e.g. "!Type:Bank\n") to form a valid QIF file.

The %config hashref may contain the following keys:

category

The QIF category to use for the deposit (default Income).

expenses

A hashref in the same format as income, but values are subtracted from your income instead of added to it.

income

A hashref that describes which entries in $paystub->{split} describe income and what category to use for each row in that section. The key is the section name, and the value is a hashref keyed by the first column. That value is an arrayref: [ $category, $memo ]. The $memo may be omitted. It croaks if the section contains a row that is not described here. However, it is ok to have an entry that describes a row not found in the current paystub.

memo

The QIF memo for this transaction (default "Paycheck for $paystub->{pay_period}").

net_deposit

The name of the key in $paystub->{totals} that contains the net deposit amount (default Net This Check).

The example directory in this distribution contains sample paystubs along with a program to generate a complete QIF file from one.

SEE ALSO

Finance::PaycheckRecords::Fetcher can be used to automatically download paystubs from PaycheckRecords.com.

The Quicken Interchange Format (QIF): http://web.archive.org/web/20100222214101/http://web.intuit.com/support/quicken/docs/d_qif.html

CONFIGURATION AND ENVIRONMENT

Finance::PaycheckRecords requires no configuration files or environment variables.

DEPENDENCIES

Finance::PaycheckRecords requires HTML::TableExtract (2.10 or later).

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

I don't know how consistent the layout of paystubs for different companies are. Two example paystubs are included as example/Paycheck-2013-01-04.html (printed check) and example/Paycheck-2015-10-23.html (direct deposit).

If your paystub doesn't parse properly, please report a bug (see the AUTHOR section) and attach a copy of one of your paystubs (after changing the numbers and/or names if you don't want to tell everyone your salary or employer).

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-Finance-PaycheckRecords AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Finance-PaycheckRecords.

You can follow or contribute to Finance-PaycheckRecords's development at https://github.com/madsen/finance-paycheckrecords.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.