===================================================================
RCS file: /cvs/pta/pta_import.1,v
retrieving revision 1.2
retrieving revision 1.9
diff -u -p -r1.2 -r1.9
--- pta/pta_import.1	2020/11/01 23:07:35	1.2
+++ pta/pta_import.1	2020/11/28 15:10:36	1.9
@@ -1,4 +1,4 @@
-.\" $Id: pta_import.1,v 1.2 2020/11/01 23:07:35 schwarze Exp $
+.\" $Id: pta_import.1,v 1.9 2020/11/28 15:10:36 freda Exp $
 .\"
 .\" Copyright (c) 2020 Freda Bundchen
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 1 2020 $
+.Dd $Mdocdate: November 28 2020 $
 .Dt PTA_IMPORT 1
 .Os
 .Sh NAME
@@ -22,6 +22,7 @@
 .Nd print pta journal entries from bank CSV file input
 .Sh SYNOPSIS
 .Nm pta_import
+.Fl I Ar accountname
 .Op Ar file
 .Sh DESCRIPTION
 The
@@ -35,62 +36,252 @@ institution into journal entries used by
 If the
 .Ar file
 argument is omitted, standard input is read instead.
+.Pp
+.Ar accountname
+is exactly one of
+.Pp
+.Bl -bullet -offset indent -compact
+.It
+.Cm bbva_usa
+.It
+.Cm capital_one_360
+.It
+.Cm capital_one_credit
+.It
+.Cm chase_credit
+.It
+.Cm etrade_ira
+.It
+.Cm optum_hsa
+.It
+.Cm sparkasse_camt
+.It
+.Cm wellsfargo
+.El
+.Pp
+and corresponds to an existing
+.Pa ./import/ Ns Ar accountname Ns Pa .txt
+configuration file.
+.Ss Configuration file format
+Each configuration file contains rules
+used to import transactions from a financial institution.
+Like all
+.Xr pta 1
+input files, it is an
+.Xr ascii 7
+text file using strings of one or more space characters
+as the field delimiter and using the hash character
+.Pq Sq #
+in the first column to mark lines as ignored.
+.Pp
+The rules are as follows:
+.Bl -tag -width Ds
+.It Ic ACCOUNT Ar csv_account_number
+The number in
+.Xr pta-accounts 5
+of the bank or credit card account this CSV file contains entries for.
+This rule is required in every configuration file.
+.It Ic DELIM Ar delimiter
+The character used to separate fields.
+This rule is required in every configuration file.
+Most financial institutions use commas but some use semicolons.
+.It Ic HEADER Ar header
+Skip the first line of the CSV file if it matches the
+.Ar header
+line verbatim, or cause parsing to fail if it does not.
+.It Ic IGNORE Ar regular_expression
+Skip all lines in the CSV file matching the
+.Ar regular_expression .
+.It Ic QUOTE Ar quote
+Expects that every field starts and ends with the
+.Ar quote
+character.
+.It Ar selector account_number booking_identifier
+Lines in the CSV file that match the
+.Ar selector
+are associated with the contra account
+.Ar account_number
+and are assigned the
+.Ar booking_identifier .
+The selector is a string consisting of regular expressions separated
+by delimiters defined in the
+.Ic DELIM
+rule.
+.El
 .Sh FILES
-.Bl -tag -width import.txt
-.It Pa ./import.txt
-file containing account numbers associated with CSV categories
+.Bl -tag -width Ds -compact
+.It Pa ./import/bbva_usa.txt
+.It Pa ./import/capital_one_360.txt
+.It Pa ./import/capital_one_credit.txt
+.It Pa ./import/chase_credit.txt
+.It Pa ./import/etrade_ira.txt
+.It Pa ./import/optum_hsa.txt
+.It Pa ./import/sparkasse_camt.txt
+.It Pa ./import/wellsfargo.txt
 .El
+.Pp
+These files contain the header that the financial institution uses, the
+account number from
+.Pa ./accounts.txt
+used by this account, as well as patterns used to map transactions to
+the correct account and booking identifier.
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
 Add journal entries to a journal file using a CSV file generated by
 a financial institution:
 .Pp
-.Dl "$ pta_import MyCreditCard1234.csv >> journal.txt"
+.Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt"
+.Ss Account numbers in the configuration file
+The line
 .Pp
-Suppose a line in the CSV file looks like
+.Dl ACCOUNT 3235
 .Pp
-.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
+in the configuration file corresponds to a line such as
 .Pp
-Then
-.Nm
-prints
+.Dl 3235 L Capital One credit card
 .Pp
-.Dl "20201026 SHOP 9996 1234 17.07 example.com*asldfkj"
+in
+.Pa ./accounts.txt .
 .Pp
-In this example, the user's
-.Pa ./import.txt
-contains
+The description
+.Qq Capital One credit card
+may vary, but in this example, the account numbers
+.Qq 3235
+match, and the account type is
+.Qq L
+to indicate that it is a liability account.
+.Ss Patterns in the configuration file
+Suppose
 .Pp
-.Dl "SHOP Shopping 9996"
+.Dl ,,,Automotive,,, 1111 AUTO
 .Pp
-to reflect that their expense account for shopping is 9996 in
-.Pa ./accounts.txt
-and
+is a sample entry in the
+.Pa ./import/chase_credit.txt
+file which uses headers of the form
 .Pp
-.Dl "CVSACCOUNT Current Account 1234"
+.Dl Transaction Date,Post Date,Description,Category,Type,Amount
 .Pp
-to reflect that the account they are importing is 1234 in
-.Pa ./accounts.txt .
+Then this
+.Ar selector
+ignores the transaction date, post date, description, type, and amount.
+It matches the
+.Qq Automotive
+category and maps transactions to account
+.Qq 1111
+defined in
+.Pa ./accounts.txt
+with the
+.Qq Auto
+booking identifier.
+.Ss A sample credit card purchase
+If
+.Pa chasedownload.csv
+file contains
 .Pp
-Now suppose a line in the CSV file looks like
+.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
 .Pp
-.Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42"
+and
+.Pa ./import/chase_credit.txt
+contains
+.Bd -literal -offset Ds
+ACCOUNT 3234
+,,,Shopping,,, 9996 SHOP
+.Ed
 .Pp
-Then
+and
+.Pa ./accounts.txt
+contains
+.Bd -literal -offset Ds
+3234 L Chase credit card
+9996 X shopping
+.Ed
+.Pp
+then the
+.Qq Shopping
+category defined by Chase is mapped to the user's
+.Qq SHOP
+booking identifier, the user's account for shopping
+expenses is defined as
+.Qq 9996
+in their
+.Pa ./accounts.txt ,
+the user's account for the credit card is 3234 in their
+.Pa ./accounts.txt ,
+and
 .Nm
 prints
 .Pp
-.Dl "20201027 DEFAULTCONTRA 1234 5678 1653.2 Payment Thank You - Web"
+.Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
+.Ss A complete example
+Suppose
+.Pa ./accounts.txt
+is given by
+.Bd -literal
+1700 A My Bank
+3234 L My Chase Credit Card
+5102 X Physician expenses
+5103 X Dental expenses
+5203 X Shopping
+.Ed
 .Pp
-In this example, the user's
-.Pa ./import.txt
-has
+and
+.Pa chasedownload.csv
+is given by
+.Bd -literal
+Transaction Date,Post Date,Description,Category,Type,Amount,Memo
+11/06/2020,11/09/2020,Dr. Joseph Schmoe,Health & Wellness,Sale,-100.00,
+11/06/2020,11/09/2020,Dr. Sally Sue,Health & Wellness,Sale,-183.00,
+11/08/2020,11/08/2020,example.com,Shopping,Sale,-53.83,
+11/04/2020,11/04/2020,Payment Thank You - Web,,Payment,75.43,
+.Ed
 .Pp
-.Dl "DEFAULTCONTRA Contra 5678"
+and
+.Pa ./import/chase_credit.txt
+is given by
+.Bd -literal
+# Chase credit card header is
+# Transaction Date,Post Date,Description,Category,Type,Amount
+# The format of this file is
+# selector account_number booking_identifier
+# selector is a comma-separated list of regular expressions which
+# matches corresponding fields in the CSV file
+ACCOUNT 3234
+,,,Automotive,,, 1111 AUTO
+,,,Bills & Utilities,,, 2222 BILLS
+,,,Fees & Adjustments,,, 3333 FEES
+,,,Food & Drink,,, 4444 FOOD
+,,,Gas,,, 5555 GAS
+,,,Gifts & Donations,,, 6666 GIFTS
+,,,Groceries,,, 7777 GROCERIES
+,,Dr. Sally Sue,,,, 5103 DENTAL
+,,,Health & Wellness,,, 5102 PHYSICIAN
+,,,Home,,, 9999 HOME
+,,,Personal,,, 9998 PERSONAL
+,,,Professional Services,,, 9997 PRO
+,,,Shopping,,, 5203 SHOP
+,,,,Payment,, 1700 PAY
+.Ed
 .Pp
-to reflect that the default account used to make payments for the
-account we are importing is 5678.
+Then
+.Pp
+.Dl pta_import -I chase_credit chasedownload.csv
+.Pp
+outputs
+.Bd -literal
+20201109 PHYSICIAN 5102 3234 100.00 Dr. Joseph Schmoe
+20201109 DENTAL 5103 3234 183.00 Dr. Sally Sue
+20201108 SHOP 5203 3234 53.83 example.com
+20201104 PAY 3234 1700 75.43 Payment Thank You - Web
+.Ed
+.Pp
+Note that the selector for Dr\&. Sally Sue
+in the example configuration file comes before the
+Health & Wellness selector.
+Since the first match wins, transactions for Dr\&. Sally Sue
+can be classified with the DENTAL booking identifier,
+even though the bank's CSV file classifies
+these transactions as Health & Wellness.
 .Sh SEE ALSO
 .Xr pta-accounts 5 ,
 .Xr pta-journal 5 ,
@@ -101,7 +292,10 @@ Currently,
 has the following limitations:
 .Bl -dash
 .It
-The CVS file's first line must contain a header.
+Pattern recognition in the
+.Pa import/accountname.txt
+files is under continued development.
 .It
-Only CSV files generated by Chase Bank are supported at this time.
+User-defined configuration files are not currently
+supported.
 .El