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.
PAYorTAXES 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.11Would 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$memomay 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 (defaultNet 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.