NAME

MoneyWorks.pm - Perl interface to MoneyWorks accounting software

VERSION

0.02 (beta)

SYNOPSIS

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/;

DESCRIPTION

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.

INTERFACE

Constructor

my $m = new MoneyWorks %args;

The %args are as follows:

rego

Registration number

user

passwd

Log-in credentials for local files. For documents on servers, include the credentials in the URL.

file

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.

bin

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.

keep_alive

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.

Accessors

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.

Methods for Data Access

version

Returns the MoneyWorks version number.

eval

Evaluates the MoneyWorks expression and returns the result.

import ( data => $str, map => $file )

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).

import ( data_file => $datafile, map => $file )

Like the above, but with a file name instead of the actual data.

export ( %options )

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.

command ( $command )

Issues a MoneyWorks command and returns the result as a string.

Methods Pertaining to the Child Process

These methods only apply in keep-alive mode.

pid

Returns the process ID of the MoneyWorks process, if there is one.

close

This method terminates the process if it is running.

Ties

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.

Utility Functions

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.

mw_cli_quote

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.

mw_str_quote

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.

LIMITATIONS

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").

BUGS

None have been reported yet, but I've left some room for them:

PREREQUISITES

perl 5.6 or higher

constant::lexical

MoneyWorks Gold or Datacentre Client (http://cognito.co.nz/)

AUTHOR & COPYRIGHT

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.

cpanm MoneyWorks

perl -MCPAN -e shell
install MoneyWorks