MoneyWorks.pm - Perl interface to MoneyWorks accounting software
0.02 (beta)
use MoneyWorks ();
# OO use:
$m = new MoneyWorks::
rego => $registration_number,
user => $user,
passwd => $password,
file => $filename,
bin => '/usr/bin/moneyworks',
keep_alive => 0; # default is 1
$m->rego($rego); # change it
$m->user($new_user); # etc.
$m->version; # returns the MoneyWorks version
$m->eval( $moneyworks_expression );
$m->import( data => $string, map => $filepath );
$m->import( data_file => $datafile, map => $filepath );
# Not yet supported
# $m->import( data => \@array_of_hashes, table => 'product' );
my $hashref = $m->export(
table => $table,
fields => \@fields,
search => $search,
key => $key, # if key is omitted an array ref is returned
);
# Ties (currently read-only):
tie my %products, MoneyWorks =>
file => 'moneyworks://localhost?doc=Acme%20Widgets.mwd5'
table => 'Product'
key => 'Code';
# Other constructor args (rego, etc.) are permitted.
$description = $products{'CA100'}{Description};
# etc.
# Also:
my $products = $m->tie('Product','Code');
my $price = $products->{CA100}{SellPrice};
# Utility functions:
use MoneyWorks;
$quoted = mw_cli_quote q/"'`abc/;
$quoted = mw_str_quote q/"'`abc/;
This module provides a Perl interface to MoneyWorks Gold or MoneyWorks Datacentre.
It uses the command line interface, either running individual commands (with keep_alive => 0) option, or maintaining a single moneyworks process.
It is highly recommended that one read the moneyworks manpage before using this.
my $m = new MoneyWorks %args;
The %args are as follows:
Registration number
Log-in credentials for local files. For documents on servers, include the credentials in the URL.
The company file to open. This can be a local file path or a moneyworks:// URL (see http://cognito.co.nz/support.faq.php?art=url).
If you are using a moneyworks:// URL, you must include a port number if running under a user without a preference file, such as www. If there is a preference file, MoneyWorks will assume the last used port number. Always provide one to be on the safe side.
The location of the MoneyWorks executable.
This module automatically tries to find it. You can override it with this option. In Windows, you will almost always have to specify this explicitly, since the executable needs to be copied and modified to work with stdio.
When this is set to a false value, every access to the database will require a separate invocation of the moneyworks executable. If you are connecting to a server (moneyworks:// URL), this means a new connection each time.
With keep_alive set to a true value (the default), a MoneyWorks process will be kept running. This can reduce overhead in the case of multiple database accesses. But be warned that only one instance of MoneyWorks can open a local file at a time. Data access methods will die if the file is already open by another process.
All the options to the constructor are also the names of accessor methods. You can set these by passing an argument.
If there is a moneyworks process running, setting any of these will terminate the process.
Returns the MoneyWorks version number.
Evaluates the MoneyWorks expression and returns the result.
Import data into MoneyWorks. The $file is the path to the import map (usually in the plugins folder).
The return value is a hash ref containing the the number of records created and updated (except for User, Contact and Build files, which will always report zero).
Note that field values cannot contain line breaks. (A line break indicates a new record.) But you can use vertical tabs (control-K) (which is precisely how MoneyWorks exports them).
Like the above, but with a file name instead of the actual data.
Retrieve data from MoneyWorks. %options are as follows:
table The name of the table (aka 'file')
fields Array ref of field names to retrieve
search Search string (filter) in MoneyWorks 'Calculations and
Things' syntax
key Which field to use as a hash key for each record
(optional)
If key is not specified, this method returns an array ref of hash refs; otherwise it returns a hash ref of hash refs.
Issues a MoneyWorks command and returns the result as a string.
These methods only apply in keep-alive mode.
Returns the process ID of the MoneyWorks process, if there is one.
This method terminates the process if it is running.
You can tie a hash to a MoneyWorks table like this:
tie my %products, MoneyWorks =>
file => $filename,
table => "Product",
key => "Code";
Other options from the constructor are permitted. keep_alive => 0 is not recommended, as it would be very inefficient.
You can also create a tie from an existing object by simply calling the tie method with the table and and the key as its arguments. It returns a reference to a tied hash.
These are exported by default. You can use MoneyWorks (); to load the module without exporting them. Or you can have just one of them exported by naming it explicitly.
This quotes its argument for use on the command line or with the command method. It picks whatever ASCII delimiter is available, starting with chr 127 and working backwards.
This functions quotes its arguments for use as a string in MoneyWorks expressions. It escapes characters as necessary and chooses either " or ` as the delimiter.
There is no easy way to edit individual fields in MoneyWorks' databases; you have to create a custom import map. Another way is to evaluate an expression containing the undocumented Replace() function. The syntax is Replace("table.field", "search expression", "replacement expression").
None have been reported yet, but I've left some room for them:
perl 5.6 or higher
MoneyWorks Gold or Datacentre Client (http://cognito.co.nz/)
Copyright (C) 2009, Father Chrysostomos (sprout at, um, cpan dot org)
This program is free software; you may redistribute or modify it (or both) under the same terms as perl.
