.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .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. \*(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- .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" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Finance::QIF 3pm" .TH Finance::QIF 3pm "2021-01-07" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Finance::QIF \- Parse and create Quicken Interchange Format files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Finance::QIF; \& \& my $qif = Finance::QIF\->new( file => "test.qif" ); \& \& while ( my $record = $qif\->next ) { \& print( "Header: ", $record\->{header}, "\en" ); \& foreach my $key ( keys %{$record} ) { \& next \& if ( $key eq "header" \& || $key eq "splits" \& || $key eq "budget" \& || $key eq "prices" ); \& print( " ", $key, ": ", $record\->{$key}, "\en" ); \& } \& if ( exists( $record\->{splits} ) ) { \& foreach my $split ( @{ $record\->{splits} } ) { \& foreach my $key ( keys %{$split} ) { \& print( " Split: ", $key, ": ", $split\->{$key}, "\en" ); \& } \& } \& } \& if ( exists( $record\->{budget} ) ) { \& print(" Budget: "); \& foreach my $amount ( @{ $record\->{budget} } ) { \& print( " ", $amount ); \& } \& print("\en"); \& } \& if ( exists( $record\->{prices} ) ) { \& print(" Date Close Max Min Volume\en"); \& $format = " %8s %7.2f %7.2f %7.2f %\-8d\en"; \& foreach my $price ( @{ $record\->{prices} } ) { \& printf( $format, \& $price\->{"date"}, $price\->{"close"}, $price\->{"max"}, \& $price\->{"min"}, $price\->{"volume"} ); \& } \& } \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Finance::QIF is a module for working with \s-1QIF\s0 (Quicken Interchange Format) files in Perl. This module reads \s-1QIF\s0 data records from a file passing each successive record to the caller for processing. This module also has the capability of writing \s-1QIF\s0 records to a file. .PP The \s-1QIF\s0 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. .PP A hash reference is returned for each record read from a file. The hash will have a \*(L"header\*(R" 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. .PP 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. .SS "\s-1RECORD TYPES & VALUES\s0" .IX Subsection "RECORD TYPES & VALUES" The following record types are currently supported by this module: .IP "Type:Bank, Type:Cash, Type:CCard, Type:Oth A, Type:Oth L" 4 .IX Item "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. .RS 4 .IP "date" 4 .IX Item "date" Date of transaction. .IP "transaction" 4 .IX Item "transaction" Dollar amount of transaction. .IP "total" 4 .IX Item "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) .IP "status" 4 .IX Item "status" Reconciliation status of transaction. .IP "number" 4 .IX Item "number" Check number of transaction. .IP "payee" 4 .IX Item "payee" Who the transaction was made to. .IP "memo" 4 .IX Item "memo" Additional text describing the transaction. .IP "address" 4 .IX Item "address" Address of payee. .IP "category" 4 .IX Item "category" Category the transaction is assigned to. .IP "splits" 4 .IX Item "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. .RS 4 .IP "category" 4 .IX Item "category" Category the split is assigned to. .IP "memo" 4 .IX Item "memo" Additional text describing the split. .IP "amount" 4 .IX Item "amount" Dollar amount of split. .RE .RS 4 .RE .RE .RS 4 .RE .IP "Type:Invst" 4 .IX Item "Type:Invst" This is for Investment ledger transactions. The following values are supported for this record type. .RS 4 .IP "date" 4 .IX Item "date" Date of transaction. .IP "action" 4 .IX Item "action" Type of transaction like buy, sell, ... .IP "security" 4 .IX Item "security" Security name of transaction. .IP "price" 4 .IX Item "price" Price of security at time of transaction. .IP "quantity" 4 .IX Item "quantity" Number of shares purchased. .IP "transaction" 4 .IX Item "transaction" Cost of shares in transaction. .IP "status" 4 .IX Item "status" Reconciliation status of transaction. .IP "text" 4 .IX Item "text" Text for non security specific transaction. .IP "memo" 4 .IX Item "memo" Additional text describing transaction. .IP "commission" 4 .IX Item "commission" Commission fees related to transaction. .IP "account" 4 .IX Item "account" Account related to security specific transaction. .IP "amount" 4 .IX Item "amount" Dollar amount of transaction. .IP "total" 4 .IX Item "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) .RE .RS 4 .RE .IP "Account" 4 .IX Item "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. .Sp Each account record supports the following values. .RS 4 .IP "name" 4 .IX Item "name" Account name. .IP "description" 4 .IX Item "description" Account description. .IP "limit" 4 .IX Item "limit" Account limit usually for credit card accounts that have some upper limit over credit. .IP "tax" 4 .IX Item "tax" Defined if the account is tax related. .IP "note" 4 .IX Item "note" Additional information about the account. .IP "type" 4 .IX Item "type" Type of account. .IP "balance" 4 .IX Item "balance" Current balance of account. .RE .RS 4 .RE .IP "Type:Cat" 4 .IX Item "Type:Cat" This is a list of categories. The following values are supported for category records. .RS 4 .IP "name" 4 .IX Item "name" Name of category. .IP "description" 4 .IX Item "description" Description of category. .IP "budget" 4 .IX Item "budget" An array of 12 values Jan-Dec to represent the budget amount for each month. .IP "expense" 4 .IX 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. .IP "income" 4 .IX Item "income" Exists if the category is an income account. .IP "tax" 4 .IX Item "tax" Exists if this category is tax related. .IP "schedule" 4 .IX Item "schedule" If this category is tax related this specifies what tax schedule it is related if defined. .RE .RS 4 .RE .IP "Type:Class" 4 .IX Item "Type:Class" This is a list of classes. The following values are supported for class records. .RS 4 .IP "name" 4 .IX Item "name" Name of class. .IP "description" 4 .IX Item "description" Description of class. .RE .RS 4 .RE .IP "Type:Memorized" 4 .IX Item "Type:Memorized" This is a list of memorized transactions. The following values are supported for memorized transaction records. .RS 4 .IP "type" 4 .IX Item "type" Type of memorized transaction \*(L"C\*(R" for check, \*(L"D\*(R" for deposit, \*(L"P\*(R" for payment, \*(L"I\*(R" for investment, and \*(L"E\*(R" for electronic payee. .IP "transaction" 4 .IX Item "transaction" Dollar amount of transaction. .IP "total" 4 .IX Item "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) .IP "status" 4 .IX Item "status" Reconciliation status of transaction. .IP "payee" 4 .IX Item "payee" Who the transaction was made to. .IP "memo" 4 .IX Item "memo" Additional text describing the transaction. .IP "address" 4 .IX Item "address" Address of payee. .IP "category" 4 .IX Item "category" Category the transaction is assigned to. .IP "action" 4 .IX Item "action" Type of investment transaction like buty, sell, ... (Inroduced in Quicken 2006 for windows) .IP "security" 4 .IX Item "security" Security name of transaction. (Inroduced in Quicken 2006 for windows) .IP "price" 4 .IX Item "price" Price of security. (Inroduced in Quicken 2006 for windows) .IP "quantity" 4 .IX Item "quantity" Quantity of security. (Inroduced in Quicken 2006 for windows) .IP "amount" 4 .IX Item "amount" Dollar amount of transaction. (Introduced in Quicken 2006 for windows) .IP "splits" 4 .IX Item "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. .RS 4 .IP "category" 4 .IX Item "category" Category the split is assigned to. .IP "memo" 4 .IX Item "memo" Additional text describing the split. .IP "amount" 4 .IX Item "amount" Dollar amount of split. .RE .RS 4 .RE .IP "first" 4 .IX Item "first" First payment date. .IP "years" 4 .IX Item "years" Total years for loan. .IP "made" 4 .IX Item "made" Number of payments already made. .IP "periods" 4 .IX Item "periods" Number of periods per year. .IP "interest" 4 .IX Item "interest" Interest rate of loan. .IP "balance" 4 .IX Item "balance" Current loan balance. .IP "loan" 4 .IX Item "loan" Original loan amount. .RE .RS 4 .RE .IP "Type:Security" 4 .IX Item "Type:Security" This is a list of securities. The following values are supported for security records. .RS 4 .IP "security" 4 .IX Item "security" Security name. .IP "symbol" 4 .IX Item "symbol" Security symbol. .IP "type" 4 .IX Item "type" Security type. .IP "goal" 4 .IX Item "goal" Security goal. .RE .RS 4 .RE .IP "Type:Budget" 4 .IX Item "Type:Budget" This is a list of budget values for categories. The following values are supported for budget records. .RS 4 .IP "name" 4 .IX Item "name" Category name of budgeted item. .IP "description" 4 .IX Item "description" Category Description of budgeted item. .IP "expense" 4 .IX 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. .IP "income" 4 .IX Item "income" Exists if the category is an income account. .IP "tax" 4 .IX Item "tax" Exists if this category is tax related. .IP "schedule" 4 .IX Item "schedule" If this category is tax related this specifies what tax schedule it is related if defined. .IP "budget" 4 .IX Item "budget" An array of 12 values Jan-Dec to represent the budget amount for each month. .RE .RS 4 .RE .IP "Type:Payee" 4 .IX Item "Type:Payee" This is a list online payee accounts. The following values are supported for online payee account records. .RS 4 .IP "name" 4 .IX Item "name" Name of payees. .IP "address" 4 .IX Item "address" Address of payee. .IP "city" 4 .IX Item "city" City of payee. .IP "state" 4 .IX Item "state" State of payee .IP "zip" 4 .IX Item "zip" Zipcode of payee. .IP "country" 4 .IX Item "country" Country of payee. .IP "phone" 4 .IX Item "phone" Phone number of payee. .IP "account" 4 .IX Item "account" Account number for payee transaction. .RE .RS 4 .RE .IP "Type:Prices" 4 .IX Item "Type:Prices" This is a list of prices for a security. The following values are supported for security prices records. .RS 4 .IP "symbol" 4 .IX Item "symbol" Security Symbol. .IP "prices" 4 .IX Item "prices" An array of hashes. With each hash having the following values. .RS 4 .IP "date" 4 .IX Item "date" Date of security values. .IP "close" 4 .IX Item "close" Close value of security for the date. .IP "max" 4 .IX Item "max" Max value of security for the date. .IP "min" 4 .IX Item "min" Min value of security for the date. .IP "volume" 4 .IX Item "volume" Number of shares of security exchanged for the date. .RE .RS 4 .RE .RE .RS 4 .RE .IP "Option:AllXfr, Option:AutoSwitch, Clear:AutoSwitch" 4 .IX Item "Option:AllXfr, Option:AutoSwitch, Clear:AutoSwitch" These record types aren't related to transactions but instead provided ways to control how Quicken processes the \s-1QIF\s0 file. They have no impact on how this software operates and are ignored when found. .PP 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. .SH "METHODS" .IX Header "METHODS" .SS "\fBnew()\fP" .IX Subsection "new()" Creates a new instance of Finance::QIF. Supports the following initializing values. .PP .Vb 1 \& my $qif = Finance::QIF\->new( file => "myfile", debug => 1 ); .Ve .PP If the file is specified it will be opened on new. .IP "file" 4 .IX Item "file" Specifies file to use for processing. See \*(L"\fBfile()\fR\*(R" for details. .Sp .Vb 3 \& my $in = Finance::QIF\->new( file => "myfile" ); \&OR \& my $in = Finance::QIF\->new( file => [ "myfile", "<:crlf" ] ); .Ve .Sp For output files, be sure to open the file in write mode. For example: .Sp .Vb 1 \& my $out = Finance::QIF\->new( file => ">myfile" ); .Ve .IP "record_separator" 4 .IX Item "record_separator" Can be used to redefine the \s-1QIF\s0 record separator. Default is $/. .Sp .Vb 1 \& my $in = Finance::QIF\->new( record_separator => "\e012" ); .Ve .Sp Note: For MacOS X it will most likely be necessary to change this to \&\*(L"\e015\*(R". Quicken on MacOS X generates files with \*(L"\e015\*(R" 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 \*(L"\e012\*(R". See \&\*(L"autodetect\*(R" for another option. .IP "autodetect" 4 .IX Item "autodetect" Enable auto detection of the record separator based on the file contents. Default is \*(L"0\*(R". .Sp .Vb 1 \& my $in = Finance::QIF\->new( autodetect => 1 ); .Ve .Sp Perl uses $/ to define line separators for text files. Perl sets this value according to the \s-1OS\s0 perl is running on: .Sp .Vb 3 \& Windows="\e015\e012" \& Mac="\e015" \& Unix="\e012" .Ve .Sp In many cases you may find yourself with text files that do not match the \s-1OS.\s0 In these cases Finance::QIF by default will not process that \&\s-1QIF\s0 file correctly. This feature is an attempt to help with the most common cases of having the wrong text file for the \s-1OS\s0 Finance::QIF is running on. .Sp 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. .Sp 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. .Sp 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. .IP "trim_white_space" 4 .IX Item "trim_white_space" Can be used to remove leading and trailing white space from values returned. Default is \*(L"0\*(R". .Sp .Vb 1 \& my $qif = Finance::QIF\->new( trim_white_space => 1 ); .Ve .IP "debug" 4 .IX Item "debug" Can be used to output debug information. Default is \*(L"0\*(R". .Sp .Vb 1 \& my $qif = Finance::QIF\->new( debug => 1 ); .Ve .SS "\fBfile()\fP" .IX Subsection "file()" Specify file name and optionally additional parameters that will be used to obtain a filehandle. The argument can be a filename (\s-1SCALAR\s0), an \s-1ARRAY\s0 reference, or an \s-1ARRAY\s0 whose values must be valid arguments for passing to IO::File\->new. .PP .Vb 5 \& $qif\->file( "myfile" ); \& OR \& $qif\->file( [ "myfile", "<:crlf" ] ); \& OR \& $qif\->file( "myfile", "<:crlf" ); .Ve .PP For output files, be sure to open the file in write mode. .SS "\fBrecord_separator()\fP" .IX Subsection "record_separator()" Returns the currently used record_separator. This is used primarly in situations where you open a \s-1QIF\s0 file with autodetect and then want to write out a \s-1QIF\s0 file in the same format. .PP .Vb 3 \& my $in = Finance::QIF\->new( file => "input.qif", autodetect => 1 ); \& my $out = Finance::QIF\->new( file => ">write.qif", \& record_separator => $in\->record_separator ); .Ve .SS "\fBopen()\fP" .IX Subsection "open()" Open already specified file. .PP .Vb 1 \& $qif\->open(); .Ve .PP Open also supports the same arguments as \*(L"\fBfile()\fR\*(R". .SS "\fBnext()\fP" .IX Subsection "next()" For input files return the next record in the \s-1QIF\s0 file. .PP .Vb 1 \& my $record = $in\->next(); .Ve .PP Returns undef if no more records are available. .SS "\fBheader()\fP" .IX Subsection "header()" For output files use to output the passed header for records that will then be written with write. .PP .Vb 1 \& $out\->header( "Type:Bank" ); .Ve .PP See \*(L"\s-1RECORD TYPES & VALUES\*(R"\s0 for list of possible record types that can be passed. .SS "\fBwrite()\fP" .IX Subsection "write()" For output files use to output the passed record to the file. .PP .Vb 1 \& $out\->write( $record ); .Ve .SS "\fBreset()\fP" .IX Subsection "reset()" Resets the filehandle so the records can be read again from the beginning of the file. .PP .Vb 1 \& $qif\->reset(); .Ve .SS "\fBclose()\fP" .IX Subsection "close()" Closes the open file. .PP .Vb 1 \& $qif\->close(); .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" Read an existing \s-1QIF\s0 file then write out to new \s-1QIF\s0 file. .PP .Vb 2 \& 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(); .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Carp, IO::File .PP Quicken Interchange Format (\s-1QIF\s0) specification .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Simon Cozens \f(CW\*(C`simon@cpan.org\*(C'\fR, Author of original Finance::QIF .PP Nathan McFarland \f(CW\*(C`nmcfarl@cpan.org\*(C'\fR, Maintainer of original Finance::QIF .SH "AUTHORS" .IX Header "AUTHORS" Matthew McGillis .PP Phil Lobbes .PP Project maintained at .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2006\-2008 by Matthew McGillis. All rights reserved. .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.