===================================================================
RCS file: /cvs/pta/pta_import.1,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -p -r1.2 -r1.3
--- pta/pta_import.1	2020/11/01 23:07:35	1.2
+++ pta/pta_import.1	2020/11/12 13:08:13	1.3
@@ -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.3 2020/11/12 13:08:13 schwarze 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 12 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 bankFormat
 .Op Ar file
 .Sh DESCRIPTION
 The
@@ -35,62 +36,209 @@ institution into journal entries used by
 If the
 .Ar file
 argument is omitted, standard input is read instead.
+.Pp
+.Ar bankFormat
+is exactly one of
+.Bl -tag -width Ds
+.It capital_one_credit
+.It chase_credit
+.It optum_hsa
+.El
+.Pp
+and corresponds to an existing
+.Qq import_bankFormat.txt
+file in the current directory.
 .Sh FILES
-.Bl -tag -width import.txt
-.It Pa ./import.txt
-file containing account numbers associated with CSV categories
+.Bl -tag -width Ds
+.It Pa ./import_capital_one_credit.txt
+.It Pa ./import_chase_credit.txt
+.It Pa ./import_optum_hsa.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.
+.Ss Defining the account number
+Each file must contain one line beginning with
+.Qq ACCOUNT
+and is followed by whitespace and then an account number.
+The account number corresponds to the account in
+.Pa ./accounts.txt
+for the imported account.
+.Ss Patterns in the import_bankFormat.txt files
+Each file contains lines of the form
+.Pp
+.Ar selector account_number 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 A sample credit card purchase
+Suppose a line in the
+.Pa chasedownload.csv
+file looks like
 .Pp
-Suppose a line in the CSV file looks like
-.Pp
 .Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
 .Pp
-Then
-.Nm
-prints
+If the line matching the
+.Qq Shopping
+category in the user's
+.Pa ./import_chase_credit.txt
+file is
 .Pp
-.Dl "20201026 SHOP 9996 1234 17.07 example.com*asldfkj"
+.Dl ,,,Shopping,,, 9996 SHOP
 .Pp
-In this example, the user's
-.Pa ./import.txt
-contains
+then the
+.Qq Shopping
+category defined by Chase is mapped to the user's
+.Qq SHOP
+booking identifier, and the user's account for shopping
+expenses is defined as
+.Qq 9996
+in their
+.Pa ./accounts.txt .
 .Pp
-.Dl "SHOP Shopping 9996"
-.Pp
-to reflect that their expense account for shopping is 9996 in
+We further assume in this example that the user has edited
+.Pa ./import_chase_credit.txt
+so that the line beginning with
+.Qq ACCOUNT
+contains the liability account they have defined for their Chase card
+in
 .Pa ./accounts.txt
-and
 .Pp
-.Dl "CVSACCOUNT Current Account 1234"
+In this example,
+.Pa ./import_chase_credit.txt
+contains
+.Dl ACCOUNT 3234
 .Pp
-to reflect that the account they are importing is 1234 in
-.Pa ./accounts.txt .
+Then
+.Nm
+prints
 .Pp
-Now suppose a line in the CSV file looks like
-.Pp
+.Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
+.Ss A sample credit card payment
 .Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42"
 .Pp
+Suppose the user's
+.Pa ./import_chase_credit.txt
+file contains
+.Pp
+.Dl ,,,,Payment,, 1700 PAY
+.Pp
+which matches Chase's payment category to the user's asset account
+.Qq 1700
+used to pay off the credit card.
 Then
 .Nm
 prints
 .Pp
-.Dl "20201027 DEFAULTCONTRA 1234 5678 1653.2 Payment Thank You - Web"
+.Dl "20201027 PAY 3234 1700 1653.2 Payment Thank You - Web"
+.Ss Account numbers in the import_bankFormat.txt files
+For example, if
+.Pa ./import_capital_one_credit.txt
+contains
 .Pp
-In this example, the user's
-.Pa ./import.txt
-has
+.Dl ACCOUNT 1293
 .Pp
-.Dl "DEFAULTCONTRA Contra 5678"
+then there must be a corresponding entry in
+.Pa ./accounts.txt
+such as
+.Dl 1293 L Capital One credit card
 .Pp
-to reflect that the default account used to make payments for the
-account we are importing is 5678.
+The description
+.Qq Capital One credit card
+may vary, but in this example, the account numbers
+.Qq 1293
+match, and the account type is
+.Qq L
+to indicate that it is a liability account.
+.Ss Patterns in the import_bankFormat.txt files
+Suppose
+.Dl ,,,Automotive,,, 1111 AUTO
+.Pp
+is a sample entry in the
+.Pa ./import_chase_credit.txt
+file which uses headers of the form
+.Pp
+.Dl Transaction Date,Post Date,Description,Category,Type,Amount
+.Pp
+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 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
+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
+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
+Then
+.Dl pta_import -I chase_credit chasedownload.csv
+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
 .Sh SEE ALSO
 .Xr pta-accounts 5 ,
 .Xr pta-journal 5 ,
@@ -101,7 +249,22 @@ Currently,
 has the following limitations:
 .Bl -dash
 .It
-The CVS file's first line must contain a header.
+Pattern recognition in the
+.Pa import_bankFormat.txt
+files is under continued development.
 .It
-Only CSV files generated by Chase Bank are supported at this time.
+The only defined import formats are for Chase credit cards,
+Capital One credit cards, and Optum Health Savings Accounts.
+.It
+Note that the first pattern match wins in
+.Pa ./import_bankFormat.txt .
+In the complete example above, we put the line containing
+.Qq Dr. Sally Sue
+before the line matching the
+.Qq Health & Wellness
+category because we wanted to override the
+.Qq Health & Wellness
+category, and use the
+.Qq Dental expenses
+account instead.
 .El