Difference between revisions of "User:Yawaramin"

From GnuCash
Jump to: navigation, search
(Initial upload)
 
(Intro)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== GnuCash Report API in 2.2.4 ==
+
== Hello ==
−
I'm trying to figure out the GnuCash API for reports by examining the Scheme
 
−
module sources, report sources and the reports they produce one by one. I'm
 
−
using Portable GnuCash 2.2.4 as it's the only one I could get to run on my
 
−
Windows system unfortunately.
 
  
−
This document is mostly the result of my educated guesses. Everyone please feel
+
I’m a member of the GnuCash Documentation team. You can also find me on:
−
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
+
* GNOME BugZilla: https://bugzilla.gnome.org/page.cgi?id=describeuser.html&login=yawar.amin%40gmail.com
−
in progress right now.
+
 
 +
* GitHub: https://github.com/yawaramin
 +
 
 +
* Ohloh: https://www.ohloh.net/accounts/yawaramin
 +
 
 +
== 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
 
All identifiers are in alphabetical order ignoring case and non-alphanumeric
Line 14: Line 19:
  
 
=== 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 38:
  
 
==== 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 45:
  
 
==== 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 52:
  
 
==== gncAccountGetGUID ====
 
==== gncAccountGetGUID ====
 +
 
'''Returns:''' The GUID of an account
 
'''Returns:''' The GUID of an account
  
Line 49: Line 59:
  
 
==== 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 66:
  
 
==== 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 73:
  
 
==== gnc:case-exchange-fn ====
 
==== gnc:case-exchange-fn ====
 +
 
'''Returns:''' A currency exchange calculator function
 
'''Returns:''' A currency exchange calculator function
  
Line 69: Line 82:
  
 
==== 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 91:
  
 
==== 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 116:
  
 
==== gnc:html-document-set-title! ====
 
==== gnc:html-document-set-title! ====
 +
 
'''Arguments:'''
 
'''Arguments:'''
 
* The HTML document object
 
* The HTML document object
Line 102: Line 122:
  
 
==== 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 131:
  
 
==== 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 145:
  
 
==== 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 170:
  
 
==== 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 181:
  
 
==== 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 196:
 
    
 
    
 
==== 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 206:
  
 
==== 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 217:
  
 
==== 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 225:
 
* 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 236:
  
 
==== gnc-print-date ====
 
==== gnc-print-date ====
 +
 
'''Returns:''' A formatted date string
 
'''Returns:''' A formatted date string
  
Line 212: Line 243:
  
 
==== gnc:register-option ====
 
==== gnc:register-option ====
 +
 
'''Arguments:'''
 
'''Arguments:'''
 
* Options object
 
* Options object
Line 217: Line 249:
  
 
==== gnc:report-options ====
 
==== gnc:report-options ====
 +
 
'''Returns:''' Options object for the report
 
'''Returns:''' Options object for the report
  
Line 223: Line 256:
  
 
==== 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 270:
  
 
==== gncSplitGetGUID ====
 
==== gncSplitGetGUID ====
 +
 
'''Returns:''' The GUID of a split
 
'''Returns:''' The GUID of a split
  
Line 242: Line 277:
  
 
==== 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 286:
  
 
==== 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 296:
  
 
==== 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 305:
  
 
==== 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 312:
  
 
==== xaccAccountGetName ====
 
==== xaccAccountGetName ====
 +
 
'''Returns:''' The name of the account
 
'''Returns:''' The name of the account
  
Line 283: Line 319:
  
 
==== 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

Latest revision as of 19:42, 12 January 2013

Hello

I’m a member of the GnuCash Documentation team. You can also find me on:

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=9335"