/ 
Finance-QIF-2.00.beta1
River stage one • 1 direct dependent • 1 total dependent
/ Finance::QIF

NAME

Finance::QIF - Parse and create Quicken Interchange Format files

SYNOPSIS

use Finance::QIF;

my $qif = Finance::QIF->new( file => "test.qif" );

while ( my $record = $qif->next() ) {
    print( "Header: ", $record->{header}, "\n" );
    foreach my $key ( keys %{$record} ) {
        next
          if ( $key eq "header"
            || $key eq "splits"
            || $key eq "budget"
            || $key eq "prices" );
        print( "     ", $key, ": ", $record->{$key}, "\n" );
    }
    if ( exists( $record->{splits} ) ) {
        foreach my $split ( @{ $record->{splits} } ) {
            foreach my $key ( keys %{$split} ) {
                print( "     Split: ", $key, ": ", $split->{$key}, "\n" );
            }
        }
    }
    if ( exists( $record->{budget} ) ) {
        print("     Budget: ");
        foreach my $amount ( @{ $record->{budget} } ) {
            print( " ", $amount );
        }
        print("\n");
    }
    if ( exists( $record->{prices} ) ) {
        print("     Date     Close   Max     Min     Volume\n");
        $format = "     %8s %7.2f %7.2f %7.2f %-8d\n";
        foreach my $price ( @{ $record->{prices} } ) {
            printf( $format,
                $price->{"date"}, $price->{"close"}, $price->{"max"},
                $price->{"min"},  $price->{"volume"} );
        }
    }
}

DESCRIPTION

Finance::QIF is a module for working with QIF (Quicken Interchange Format) files in Perl. This module reads QIF data records from a file passing each successive record to the caller for processing. This module also has the capability of writing QIF records to a file.

The QIF file format typically consists of a header containing a record or transaction type, followed by associated data records. Within a file there may be multiple headers. Headers are usually followed by data records, however data is not required to always follow a header.

A hash reference is returned for each record read from a file. The hash will have a "header" value which contains the header type that was read along with all supported values found for that record. If a value is not specified in the data file, the value will not exist in this hash.

No processing or validation is done on values found in files or data structures to try and convert them into appropriate types and formats. It is expected that users of this module or extensions to this module will do any additional processing or validation as required.

RECORD TYPES & VALUES

The following record types are currently supported by this module:

Type:Bank, Type:Cash, Type:CCard, Type:Oth A, Type:Oth L

These are non investment ledger transactions. All of these record types support the following values.

date

Date of transaction.

amount

Dollar amount of transaction.

status

Reconciliation status of transaction.

number

Check number of transaction.

payee

Who the transaction was made to.

memo

Additional text describing the transaction.

address

Address of payee.

category

Category the transaction is assigned to.

splits

If the transaction contains splits this will be defined and consist of an array of hash references. With each split potentially having the following values.

category

Category the split is assigned to.

memo

Additional text describing the split.

amount

Dollar amount of split.

Type:Invst

This is for Investment ledger transactions. The following values are supported for this record type.

date

Date of transaction.

action

Type of transaction like buy, sell, ...

security

Security name of transaction.

price

Price of security at time of transaction.

quantity

Number of shares purchased.

transaction

Cost of shares in transaction.

status

Reconciliation status of transaction.

text

Text for non security specific transaction.

memo

Additional text describing transaction.

commission

Commission fees related to transaction.

account

Account related to security specific transaction.

amount

Dollar amount of transaction.

Account

This is a list of accounts. In cases where it is used in a file by first providing one account record followed by a investment or non-investment record type and its transactions, it means that that set of transactions is related to the specified account. In other cases it can just be a sequence of Account records.

Each account record supports the following values.

name

Account name.

description

Account description.

limit

Account limit usually for credit card accounts that have some upper limit over credit.

tax

Defined if the account is tax related.

address

Address associated with the account.

type

Type of account.

balance

Current balance of account.

Type:Cat

This is a list of categories. The following values are supported for category records.

name

Name of category.

description

Description of category.

expense

Usually exists if the category is an expense account however this is often a default assumed value and doesn't show up in files.

income

Exists if the category is an income account.

tax

Exists if this category is tax related.

schedule

If this category is tax related this specifies what tax schedule it is related if defined.

Type:Class

This is a list of classes. The following values are supported for class records.

name

Name of class.

description

Description of class.

Type:Memorized

This is a list of memorized transactions. The following values are supported for memorized transaction records.

transaction

Type of memorized transaction "C" for check, "D" for deposit, "P" for payment, "I" for investment, and "E" for electronic payee.

amount

Dollar amount of transaction.

status

Reconciliation status of transaction.

payee

Who the transaction was made to.

memo

Additional text describing the transaction.

address

Address of payee.

category

Category the transaction is assigned to.

splits

If the transaction contains splits this will be defined and consist of an array of hashes. With each split potentially having the following values.

category

Category the split is assigned to.

memo

Additional text describing the split.

amount

Dollar amount of split.

first

First payment date.

years

Total years for loan.

made

Number of payments already made.

periods

Number of periods per year.

interest

Interest rate of loan.

balance

Current loan balance.

loan

Original loan amount.

Type:Security

This is a list of securities. The following values are supported for security records.

security

Security name.

symbol

Security symbol.

type

Security type.

goal

Security goal.

Type:Budget

This is a list of budget values for categories. The following values are supported for budget records.

name

Category name of budgeted item.

description

Category Description of budgeted item.

expense

Usually exists if the category is an expense account however this is often a default assumed value and doesn't show up in files.

income

Exists if the category is an income account.

tax

Exists if this category is tax related.

schedule

If this category is tax related this specifies what tax schedule it is related if defined.

amount

An array of 12 values Jan-Dec to represent the budget amount for each month.

Type:Payee

This is a list online payee accounts. The following values are supported for online payee account records.

Note: A common field for this type is identified by a "Y" however so far I have been unable to determine what that field represents. As a result this software currently doesn't support it and will raise a warning when ever it is found.

name

Name of payees.

address

Address of payee.

city

City of payee.

state

State of payee

zip

Zipcode of payee.

phone

Phone number of payee.

account

Account number for payee transaction.

Type:Prices

This is a list of prices for a security. The following values are supported for security prices records.

symbol

Security Symbol.

prices

An array of hashes. With each hash having the following values.

date

Date of security values.

close

Close value of security for the date.

max

Max value of security for the date.

min

Min value of security for the date.

volume

Number of shares of security exchanged for the date.

Option:AllXfr, Option:AutoSwitch, Clear:AutoSwitch

These record types aren't related to transactions but instead provided ways to control how Quicken processes the QIF file. They have no impact on how this software operates and are ignored when found.

Note: If this software finds unsupported record types or values in a data file a warning will be generated containing information on what unexpected value was found.

METHODS

new()

Creates a new instance of Finance::QIF. Supports the following initializing values.

my $qif = Finance::QIF->new( file => "myfile", debug => 1 );

If the file is specified it will be opened on new.

file

Specifies file to use for processing.

my $in = Finance::QIF->new( file => "myfile" );

For output files must include ">" with file name.

my $out = Finance::QIF->new( file => ">myfile" );
output_record_separator

Can be used to redefine the QIF output record separator. Default is "\r".

my $out = Finance::QIF->new( output_record_separator => "\n" );
input_record_separator

Can be used to redefine the QIF input record separator. Default is "\r".

my $in = Finance::QIF->new( input_record_separator => "\n" );
debug

Can be used to output debug information. Default is "0".

my $qif = Finance::QIF->new( debug => 1 );

file()

Specify file name to use. For output files must include ">" with name.

$qif->file("myfile");

open()

Open already specified file.

$qif->open();

Opens specified file.

$qif->open("myfile");

next()

For input files return the next record in the QIF file.

my $record = $in->next();

Returns null if no more records are available.

header()

For output files use to output the passed header for records that will then be written with write.

$out->header("Type:Bank");

See "RECORD TYPES & VALUES" for list of possible record types that can be passed.

write()

For output files use to output the passed record to the file.

$out->write($record);

reset()

Resets the filehandle so the records can be read again from the beginning of the file.

$qif->reset();

close()

Closes the open file.

$qif->close();

EXAMPLES

Read an existing QIF file then write out to new QIF file.

my $in  = Finance::QIF->new( file => "input.qif" );
my $out = Finance::QIF->new( file => ">write.qif" );

my $header = "";
while ( my $record = $in->next() ) {
    if ( $header ne $record->{header} ) {
        $out->header( $record->{header} );
        $header = $record->{header};
    }
    $out->write($record);
}

$in->close();
$out->close();

TODO

Type:Payee is not complete. Real exports from Quicken with this feature being used are required to complete support for this type.

SEE ALSO

Carp, IO::File

Quicken Interchange Format (QIF) specification http://web.intuit.com/support/quicken/docs/d_qif.html

ACKNOWLEDGEMENTS

Simon Cozens simon@cpan.org, Author of original Finance::QIF

Nathan McFarland nmcfarl@cpan.org, Maintainer of original Finance::QIF

AUTHORS

Matthew McGillis <matthew@mcgillis.org> http://www.mcgillis.org/

Phil Lobbes <phil at perkpartners dot com>

Project maintaned at http://www.sourceforge.net/projects/finance-qif

COPYRIGHT

Copyright (C) 2006 by Matthew McGillis. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.