Difference between revisions of "Custom Reports"

Revision as of 20:13, 23 April 2012

Custom Reports in GnuCash

The term Custom Reports has several contexts in GnuCash:

• Customizing settings for standard reports ([[1]])
• Combining selected standard reports into one view ([[2]])
• Customized output formart for reports ([[3]])
• Reports written in Scheme which are not delivered as part of the standard reports (this page)

If you are not up into coding, you should check the

• report options
• stylesheets and
• stylesheet options and
• file properties.

Possibly there are ways to get, what you desired.

If you are ready for coding (and even already firm in Scheme and Guile) then this is the place to contribute.

Introduction

Unfortunately, at the present time writing a custom report for GnuCash requires a little bit of hacking. This wiki page should contain some information to help you get started, since there is no official documentation.

In the GnuCash project the reports are coded in Scheme, not in C. This is one of the pre-requisites to make the behaviour ready for customization. It leads to the drawback that one must learn yet another programming language (if not already familiar with it) but saves the effort to get into the issue how to build GnuCash from source.

Guile is used as interface to get the Scheme code executed during runtime. Again, if not already familiar with it, this is the second piece of work that one has to swallow.

Last but not least the API for that sort of thing is not formally specified.

Still reading? Not yet discouraged? Good on you! Because there is lots of help available.

First of all there is good educational stuff available on the web to get you into the topic of Scheme and Guile. Secondly there is a nice hello-world.scm example report specifically written to show you the base layout of a GnuCash report. And finally, this Wiki page might give you some guidence when doing the first steps.

Getting Started

Get to know Scheme

Get to know Guile

Example Reports

A good place to start is to examine the source code of the reports included with GnuCash. The location varies a little with different operating systems:

• On BSD look in /usr/local/share/gnucash/guile-modules/gnucash/report
• On OpenSuse up to 10.x look in /opt/gnome/share/gnucash/guile-modules/gnucash/report, more recent versions use /usr/share/gnucash...
• On Gentoo, Ubuntu, Foresight look in /usr/share/gnucash/guile-modules/gnucash/report
• On Windows look in C:\Program Files\gnucash\share\gnucash\guile-modules\gnucash\report
• On OSX (Gnucash.app, not Fink or MacPorts), look in Gnucash.app/Contents/Resources/share/gnucash/guile-modules/gnucash/report)

hello-world.scm is specially written to demonstrate the basic structure of a report. However, don't get too confused by the huge number of options which are shown in that report - those were just added to show off the variety of options which are available inside gnucash.

account-piechart

As another example, here's how the file src/reports/standard-reports/account-piechart.scm works (line numbers for SVN r20800 version): There are two long Scheme functions: The first one is "option-generator" starting in line 84 which defines, well, the options for this report. The second one is "piechart-renderer" (line 191ff) and contains the code that does the actual calculation: The list of values that should be shown is calculated by the function call in line 377, using the selected accounts in the variable "topl-accounts". That function "traverse-accounts" is defined in line 336 and it is a recursive function that calls itself in line 349 to traverse through all children accounts of the account tree. For a single account, in line 346 it calls "profit-fn" which gets the balance amount of one single account. You can see that in "profit-fn"'s definition in line 253, which obtains the account balance either in one interval or at a given date. The function there "gnc:account-get-comm-balance-at-date" is defined in the file src/reports/report-system/html-utilities.scm, where it finally will call the functions from the C API about QofQuery. It will create a query for the account balance at the given date.

Well, long story short, this calculation is rather involved. Sorry.

The GnuCash API

The GnuCash application programming interface is quite intimidating, unfortunately. Luckily, for the reports, most of the stuff needed can be found in the scheme sources. Here some random examples of handy procedures (paths shown refer to the location in a source tarball; might be copied into the location as above in your installation):

• create a monetary object: gnc:make-gnc-monetary src/engine/gnc-numeric.scm
• get the amount of a monetary object: gnc:gnc-monetary-amount src/engine/gnc-numeric.scm
• get an account name: gnc-account-get-name src/engine/swig-engine.c
• create a commodity collector: gnc:make-commodity-collector src/report/report-system/report-utilities.scm

Watch out for the gnucash version in use: In 2.0.x, the Scheme wrappers were created by G-WRAP, started with gnc: (with a colon) and were written into scheme files of the name gw-something.scm. In 2.1.x and later, the Scheme wrappers are created by SWIG, start with gnc- (a dash, not a colon) and were written into C files of the name swig-something.c. Please keep that in mind if the old documentation points you towards functions like these: Get an account name: gnc:account-get-name src/engine/gw-engine-spec.scm - such a function would now be called gnc-account-get-name and would be found in src/engine/engine.i or the generated file src/engine/swig-engine.c.

Programming tools

Any reasonable source/text editor, including emacs and vi, should provide basic syntax support for source-code editing. One of the most basic and important for editings scheme/lisp sources is parenthesis matching. Other scheme environments (such as drScheme) might also be useful for editing the sources, but note that they might allow constructs that are not valid in guile.

Loading the Report

There are two ways to load a report at startup of GnuCash: from a user account, or from the installation tree. You will likely want to use the user account approach.

Before you load the report

• To avoid symbol definition conflicts with other reports, make sure your report code begins with a define-module statement:

  (define-module (gnucash report unique-report-name))

  like for example

  (define-module (gnucash report my-custom-invoice))

• Make sure your report has a unique name (for GnuCash 2.2.x and before) or a unique id (GnuCash 2.3.x and later). These are set at the end of your code in a gnc:define-report statement. If you need some newly generated unique id, run the program gnucash-make-guids which is being installed by gnucash as well.

From a user account

In your settings folder edit config.user to add a line of the form:

    (load "/path/to/my/personal/report.scm") ;; Linux and OS X
    (load "X:\\path\\to\\my\\personal\\report.scm")  ;; Windows

Note: Without a leading '/', all paths are taken relative to your settings folder (see below).

Note: On Windows, double backslashes are required since the backslash is a special character and must be escaped.

Caution: For older versions of GnuCash (before 2.1.x ?) load-from-path was suggested to load reports instead of load, but this is not compatible with the module definition that is now found in all reports. Using load-from-path on a report with module defninition will cause a crash

Settings Folder Locations:

To load your report, you must restart GnuCash. You will have to do this every time you change a report.

Thanks to DeanCording for clarifying the define-module/load bits

From the installed report directory

Alternatively, you can copy the report to the installed report directory. Make sure you have included a module definition as shown above. In gnucash-2.3.x or higher, all *.scm files from the directory guile-modules/gnucash/report/standard-reports/ will be loaded automatically. This applies only to the standard-reports/ sub-directory, not to any of the other directories with reports. Hence, the easiest way to have your report available to gnucash is to copy your *.scm file into that directory.

Then restart GnuCash. You will have to do this every time you change the report definition file.

Alternatively (or for gnucash versions before 2.3.0), you can copy your *.scm file to one of the other report definition directories, but then you have to edit the appropriate Scheme file to register your report with the reporting system. You will have to register the report in one of the following places, depending on which submenu you want it to appear.

• Standard Reports: standard-reports.scm
• Business Reports: business-reports.scm
• Utility Reports: utility-reports.scm

Then restart GnuCash. You will have to do this every time you change a report.

Debugging your report

There is not really a debugger available for guile, but you can have your code write debug messages to help you trace your code.

• Start GnuCash like

  gnucash --debug --log gnc.scm=debug

  to enable debugging messages.
• Add debugging messages with the (gnc:debug) variable, e.g. (gnc:debug "here I am").
• There are also (gnc:msg), (gnc:warn) and (gnc:error) functions; see src/scm/main.scm for more details.
• Messages will be logged to /tmp/gnucash.trace by default, you can change this with --logto (try 'stderr' or 'stdout').

Other Resources

One other way to create custom reports outside GnuCash, but directly from GnuCash data, is to use Ledger-CLI.

Old GnuCash Report Information

(may be very out of date)

• Version 1.6 report documentation
• FAQ#Q:_I.27d_like_to_write_my_own_custom_reports._Where_should_I_start.3F
• From the mailing list

Learning Scheme

• MIT Scheme Index
• Teach Yourself Scheme in Fixnum Days
• Structure and Interpretation of Computer Programs
• How to Design Programs
• Mastering Scheme is highly eased after reading The Scheme Progamming Language by R. Kent Dybvig
• Guile documentation