Difference between revisions of "User:Yawaramin"

From GnuCash
Jump to: navigation, search
(Generalise description of this page)
Line 1: Line 1:
 
== GnuCash Scheme Report API ==
 
== GnuCash Scheme Report API ==
  
−
I'm trying to figure out the GnuCash API for reports by examining the
+
I'm trying to figure out the GnuCash API for reports by examining the GnuCash and Scheme module sources, report sources and the reports they produce one by one.
−
GnuCash and Scheme module sources, report sources and the reports they
 
−
produce one by one.
 
  
−
This document is mostly the result of my educated guesses. Everyone please feel
+
This document is mostly the result of my educated guesses. Everyone please feel free to change anything that's inaccurate, and move it to a more appropriate place if needed. I just started tonight (5 Sep 2009) so it's definitely a work in progress right now.
−
free to change anything that's inaccurate, and move it to a more appropriate
 
−
place if needed. I just started tonight (5 Sep 2009) so it's definitely a work
 
−
in progress right now.
 
  
 
All identifiers are in alphabetical order ignoring case and non-alphanumeric
 
All identifiers are in alphabetical order ignoring case and non-alphanumeric
Line 14: Line 9:
  
 
=== Defined Variables ===
 
=== Defined Variables ===
−
----
+
 
 
==== gnc:pagename-accounts ====
 
==== gnc:pagename-accounts ====
 +
 
The name of the accounts page (tab) in the options dialog box
 
The name of the accounts page (tab) in the options dialog box
  
 
==== gnc:pagename-general ====
 
==== gnc:pagename-general ====
 +
 
The name of the general page (tab) in the options dialog box
 
The name of the general page (tab) in the options dialog box
  
 
=== Procedures ===
 
=== Procedures ===
−
----
+
 
 
==== gnc-account-get-children ====
 
==== gnc-account-get-children ====
−
'''Returns:''' A list of immediate children accounts of the given account; not
+
 
−
all descendents. For that, see ''gnc-account-get-descendants-sorted''
+
'''Returns:''' A list of immediate children accounts of the given account; not all descendents. For that, see ''gnc-account-get-descendants-sorted''
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 31: Line 28:
  
 
==== gnc-account-get-descendants-sorted ====
 
==== gnc-account-get-descendants-sorted ====
 +
 
'''Returns:''' The descendants of the given account
 
'''Returns:''' The descendants of the given account
  
Line 37: Line 35:
  
 
==== gnc-account-get-full-name ====
 
==== gnc-account-get-full-name ====
 +
 
'''Returns:''' The full name of an account
 
'''Returns:''' The full name of an account
  
Line 43: Line 42:
  
 
==== gncAccountGetGUID ====
 
==== gncAccountGetGUID ====
 +
 
'''Returns:''' The GUID of an account
 
'''Returns:''' The GUID of an account
  
Line 49: Line 49:
  
 
==== gnc:accounts-count-splits ====
 
==== gnc:accounts-count-splits ====
 +
 
'''Returns:''' The number of splits across all the given accounts
 
'''Returns:''' The number of splits across all the given accounts
  
Line 55: Line 56:
  
 
==== gnc:accounts-get-all-subaccounts ====
 
==== gnc:accounts-get-all-subaccounts ====
 +
 
'''Returns:''' List of subaccounts of an account
 
'''Returns:''' List of subaccounts of an account
  
Line 61: Line 63:
  
 
==== gnc:case-exchange-fn ====
 
==== gnc:case-exchange-fn ====
 +
 
'''Returns:''' A currency exchange calculator function
 
'''Returns:''' A currency exchange calculator function
  
Line 69: Line 72:
  
 
==== gnc:date-option-absolute-time ====
 
==== gnc:date-option-absolute-time ====
 +
 
Converts a date option value to absolute Unix epoch time
 
Converts a date option value to absolute Unix epoch time
  
−
'''Returns:''' A date/time object in absolute time (i.e. from the start of the
+
'''Returns:''' A date/time object in absolute time (i.e. from the start of the Unix epoch)
−
Unix epoch)
 
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 78: Line 81:
  
 
==== gnc:filter-accountlist-type ====
 
==== gnc:filter-accountlist-type ====
 +
 
'''Returns:''' A list of accounts filtered by their type
 
'''Returns:''' A list of accounts filtered by their type
  
 
'''Arguments:'''
 
'''Arguments:'''
−
* A list of account types to filter by. Accepts, among others: ACCT-TYPE-BANK
+
* A list of account types to filter by. Accepts, among others: ACCT-TYPE-BANK ACCT-TYPE-CASH ACCT-TYPE-ASSET ACCT-TYPE-STOCK ACCT-TYPE-MUTUAL
−
ACCT-TYPE-CASH ACCT-TYPE-ASSET ACCT-TYPE-STOCK ACCT-TYPE-MUTUAL
 
 
* A list of accounts
 
* A list of accounts
 +
 +
==== gnc-get-current-book ====
 +
 +
'''Returns:''' The currently-open GnuCash Book.
  
 
==== gnc-get-current-root-account ====
 
==== gnc-get-current-root-account ====
 +
 
'''Returns:''' The root account of the book that is currently open
 
'''Returns:''' The root account of the book that is currently open
  
 
==== gnc:gnc-monetary-amount ====
 
==== gnc:gnc-monetary-amount ====
 +
 
'''Returns:''' The amount of a Gnc-Monetary object
 
'''Returns:''' The amount of a Gnc-Monetary object
  
Line 97: Line 106:
  
 
==== gnc:html-document-set-title! ====
 
==== gnc:html-document-set-title! ====
 +
 
'''Arguments:'''
 
'''Arguments:'''
 
* The HTML document object
 
* The HTML document object
Line 102: Line 112:
  
 
==== gnc:lookup-option ====
 
==== gnc:lookup-option ====
 +
 
'''Returns:''' The actual option object (not its value)
 
'''Returns:''' The actual option object (not its value)
  
Line 110: Line 121:
  
 
==== gnc:make-commodity-collector ====
 
==== gnc:make-commodity-collector ====
 +
 
'''Returns:''' A commodity collector object. (TODO Explain what this is)
 
'''Returns:''' A commodity collector object. (TODO Explain what this is)
  
 
==== gnc:make-gnc-monetary ====
 
==== gnc:make-gnc-monetary ====
−
'''Returns:''' A Gnc-Monetary object, which is a structure consisting of an
+
 
−
amount of money and its currency
+
'''Returns:''' A Gnc-Monetary object, which is a structure consisting of an amount of money and its currency
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 123: Line 135:
  
 
==== gnc:make-html-document ====
 
==== gnc:make-html-document ====
 +
 
'''Returns:''' An HTML document object
 
'''Returns:''' An HTML document object
  
 
==== gnc:make-html-table ====
 
==== gnc:make-html-table ====
 +
 
'''Returns:''' An HTML table object
 
'''Returns:''' An HTML table object
  
 
==== gnc:make-html-text ====
 
==== gnc:make-html-text ====
 +
 
'''Returns:''' An HTML text object
 
'''Returns:''' An HTML text object
  
 
==== gnc:make-simple-boolean-option ====
 
==== gnc:make-simple-boolean-option ====
 +
 
Creates a checkbox control for yes/no options
 
Creates a checkbox control for yes/no options
  
Line 144: Line 160:
  
 
==== gnc:new-options ====
 
==== gnc:new-options ====
−
'''Returns:''' A new Options object. An Options object is a database of
+
 
−
user-settable options and their values
+
'''Returns:''' A new Options object. An Options object is a database of user-settable options and their values
  
 
==== gnc:option-value ====
 
==== gnc:option-value ====
 +
 
'''Returns:''' The value of the given option
 
'''Returns:''' The value of the given option
  
Line 154: Line 171:
  
 
==== gnc:options-add-account-selection! ====
 
==== gnc:options-add-account-selection! ====
−
Adds a control that allows user to select multiple accounts from the tree of
+
 
−
accounts
+
Adds a control that allows user to select multiple accounts from the tree of accounts
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 169: Line 186:
 
    
 
    
 
==== gnc:options-add-currency! ====
 
==== gnc:options-add-currency! ====
 +
 
Adds a currency selector control to the options dialog box
 
Adds a currency selector control to the options dialog box
  
Line 178: Line 196:
  
 
==== gnc:options-add-date-interval! ====
 
==== gnc:options-add-date-interval! ====
 +
 
Adds a date interval selector control to the options dialog box
 
Adds a date interval selector control to the options dialog box
  
Line 188: Line 207:
  
 
==== gnc:options-add-price-source! ====
 
==== gnc:options-add-price-source! ====
 +
 
Adds a price source selector option to the options dialog box
 
Adds a price source selector option to the options dialog box
  
Line 195: Line 215:
 
* Text to use for option label
 
* Text to use for option label
 
* Order in which the option appears on the page. Can be text from `a' to `z'
 
* Order in which the option appears on the page. Can be text from `a' to `z'
−
* Symbol which names the price database to use. E.g. the symbol corresponding
+
* Symbol which names the price database to use. E.g. the symbol corresponding to the `Nearest in time' option is 'pricedb-nearest
−
to the `Nearest in time' option is 'pricedb-nearest
 
  
 
==== gnc:options-set-default-section ====
 
==== gnc:options-set-default-section ====
 +
 
Sets the options dialog box tab to show when the dialog box appears
 
Sets the options dialog box tab to show when the dialog box appears
  
Line 206: Line 226:
  
 
==== gnc-print-date ====
 
==== gnc-print-date ====
 +
 
'''Returns:''' A formatted date string
 
'''Returns:''' A formatted date string
  
Line 212: Line 233:
  
 
==== gnc:register-option ====
 
==== gnc:register-option ====
 +
 
'''Arguments:'''
 
'''Arguments:'''
 
* Options object
 
* Options object
Line 217: Line 239:
  
 
==== gnc:report-options ====
 
==== gnc:report-options ====
 +
 
'''Returns:''' Options object for the report
 
'''Returns:''' Options object for the report
  
Line 223: Line 246:
  
 
==== gnc:report-percent-done ====
 
==== gnc:report-percent-done ====
−
Updates the progress bar at the bottom of the screen which shows report
+
 
−
creation progress
+
Updates the progress bar at the bottom of the screen which shows report creation progress
  
 
'''Arguments:'''
 
'''Arguments:'''
 
* A percentage value indicating how much of the report has been done so far
 
* A percentage value indicating how much of the report has been done so far
 +
 
==== gnc:report-starting ====
 
==== gnc:report-starting ====
−
(TODO Probably marks the starting point of the report rendering. Probably used
+
 
−
to start the progress bar when a report is (re)loaded)
+
(TODO Probably marks the starting point of the report rendering. Probably used to start the progress bar when a report is (re)loaded)
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 236: Line 260:
  
 
==== gncSplitGetGUID ====
 
==== gncSplitGetGUID ====
 +
 
'''Returns:''' The GUID of a split
 
'''Returns:''' The GUID of a split
  
Line 242: Line 267:
  
 
==== gnc:timepair-end-day-time ====
 
==== gnc:timepair-end-day-time ====
−
'''Returns:''' The Timepair object supplied as the argument but with its time
+
 
−
set to the last second of its day.
+
'''Returns:''' The Timepair object supplied as the argument but with its time set to the last second of its day.
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 251: Line 276:
  
 
==== gnc:timepair-le ====
 
==== gnc:timepair-le ====
−
'''Returns:''' Boolean indicating whether the first Timepair is earlier than or
+
 
−
the same as the second Timepair
+
'''Returns:''' Boolean indicating whether the first Timepair is earlier than or the same as the second Timepair
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 261: Line 286:
  
 
==== gnc:timepair-start-day-time ====
 
==== gnc:timepair-start-day-time ====
−
'''Returns:''' The Timepair object supplied as the argument but with its time
+
 
−
set to the first second of its day.
+
'''Returns:''' The Timepair object supplied as the argument but with its time set to the first second of its day.
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 270: Line 295:
  
 
==== xaccAccountGetCommodity ====
 
==== xaccAccountGetCommodity ====
−
'''Returns:''' The commodity (usually the currency, sometimes the fund name) of
+
 
−
an account
+
'''Returns:''' The commodity (usually the currency, sometimes the fund name) of an account
  
 
'''Arguments:'''
 
'''Arguments:'''
Line 277: Line 302:
  
 
==== xaccAccountGetName ====
 
==== xaccAccountGetName ====
 +
 
'''Returns:''' The name of the account
 
'''Returns:''' The name of the account
  
Line 283: Line 309:
  
 
==== xaccAccountGetSplitList ====
 
==== xaccAccountGetSplitList ====
 +
 
'''Returns:''' A list of the splits in an account
 
'''Returns:''' A list of the splits in an account
  
 
'''Arguments:'''
 
'''Arguments:'''
 
* An Account object
 
* An Account object
 +
 +
==== xaccAccountLookup ====
 +
 +
'''Returns:''' An Account object
 +
 +
'''Arguments:'''
 +
* The account's GUID as a string
 +
* The Book object in which the Account lives (see ''gnc-get-current-book'' to get a Book object)
  
 
==== xaccSplitGetParent ====
 
==== xaccSplitGetParent ====
 +
 
'''Returns:''' The parent (TODO account? transaction?) of a split
 
'''Returns:''' The parent (TODO account? transaction?) of a split
  
 
'''Arguments:'''
 
'''Arguments:'''
 
* A Split object
 
* A Split object

Revision as of 02:51, 3 November 2011

GnuCash Scheme Report API

I'm trying to figure out the GnuCash API for reports by examining the GnuCash and Scheme module sources, report sources and the reports they produce one by one.

This document is mostly the result of my educated guesses. Everyone please feel free to change anything that's inaccurate, and move it to a more appropriate place if needed. I just started tonight (5 Sep 2009) so it's definitely a work in progress right now.

All identifiers are in alphabetical order ignoring case and non-alphanumeric characters in the names.

Defined Variables

gnc:pagename-accounts

The name of the accounts page (tab) in the options dialog box

gnc:pagename-general

The name of the general page (tab) in the options dialog box

Procedures

gnc-account-get-children

Returns: A list of immediate children accounts of the given account; not all descendents. For that, see gnc-account-get-descendants-sorted

Arguments:

  • The account whose children we want

gnc-account-get-descendants-sorted

Returns: The descendants of the given account

Arguments:

  • The account whose descendants we want

gnc-account-get-full-name

Returns: The full name of an account

Arguments:

  • An Account object

gncAccountGetGUID

Returns: The GUID of an account

Arguments:

  • An Account object

gnc:accounts-count-splits

Returns: The number of splits across all the given accounts

Arguments:

  • List of account objects

gnc:accounts-get-all-subaccounts

Returns: List of subaccounts of an account

Arguments:

  • An Account object

gnc:case-exchange-fn

Returns: A currency exchange calculator function

Arguments:

  • A price source
  • The report currency
  • The date at which we want to calculate the exchange values

gnc:date-option-absolute-time

Converts a date option value to absolute Unix epoch time

Returns: A date/time object in absolute time (i.e. from the start of the Unix epoch)

Arguments:

  • A date option

gnc:filter-accountlist-type

Returns: A list of accounts filtered by their type

Arguments:

  • A list of account types to filter by. Accepts, among others: ACCT-TYPE-BANK ACCT-TYPE-CASH ACCT-TYPE-ASSET ACCT-TYPE-STOCK ACCT-TYPE-MUTUAL
  • A list of accounts

gnc-get-current-book

Returns: The currently-open GnuCash Book.

gnc-get-current-root-account

Returns: The root account of the book that is currently open

gnc:gnc-monetary-amount

Returns: The amount of a Gnc-Monetary object

Arguments:

  • A Gnc-Monetary object. These can be created with gnc:make-gnc-monetary

Defined in: src/engine/gnc-numeric.scm

gnc:html-document-set-title!

Arguments:

  • The HTML document object
  • String to set as the document title

gnc:lookup-option

Returns: The actual option object (not its value)

Arguments:

  • Options object. Can be specified with the gnc:report-options procedure
  • Name of page (tab) where the option lives
  • Name of the option to look up

gnc:make-commodity-collector

Returns: A commodity collector object. (TODO Explain what this is)

gnc:make-gnc-monetary

Returns: A Gnc-Monetary object, which is a structure consisting of an amount of money and its currency

Arguments:

  • A Currency object
  • An amount

Defined in: src/engine/gnc-numeric.scm

gnc:make-html-document

Returns: An HTML document object

gnc:make-html-table

Returns: An HTML table object

gnc:make-html-text

Returns: An HTML text object

gnc:make-simple-boolean-option

Creates a checkbox control for yes/no options

Returns: The boolean option object

Arguments:

  • Options dialog box tab (page) name where the option lives
  • Label for the control
  • Order in which the option appears on the page. Can be text from `a' to `z'
  • Tooltip for the checkbox control
  • Default value

gnc:new-options

Returns: A new Options object. An Options object is a database of user-settable options and their values

gnc:option-value

Returns: The value of the given option

Arguments:

  • The option object whose value to get. Can be specified with the gnc:lookup-option procedure

gnc:options-add-account-selection!

Adds a control that allows user to select multiple accounts from the tree of accounts

Arguments:

  • Options object
  • Options dialog box tab (page) name where the option lives
  • Label for the control that sets how many levels of accounts to show
  • Label for the control that sets whether to show subaccounts
  • Label for the overall control
  • Order in which the option appears on the page. Can be text from `a' to `z'
  • (TODO Probably the default account display depth)
  • A lambda expr that returns a list of accounts to show at first
  • (TODO Don't know but set to #f)

gnc:options-add-currency!

Adds a currency selector control to the options dialog box

Arguments:

  • Options object
  • Options dialog box tab (page) name where the option lives
  • Text to use for option label
  • Order in which the option appears on the page. Can be text from `a' to `z'

gnc:options-add-date-interval!

Adds a date interval selector control to the options dialog box

Arguments:

  • Options object
  • Options dialog box tab (page) name where the date option lives
  • Text to use to label `From' part of interval
  • Text to use to label `To' part of interval
  • Order in which the option appears on the page. Can be text from `a' to `z'

gnc:options-add-price-source!

Adds a price source selector option to the options dialog box

Arguments:

  • Options object
  • Options dialog box tab (page) name where the option lives
  • Text to use for option label
  • Order in which the option appears on the page. Can be text from `a' to `z'
  • Symbol which names the price database to use. E.g. the symbol corresponding to the `Nearest in time' option is 'pricedb-nearest

gnc:options-set-default-section

Sets the options dialog box tab to show when the dialog box appears

Arguments:

  • Options object
  • Options dialog box tab (page) name to set as the default

gnc-print-date

Returns: A formatted date string

Arguments:

  • A date/time object

gnc:register-option

Arguments:

  • Options object
  • An individual option object, e.g. made with gnc:make-simple-boolean-option

gnc:report-options

Returns: Options object for the report

Arguments:

  • Report object

gnc:report-percent-done

Updates the progress bar at the bottom of the screen which shows report creation progress

Arguments:

  • A percentage value indicating how much of the report has been done so far

gnc:report-starting

(TODO Probably marks the starting point of the report rendering. Probably used to start the progress bar when a report is (re)loaded)

Arguments:

  • Name of the report

gncSplitGetGUID

Returns: The GUID of a split

Arguments:

  • A Split object

gnc:timepair-end-day-time

Returns: The Timepair object supplied as the argument but with its time set to the last second of its day.

Arguments:

  • A Timepair object. Can come from the gnc:date-option-absolute-time procedure

Defined in: src/app-utils/date-utilities.scm

gnc:timepair-le

Returns: Boolean indicating whether the first Timepair is earlier than or the same as the second Timepair

Arguments:

  • A Timepair object
  • A Timepair object

Defined in: src/app-utils/date-utilities.scm

gnc:timepair-start-day-time

Returns: The Timepair object supplied as the argument but with its time set to the first second of its day.

Arguments:

  • A Timepair object. Can come from the gnc:date-option-absolute-time procedure

Defined in: src/app-utils/date-utilities.scm

xaccAccountGetCommodity

Returns: The commodity (usually the currency, sometimes the fund name) of an account

Arguments:

  • An Account object

xaccAccountGetName

Returns: The name of the account

Arguments:

  • An Account object

xaccAccountGetSplitList

Returns: A list of the splits in an account

Arguments:

  • An Account object

xaccAccountLookup

Returns: An Account object

Arguments:

  • The account's GUID as a string
  • The Book object in which the Account lives (see gnc-get-current-book to get a Book object)

xaccSplitGetParent

Returns: The parent (TODO account? transaction?) of a split

Arguments:

  • A Split object
Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=User:Yawaramin&oldid=7872"