Provided by: libfinance-qif-perl_3.02-1.1_all bug

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.

           transaction
               Dollar amount of transaction.

           total
               Dollar amount of transaction. This is generally the same as transaction but in
               some cases can be higher. (Introduced in Quicken 2005 for windows)

           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.

           total
               Dollar amount of transaction. This is generally the same as amount but in some
               cases can be higher. (Introduced in Quicken 2005 for windows)

       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.

           note
               Additional information about 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.

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

           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.

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

           transaction
               Dollar amount of transaction.

           total
               Dollar amount of transaction. This is generally the same as amount but in some
               cases can be higher. (Introduced in Quicken 2005 for windows)

           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.

           action
               Type of investment transaction like buty, sell, ... (Inroduced in Quicken 2006 for
               windows)

           security
               Security name of transaction. (Inroduced in Quicken 2006 for windows)

           price
               Price of security. (Inroduced in Quicken 2006 for windows)

           quantity
               Quantity of security. (Inroduced in Quicken 2006 for windows)

           amount
               Dollar amount of transaction. (Introduced in Quicken 2006 for windows)

           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.

           budget
               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.

           name
               Name of payees.

           address
               Address of payee.

           city
               City of payee.

           state
               State of payee

           zip Zipcode of payee.

           country
               Country 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.  See "file()" for details.

             my $in = Finance::QIF->new( file => "myfile" );
           OR
             my $in = Finance::QIF->new( file => [ "myfile", "<:crlf" ] );

           For output files, be sure to open the file in write mode.  For example:

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

       record_separator
           Can be used to redefine the QIF record separator.  Default is $/.

             my $in = Finance::QIF->new( record_separator => "\012" );

           Note: For MacOS X it will most likely be necessary to change this to "\015".  Quicken
           on MacOS X generates files with "\015" as the separator which is typical of Mac
           however the native perl in MacOS X is unix based and uses the default unix separator
           which is "\012".  See "autodetect" for another option.

       autodetect
           Enable auto detection of the record separator based on the file contents.  Default is
           "0".

             my $in = Finance::QIF->new( autodetect => 1 );

           Perl uses $/ to define line separators for text files.  Perl sets this value according
           to the OS perl is running on:

             Windows="\015\012"
             Mac="\015"
             Unix="\012"

           In many cases you may find yourself with text files that do not match the OS.  In
           these cases Finance::QIF by default will not process that QIF file correctly. This
           feature is an attempt to help with the most common cases of having the wrong text file
           for the OS Finance::QIF is running on.

           This feature depends on being able to seek to the end of the file and reading the last
           2 characters to determine the proper separator. If a seek can not be performed or the
           last 2 characters are not a proper separator the record_separator will default to $/
           or the value passed in. If a valid record_separator is found then it will be set
           according to what was in the file.

           This code requires a file use a consistent line separator. If you find your self
           dealing with unusual files containing mixed separators you need to first Normalize the
           file to a consistent separator.

           Normalizing a text file to have a consistent line separator is done in modules like
           File::LocalizeNewlines or Template::Parser::LocalizeNewlines so if you are having
           issues with trying to process poorly formated text files look at preprocessing them
           with something like those before passing on to Finance::QIF.

       trim_white_space
           Can be used to remove leading and trailing white space from values returned. Default
           is "0".

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

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

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

   file()
       Specify file name and optionally additional parameters that will be used to obtain a
       filehandle.  The argument can be a filename (SCALAR), an ARRAY reference, or an ARRAY
       whose values must be valid arguments for passing to IO::File->new.

         $qif->file( "myfile" );
        OR
         $qif->file( [ "myfile", "<:crlf" ] );
        OR
         $qif->file( "myfile", "<:crlf" );

       For output files, be sure to open the file in write mode.

   record_separator()
       Returns the currently used record_separator.  This is used primarly in situations where
       you open a QIF file with autodetect and then want to write out a QIF file in the same
       format.

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

   open()
       Open already specified file.

         $qif->open();

       Open also supports the same arguments as "file()".

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

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

       Returns undef 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();

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 maintained at <http://sourceforge.net/projects/finance-qif>

COPYRIGHT

       Copyright (C) 2006-2008 by Matthew McGillis.  All rights reserved.

LICENSE

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