From bc8ad8961a0158b483c87032ee0367bc47f313fa Mon Sep 17 00:00:00 2001 From: Christopher Lam Date: Wed, 7 Feb 2018 23:13:58 +0800 Subject: [PATCH] TR & GSTReport: Improve comments This commit only improves the comments for both reports, and uses gnc:error calls as advised. The reordering in GST Report now reflects the logical transformation of a split into column amount. --- .../standard-reports/income-gst-statement.scm | 29 ++++++---- .../report/standard-reports/transaction.scm | 53 +++++++++++++------ 2 files changed, 57 insertions(+), 25 deletions(-) diff --git a/gnucash/report/standard-reports/income-gst-statement.scm b/gnucash/report/standard-reports/income-gst-statement.scm index e3386434aa..6396db109e 100644 --- a/gnucash/report/standard-reports/income-gst-statement.scm +++ b/gnucash/report/standard-reports/income-gst-statement.scm @@ -58,11 +58,14 @@ accounts must be of type ASSET for taxes paid on expenses, and type LIABILITY fo (not (xaccTransGetIsClosingTxn trans))))) (define (gst-statement-options-generator) + ;; Retrieve the list of options specified within the transaction report (define options (trep-options-generator)) - ;; Delete Accounts selector and recreate with limited account types + ;; Delete Accounts selector (gnc:unregister-option options gnc:pagename-accounts (N_ "Accounts")) + + ;; and recreate with limited account types (gnc:register-option options (gnc:make-account-list-limited-option @@ -125,8 +128,8 @@ for taxes paid on expenses, and type LIABILITY for taxes collected on sales.") (amount (+ (gnc:gnc-monetary-amount a) (gnc:gnc-monetary-amount b)))) (if same-currency? (gnc:make-gnc-monetary (gnc:gnc-monetary-commodity a) amount) - (warn "incompatible currencies in monetary+: " a b))) - (warn "wrong arguments for monetary+: " a b)))) + (gnc:error "incompatible currencies in monetary+: " a b))) + (gnc:error "wrong arguments for monetary+: " a b)))) (myadd (lambda (X Y) (if X (if Y (monetary+ X Y) X) Y))) ; custom adder which understands #f values (myneg (lambda (X) (and X (gnc:monetary-neg X)))) ; custom monetary negator which understands #f (accounts (opt-val gnc:pagename-accounts "Accounts")) @@ -140,14 +143,22 @@ for taxes paid on expenses, and type LIABILITY for taxes collected on sales.") (split-date (lambda (s) (xaccTransGetDate (xaccSplitGetParent s)))) (split-currency (lambda (s) (xaccAccountGetCommodity (xaccSplitGetAccount s)))) (split-adder (lambda (split accountlist) - (let* ((transaction (xaccSplitGetParent split)) + (let* (;; 1. from split, get the trans + (transaction (xaccSplitGetParent split)) + ;; 2. from trans, get all splits (splits-in-transaction (xaccTransGetSplitList transaction)) + ;; 3. but only from accounts specified + (include-split? (lambda (s) (member (xaccSplitGetAccount s) accountlist))) + (filtered-splits (filter include-split? splits-in-transaction)) + ;; 4. get the filtered split amount (split-get-monetary (lambda (s) (gnc:make-gnc-monetary (split-currency s) (if (xaccTransGetVoidStatus transaction) (xaccSplitVoidFormerAmount s) (xaccSplitGetAmount s))))) + ;; 5. amount - always convert to + ;; either report currency or the original split currency (split-monetary-converted (lambda (s) (gnc:exchange-by-pricedb-nearest (split-get-monetary s) @@ -155,8 +166,6 @@ for taxes paid on expenses, and type LIABILITY for taxes collected on sales.") (split-currency split)) (time64CanonicalDayTime (split-date s))))) - (include-split? (lambda (s) (member (xaccSplitGetAccount s) accountlist))) - (filtered-splits (filter include-split? splits-in-transaction)) (list-of-values (map split-monetary-converted filtered-splits))) (fold myadd #f list-of-values)))) (account-adder (lambda (acc) (lambda (s) (split-adder s (list acc))))) @@ -177,10 +186,10 @@ for taxes paid on expenses, and type LIABILITY for taxes collected on sales.") ;; each column will be a vector ;; (vector heading ;; calculator-function ;; (calculator-function split) to obtain amount - ;; reverse-column? ;; to optionally reverse signs - ;; subtotal? ;; subtotal? to allow subtotals (ie irrelevant for running balance) - ;; start-dual-column? ;; #t for the left side of a dual column (i.e. debit/credit) - ;; friendly-heading-fn ;; retrieve friendly heading name for account debit/credit + ;; reverse-column? ;; unused in GST report + ;; subtotal? ;; #t - all columns need subtotals + ;; start-dual-column? ;; unused in GST report + ;; friendly-heading-fn ;; unused in GST report (list (vector "TOTAL SALES" total-sales #t #t #f diff --git a/gnucash/report/standard-reports/transaction.scm b/gnucash/report/standard-reports/transaction.scm index b94ce09d50..1e4e5232c3 100644 --- a/gnucash/report/standard-reports/transaction.scm +++ b/gnucash/report/standard-reports/transaction.scm @@ -397,6 +397,8 @@ Credit Card, and Income accounts.")) (gnc:option-set-value (gnc:lookup-option options pagename-sorting optname-prime-sortkey) 'reconciled-status) (gnc:option-set-value (gnc:lookup-option options pagename-sorting optname-sec-sortkey) 'date) (gnc:option-set-value (gnc:lookup-option options pagename-sorting optname-sec-date-subtotal) 'none) + ;; the start date should really be the last-reconcile-date but this information is not + ;; easily accessible from scheme: (gnc:option-set-value (gnc:lookup-option options gnc:pagename-general optname-startdate) (cons 'relative 'start-prev-quarter)) (gnc:option-set-value (gnc:lookup-option options gnc:pagename-general optname-enddate) (cons 'relative 'today)) (gnc:option-set-value (gnc:lookup-option options gnc:pagename-display (N_ "Reconciled Date")) #t) @@ -414,6 +416,15 @@ Credit Card, and Income accounts.")) (define (gnc:register-trep-option new-option) (gnc:register-option options new-option)) + ;; (Feb 2018) Note to future hackers - this trep-options-generator + ;; defines a long set of options to be assigned as an object in + ;; the report. This long list (52 at Feb 2018 count) of options + ;; may be modified in a derived report (see income-gst-statement.scm) + ;; via gnc:make-internal! and gnc-unregister-option to hide + ;; and remove options, respectively. If an option is unregistered, + ;; don't forget to re-register them via gnc:register-option, unless + ;; your derived report truly does not require them. + ;; General options (gnc:options-add-date-interval! @@ -550,8 +561,6 @@ tags within description, notes or memo. ") (gnc-option-db-set-option-selectable-by-name options gnc:pagename-accounts optname-filterby (not (eq? x 'none)))))) - ;; - ;; Sorting options @@ -870,10 +879,14 @@ tags within description, notes or memo. ") gnc:pagename-display (N_ "Sign Reverses") "m1" (_ "Reverse amount display for certain account types.") 'global - (keylist->vectorlist sign-reverse-list))) + (keylist->vectorlist sign-reverse-list)))) - (gnc:register-trep-option - (gnc:make-internal-option "__trep" "unique-transactions" #f))) + ;; this hidden option will toggle whether the default + ;; qof-query is run, or a different query which ensures + ;; no transaction is duplicated. It can be enabled in + ;; a derived report (eg income-gst-statement.scm) + (gnc:register-trep-option + (gnc:make-internal-option "__trep" "unique-transactions" #f)) (gnc:options-set-default-section options gnc:pagename-general) options) @@ -887,7 +900,7 @@ tags within description, notes or memo. ") (let ((option (gnc:lookup-option options section name))) (if option (gnc:option-value option) - (error (format #f "cannot find ~a ~a" section name))))) + (gnc:error "gnc:lookup-option error: " section "/" name)))) (define BOOK-SPLIT-ACTION (qof-book-use-split-action-for-num-field (gnc-get-current-book))) (define (build-columns-used) @@ -1114,11 +1127,11 @@ tags within description, notes or memo. ") ;; each column will be a vector ;; (vector heading ;; calculator-function ;; (calculator-function split) to obtain amount - ;; reverse-column? ;; to optionally reverse signs - ;; subtotal? ;; subtotal? to allow subtotals (ie irrelevant for running balance) - ;; start-dual-column? ;; #t for the left side of a dual column (i.e. debit/credit) - ;; ;; which means the next column will be the right side - ;; friendly-heading-fn ;; retrieve friendly heading name for account debit/credit + ;; reverse-column? ;; #t to allow reverse signs + ;; subtotal? ;; #t to allow subtotals (ie must be #f for running balance) + ;; start-dual-column? ;; #t for the debit side of a dual column (i.e. debit/credit) + ;; ;; which means the next column must be the credit side + ;; friendly-heading-fn ;; (friendly-heading-fn account) to retrieve friendly name for account debit/credit (if (column-uses? 'amount-single) (list (vector (header-commodity (_ "Amount")) amount #t #t #f @@ -1604,6 +1617,13 @@ tags within description, notes or memo. ") (define* (trep-renderer report-obj #:key custom-calculated-cells empty-report-message custom-split-filter) + ;; the trep-renderer is a define* function which, at minimum, takes the report object + ;; + ;; the optional arguments are: + ;; #:custom-calculated-cells - a list of vectors to define customized data columns + ;; #:empty-report-message - a str which is displayed at the initial report opening + ;; #:custom-split-filter - a split->bool function to add to the split filter + (define options (gnc:report-options report-obj)) (define (opt-val section name) (gnc:option-value (gnc:lookup-option options section name))) (define BOOK-SPLIT-ACTION (qof-book-use-split-action-for-num-field (gnc-get-current-book))) @@ -1732,10 +1752,12 @@ tags within description, notes or memo. ") document (gnc:html-make-no-account-warning report-title (gnc:report-id report-obj))) - (and empty-report-message - (gnc:html-document-add-object! - document - empty-report-message))) + ;; if an empty-report-message is passed by a derived report to + ;; the renderer, display it here. + (if empty-report-message + (gnc:html-document-add-object! + document + empty-report-message))) (if (member 'no-match infobox-display) (gnc:html-document-add-object! @@ -1777,6 +1799,7 @@ tags within description, notes or memo. ") ;; Combined Filter: ;; - include/exclude splits to/from selected accounts ;; - substring/regex matcher for Transaction Description/Notes/Memo + ;; - custom-split-filter, a split->bool function for derived reports ;; - by reconcile status (set! splits (filter (lambda (split)