WhisperingChaos/costshare_chase.program.sh

uses costshare.source to implement credit card cost sharing for Chase Bank

costshare_chase.program.sh

A program that implements cost sharing for Chase Bank credit card purchases.

ToC

API Index
API
Install
Test Run
License MIT

API Index

costshare_chase_category_filter_tbl

costshare_chase_purchases_exclude_specific_category_matches_tbl

costshare_chase_purchases_excluded_tbl

costshare_chase_vendor_pct_tbl

API

costshare_chase_category_filter_tbl

costshare_chase.program.sh/component/costshare.chase.source.sh

Lines 120 to 147 in c9595b2

	###############################################################################
	##
	## Purpose
	## Defines a table whose rows select purchases based on Chase Bank
	## Category descriptions which suggest they should be
	## included in cost sharing. However, there will be purchases
	## assigned a cost sharing category that should instead be excluded.
	## The matching semantics of a grep --fix-string match is
	## performed using the contents of this table on the Chase Bank
	## credit card CSV input stream.
	## Why
	## Helps to eliminate calculation errors by including only those purchases
	## likely to be shared while excluding ones that should never be considered.
	## Also, it performs this search on the Chase CSV formatted purchases and
	## this format's semantics before these purchases are conveted to a different
	## format whose semantics are devoid of the category concept.
	## Format
	## Must conform to:
	##
	## ,<Category>,
	##
	## Category - (required) any Chase Bank descriptive category extracted from
	## their CSV stream fed into this program. The leading and trailing
	## commas better ensure match semantics will only consider the
	## contents of the category field in the CSV stream, as hopefully,
	## a category description/name doesn't match the full name of a
	## purchase vendor/description field.
	###############################################################################

This table must contain at least one category entry. It must exist in the "override" directory specified as an argument to this program.

Example

Table Contents

costshare_chase_purchases_exclude_specific_category_matches_tbl

costshare_chase.program.sh/component/costshare.chase.source.sh

Lines 151 to 174 in c9595b2

	###############################################################################
	##
	## Purpose
	## Define a table to exclude specific purchases that are incorrectly included
	## in cost sharing when applying the Chase Bank category table rows.
	## The matching semantics of a grep --fix-string match are performed using
	## the contents of this table on the Chase Bank credit card CSV input stream.
	## Why
	## Helps to eliminate cost sharing errors by excluding only those purchases
	## that should never be considered.
	## Also, it performs this search on the Chase CSV formatted purchases and
	## their semantics before these purchases are conveted to a different
	## format whose semantics are devoid of the category concept.
	## Format
	##
	## <Transaction Date>,<Post Date>,<Description>,<Category>,<Type>,<Amount>,<Memo>
	##
	## A row in the table must contain the minimal portion of a Chase Bank CSV
	## purchase entry that matches the purchase(s) that must be excluded
	## without affecting any purchase that must be included. The easiest method
	## is to add a row in the table that exactly matches the corresponding entry
	## in the Chase Bank input stream. This ensures that this row will only
	## affect that specific entry in the input stream.
	###############################################################################

This table may be empty. It must exist in the "override" directory specified as an argument to this program. ##### Example Not Available

costshare_chase_purchases_excluded_tbl

costshare_chase.program.sh/component/costshare.chase.source.sh

Lines 85 to 116 in c9595b2

	###############################################################################
	##
	## This content is copied from:
	## https://github.com/WhisperingChaos/costshare.source.sh/blob/main/component/costshare.source.sh
	## for convienence. It should always be the same. Please replace the description
	## below with the authorative one from URL above if the below differs.
	##
	## Purpose
	## Excludes purchases normally included by "costshare_vendor_pct_tbl".
	## Each CSV formatted row can define a regex pattern for each input field.
	## Why
	## There may be purchases involving a vendor that are typically shared
	## but in certain cases aren't.
	## Format
	## Must conform to CSV format:
	##
	## [<Vendor Name>][,<Date>|,][,<Charge>]
	##
	## Vendor Name - (optional) extended regex.
	## Date - (optional) extended regex.
	## Charge - (optional) extended regex.
	##
	## At least one of the above fields must be specified.
	## When combined, the regex of these fields identify the purchase(s)
	## to specifically exclude.
	##
	## Omit a field from matching by either leaving it entirely empty or by
	## specifing an empty value using a pair of double quotes (""). If an
	## empty value is specified, a comma must terminate the field if a value
	## is specified for a subsequent field.
	##
	###############################################################################

This table may be empty. It must exist in the "override" directory specified as an argument to this program.

Example

Table Contents.

costshare_chase_vendor_pct_tbl

costshare_chase.program.sh/component/costshare.chase.source.sh

Lines 32 to 81 in c9595b2

	###############################################################################
	##
	## This is the authoritative content which should be reflected by the
	## corresponding version found on the main branch:
	## https://github.com/WhisperingChaos/costshare.source.sh/blob/main/component/costshare.source.sh
	## Please update the referenced github description if the below differs.
	##
	## Purpose
	## Defines the vendor percentage table used to filter and calculate the
	## share amount of a purchase owed between two parties: Party 'X' and
	## Party 'Y'.
	##
	## Filtering selects only those purchases whose Vendor Names appear in
	## this table. A "grep" "fixed string" comparision is performed between
	## each Vendor Name in this table and the one appearing in a purchase. If
	## the fixed string comparison succeeds, the purchase is selected for
	## further processing. Note, fixed string evaluation compares all characters
	## according to their character values, therefore, a character's case
	## affects the comparison outcome and regular expressions are unsupported.
	## Why
	## Automates the process of filtering the purchases and calculating
	## what each party owes.
	## Format
	## Must conform to CSV format:
	##
	## <Vendor Name>,<Party 'X' Percentage>
	##
	## Must use double quotes to encapsulate Vendor Name when it contains
	## the CSV delimiter characters: double quotes or commas.
	## Whitespace can be used to visually align the column values. Whitespace
	## will be eliminated from each side of a field value. Also, repeated,
	## embedded whitespace will be replaced by a single "space" character.
	## Constraints
	## Vendor Name
	## - Must be capitalized in the same manner as specified by purchases.
	## - A partial vendor name can be specified. However, it must be long
	## enough to uniquely assign the proper percentage that should be paid
	## by Party 'X'. The algorithm selects the percentage
	## associated to the longest matching vendor name before considering
	## shorter ones that share the same first whole word (root word).
	## - A root word must be at least 3 characters long.
	## - A vendor name will be truncated to 'costshare_VENDOR_NAME_LENGTH_MAX'
	## to prevent exploitation/bugs.
	## Party 'X' Percentage
	## - The percentage of the total charge to be paid by Party 'X'.
	## - The share paid by Party 'Y' is the amount that remains after deducting
	## the amount owed by Party 'X'.
	## - Must be a whole number that ranges: 0-100.
	##
	###############################################################################

Example

Table Contents

Install

• git clone to copy entire project contents including its git repository. Obtains current master which may include untested features. To synchronize the working directory to reflect the desired release, use git checkout tags/<tag_name>.
• wget https://github.com/whisperingchaos/costshare.source.sh/tarball/master creates a tarball that includes only the project files without the git repository. Obtains current master branch which may include untested features.
• Since this program is composed from a number of components, it must be "configured" in order to download it's dependencies.

> cd program
> ./config.sh

Once the above successfully finishes, all the program's static dependencies have been downloaded and installed to the proper subdirectories in "program/costshare_chase_program_sh".

SOLID Composition

TODO

How to override a callback function.

Depends on

• GNU bash, version 4.3.48(1)-release. This component relies on nameref/name reference feature introduced in version 4.3.
• The Bash components listed in its vendor.config

Test

After installing, change directory to costshare_chase.program.sh's test. Then run:

• >./config.sh followed by
• ./test_costshare_chase.program.sh. It should complete successfully and not produce any messages.

> ~/Desktop/projects/test_costshare_chase.program.sh/test$ ./costshare.source_test.sh
> ~/Desktop/projects/test_costshare_chase.program.sh/test$ 

Run

Usage: ChaseCCcsv | costshare_chase.program.sh [Option] OverrideComponentDir

Filter Chase Credit Card transactions then compute amount owed between
two parties which agreed to share the cost.

Option:
    -h,--help     Display this help text and exit.

Argument:

OverrideComponentDir:
    Interface functions detailed in the source code comments of 
    costshare_chase.source.sh must be overriden to specify certain
    filtering features that select or exclude credit card
    transactions as well as defining the percentage to be paid by
    one party for specific vendor charges appearing in the credit
    card description field.  You must read these comments and provide
    function bodies that provide the data in the required format.

    When defining these interface functions, create one or more
    bash source files adhering to the following naming convention:
    <namespace>'.source.sh' where <namespace> can be nearly any
    name, however, suggest using "costshare_chase".  Save this file
    to a subdirectory named "override" in any parent directory
    except the one containing this program.  Finally, when running
    this program, specify the name of the parent directory as the
    value of this argument.   
    
Input:

STDIN: ChaseCCcsv -
  Downloaded Chase Credit Card transactions formatted as Comma
  Separated Values (CSV).  Logon to Chase then use the search transaction
  feature to select the desired transaction period.  Once selected,
  export them in CSV format which downloads them to the current
  connected device.

  This CSV format should adhere to (as of 02/28/2022):

  <Transaction Date>,<Post Date>,<Description>,<Category>,<Type>,<Amount>[,forwardedFields]

  Transaction Date
              - MM/DD/YYYY. The purchase date.
  Post Date   - MM/DD/YYYY. The date the purchase was applied to the credit card account.
  Description - A string of characters that describes the purchased item.  The description
                contains the name of the vendor (company) that sold the item.  It
                also usually describes the item's type/product name.
  Category    - A value generated by Chase that groups similar items.
  Type        - A value specified by Chase that classifies the transaction as either a
                "Sale", "Return", "Payment", or perhaps others.  This program only considers
                "Sale" and "Return" transaction types
  ,forwardedFields
              - (optional) Additional data, not necessarily in CSV format, that's preserved
                and will appear in the generated output.  This additional data can, for
                instance, contain a unique id.  This unique id can be used to definitively
                correlate the generated output to this process' input.       
 
Output:

STDOUT - newline delimited CSV records with format:

  <Transaction Date>,<Vendor Name>,<Charge>,<PartyXpct>,<SharePartyXRound>,<SharePartyY>,Category,Type[,forwardedFields]

  Transaction Date
              - MM/DD/YYYY. The purchase date.
  Vendor Name - A.K.A Description. Vendor can contain
                any character value. It will also be normalized:
                whitespace appearing before the first non-whitespace
                character and those appearing after the last
                non-whitespace character are removed.  Also,
                repeating whitespace embedded inside a name are
                replaced by a single "space" character.
  Charge      - Will either be a whole number or a
                decimal number with 2 places of accuracy to right
                of decimal point.  It can be prefix by a sign(+-).
  PartyXpct   - Party 'X' percentage applied to the charge
  SharePartyXRound
              - Calculated Party 'X' portion of the charge
                rounded using "unbaised/bankers" rounding method.
  SharePartyY - Calculated Party 'Y' portion of the charge.  Party
                'Y''s portion represents the remainder of the charge
                afer subtracting the total transaction charge by
                the portion owed by Party 'X'.
  ,forwardedFields
              - See STDIN.

cd program cat MarchCreditCardSatement.cvs | ./costshare_chase.program.sh ./