I've posted a new workspace today. TB is not a library. It is an application, and my hope is to demonstrate how I use some of the libraries here.
My objective is to provide generally useful libraries that expand the functionality of APL.
TB stands for trial balance, a tool accountants use at the end of the year to summarize and adjust financial records. My workspace lets you produce a trial balance and adjust it by loading exampleSession. Each entry is displayed as it is entered, and a final adjusted trial balance is displayed at the end.
Here I set out the axioms of accounting so as to make some sense of all this and of how I've used the libraries here.
Axiom 1. The basic accounting equation is Assets = Labilities + Equity.
Assets are things that one owns. Labilities are what must be paid out to third parties from those assets. Equity equals assets minus liabilities, or what’s left over for the owners.
The first report of the example session is a chart of accounts, which is just a list of categories. Following the account title is a two-character code. The first is B, R, or I, and the second either D or C. D and C come into play for axiom 2.
B stands for balance sheet, R for retained earnings, and I for income. Both R and I are parts of equity. B, the balance sheet, represents the assets (B, D) and liabilities (B, C).
The balance sheet is so named because it demonstrates this equation. We group all assets and add them up; group all liabilities and add them; and calculate equity to show that our calculations satisfy axiom 1.
Axiom 2. Debits = Credits
Debits (Dr) and credits (Cr) are two categories of entries in the books and records. They are opposite in sign, so that 50 Dr + 50 Cr = 0. They are not intrinsically positive and negative, although some accounting software displays them as such. Assets have a debit balance; liabilities and equity have a credit balance.
Every entry consists of at least one debit and one credit. The total debits must equal the total credits.
This whole system of debits and credits simplifies the classification and summary process. First we make an entry to reflect a particular transaction:
We sell four widgets for a total of $250 payable in 30 days. The effect of the sale is to increase accounts receivable (an asset) and sales (a component of equity). Our entry:
t1←TB_doc_create 'gj' 'sales' '12/31/2017' 'To record sale of 4 widgets'
t1←t1 TB_doc_debit 1110 250
t1←t1 TB_doc_credit 5010 250
TB_doc_show t1
Example Company
Journal Entry gj sales TB workspace
12/31/2017 03/16/2018
1110 Accounts Receivable 250.00 0.00
5010 Sales 0.00 250.00
Total 250.00 250.00
To record sale of 4 widgets
At this point we don't know what amounts are owed to us by our customers (accounts receivable), nor do we know our sales; just the effect of our transaction.
In the process of preparing a trial balance, we sort these lines by account and then calculate the net (total debits less total credits) and assign the difference based on the larger amount. This process is repeated for each item in our chart of accounts. Until we have the trial balance, we don't try to make sense of the debits and credits; we just pound away at the calculator.
The adjusted trial balance (the last command in exampleSession, ⍞←wp∆txt∆assemble TB_trialbalance_adj) demonstrates this process. The first two columns (one debit and one credit) are the beginning balance. The next two list all adjustments, and the final two show our calculation of the closing balances. By tradition, debits are listed on the left and credits on the right.
A guide to exampleSession
The exampleSession workspace goes through five phases:
Prepare the workspace.
Define and set up the chart of accounts.
Enter the opening balances.
Enter adjustments.
Prepare the trial balance.
Prepare the workspace
Function TB_init sets up all of the global variables where we will store our data. It has three items: the name of the company, the last day of its fiscal year, and the account number of retained earnings.
TB_init also adds the required account retained earnings.
Define and set up the chart of accounts
TB_acct_add adds an account to the chart of accounts. Each account has four attributes:
The account number
The account title
one of B, R, or I (for balance sheet, retained earnings, and income)
one of D or C (for debit or credit)
We close this section with TB_acct_chart, which displays a list of the accounts.
Enter the opening balances
The accountant obtains this report from the client. Most accounting software will print it into an Excel file. In our example we enter it using the TB_doc functions. If we had a delimited disk file, we could import the data using TB_import_delimited.
We close this section with a report on the entry we've made using TB_doc_show.
Enter Adjustments
This section includes seven summary adjustments. Each adjustment follows the same procedure: make the journal entry, add debits and credits, display the entry, and post the entry.
TB_doc_create journal entry_name entry_date entry_description returns a document (or entry to the books).
TB_doc_debit and TB_doc_credit add lines to the document assigning the debit or credit to an account.
TB_doc_show displays the entry and can be executed multiple times (at least until the entry is right).
TB_doc_post adds the data to the database.
Prepare the trial balance
TB_trialbalance and TB_trialbalance_adj prepare trial balances. The first just shows the closing balance for each account, while the second shows the calculation.
Both functions return a workpaper (see the wp library) and we must use wp∆assemble or wp∆txt∆assemble to get a readable report.
Libraries
util
util is a collection of functions that are generally useful. I find the one I use the most is util∆helpFns, which will return the definition of the function as well as comments at the top of the function.
lex
lex, or lexicon, is a system to use arrays with text indices rather than numbers. APL library has several versions of this idea using different storage and retrieval schemes.
TB_config is a lexicon. Several functions will take a lexicon as an argument.
wp
wp, or workpaper, is a lexicon for preparing a report from the elements of the report. A workpaper should have an entity saying for whom the report is prepared, a title, and other general information.
I've used wp for the reports in this application. TB_doc_workpaper, TB_trialbalance, and TB_trialbalance_adj all return a workpaper. wp∆txt∆assemble will return the report.
The last line of exampleSession:
`⍞←wp∆txt∆assemble TB_trialbalance_adj`
import
import provides routines for extracting an array from a delimited file. TB_import_delimited calls on this library to import a beginning trial balance from other applications.
prompt
prompt requests user input. It is an implementation of a design pattern to use the keywords quit, top, done, and back for navigation during data entry.
TB_select uses the library prompt.
xml
xml comprises tools to build xml files.
TB uses a collection of html functions generated by xml to display a workpaper inside a web browser.
These letters will be lowercase in the actual trial balance; they are capped here for clarity as you read.
Last edit: Bill Daly 2018-03-20
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Blog on Posting TB
I've posted a new workspace today. TB is not a library. It is an application, and my hope is to demonstrate how I use some of the libraries here.
My objective is to provide generally useful libraries that expand the functionality of APL.
TB stands for trial balance, a tool accountants use at the end of the year to summarize and adjust financial records. My workspace lets you produce a trial balance and adjust it by loading exampleSession. Each entry is displayed as it is entered, and a final adjusted trial balance is displayed at the end.
Here I set out the axioms of accounting so as to make some sense of all this and of how I've used the libraries here.
Axiom 1. The basic accounting equation is Assets = Labilities + Equity.
Assets are things that one owns. Labilities are what must be paid out to third parties from those assets. Equity equals assets minus liabilities, or what’s left over for the owners.
The first report of the example session is a chart of accounts, which is just a list of categories. Following the account title is a two-character code. The first is B, R, or I, and the second either D or C. D and C come into play for axiom 2.
B stands for balance sheet, R for retained earnings, and I for income. Both R and I are parts of equity. B, the balance sheet, represents the assets (B, D) and liabilities (B, C).
The balance sheet is so named because it demonstrates this equation. We group all assets and add them up; group all liabilities and add them; and calculate equity to show that our calculations satisfy axiom 1.
Axiom 2. Debits = Credits
Debits (Dr) and credits (Cr) are two categories of entries in the books and records. They are opposite in sign, so that 50 Dr + 50 Cr = 0. They are not intrinsically positive and negative, although some accounting software displays them as such. Assets have a debit balance; liabilities and equity have a credit balance.
Every entry consists of at least one debit and one credit. The total debits must equal the total credits.
This whole system of debits and credits simplifies the classification and summary process. First we make an entry to reflect a particular transaction:
We sell four widgets for a total of $250 payable in 30 days. The effect of the sale is to increase accounts receivable (an asset) and sales (a component of equity). Our entry:
t1←TB_doc_create 'gj' 'sales' '12/31/2017' 'To record sale of 4 widgets' t1←t1 TB_doc_debit 1110 250 t1←t1 TB_doc_credit 5010 250 TB_doc_show t1 Example Company Journal Entry gj sales TB workspace 12/31/2017 03/16/2018 1110 Accounts Receivable 250.00 0.00 5010 Sales 0.00 250.00 Total 250.00 250.00 To record sale of 4 widgetsAt this point we don't know what amounts are owed to us by our customers (accounts receivable), nor do we know our sales; just the effect of our transaction.
In the process of preparing a trial balance, we sort these lines by account and then calculate the net (total debits less total credits) and assign the difference based on the larger amount. This process is repeated for each item in our chart of accounts. Until we have the trial balance, we don't try to make sense of the debits and credits; we just pound away at the calculator.
The adjusted trial balance (the last command in exampleSession, ⍞←wp∆txt∆assemble TB_trialbalance_adj) demonstrates this process. The first two columns (one debit and one credit) are the beginning balance. The next two list all adjustments, and the final two show our calculation of the closing balances. By tradition, debits are listed on the left and credits on the right.
A guide to exampleSession
The exampleSession workspace goes through five phases:
Prepare the workspace
Function TB_init sets up all of the global variables where we will store our data. It has three items: the name of the company, the last day of its fiscal year, and the account number of retained earnings.
TB_init also adds the required account retained earnings.
Define and set up the chart of accounts
TB_acct_add adds an account to the chart of accounts. Each account has four attributes:
We close this section with TB_acct_chart, which displays a list of the accounts.
Enter the opening balances
The accountant obtains this report from the client. Most accounting software will print it into an Excel file. In our example we enter it using the TB_doc functions. If we had a delimited disk file, we could import the data using TB_import_delimited.
We close this section with a report on the entry we've made using TB_doc_show.
Enter Adjustments
This section includes seven summary adjustments. Each adjustment follows the same procedure: make the journal entry, add debits and credits, display the entry, and post the entry.
TB_doc_create journal entry_name entry_date entry_description returns a document (or entry to the books). TB_doc_debit and TB_doc_credit add lines to the document assigning the debit or credit to an account. TB_doc_show displays the entry and can be executed multiple times (at least until the entry is right). TB_doc_post adds the data to the database.Prepare the trial balance
TB_trialbalance and TB_trialbalance_adj prepare trial balances. The first just shows the closing balance for each account, while the second shows the calculation.
Both functions return a workpaper (see the wp library) and we must use wp∆assemble or wp∆txt∆assemble to get a readable report.
Libraries
util
util is a collection of functions that are generally useful. I find the one I use the most is util∆helpFns, which will return the definition of the function as well as comments at the top of the function.
lex
lex, or lexicon, is a system to use arrays with text indices rather than numbers. APL library has several versions of this idea using different storage and retrieval schemes.
TB_config is a lexicon. Several functions will take a lexicon as an argument.
wp
wp, or workpaper, is a lexicon for preparing a report from the elements of the report. A workpaper should have an entity saying for whom the report is prepared, a title, and other general information.
I've used wp for the reports in this application. TB_doc_workpaper, TB_trialbalance, and TB_trialbalance_adj all return a workpaper. wp∆txt∆assemble will return the report.
The last line of exampleSession:
import
import provides routines for extracting an array from a delimited file. TB_import_delimited calls on this library to import a beginning trial balance from other applications.
prompt
prompt requests user input. It is an implementation of a design pattern to use the keywords quit, top, done, and back for navigation during data entry.
TB_select uses the library prompt.
xml
xml comprises tools to build xml files.
TB uses a collection of html functions generated by xml to display a workpaper inside a web browser.
These letters will be lowercase in the actual trial balance; they are capped here for clarity as you read.
Last edit: Bill Daly 2018-03-20