NAME

MoneyWorks.pm - Perl interface to MoneyWorks accounting software

VERSION

0.08

SYNOPSIS

use MoneyWorks ();


# OO use:

$m = new MoneyWorks::
  rego   => $registration_number,
  user   => $user,
  password => $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,  # optional; all fields by default
  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 Client.

It uses the command line interface, either running individual commands (with keep_alive => 0), 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

password

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. This method also replaces line breaks with spaces, to make it easier to write long expressions. (MoneyWorks expressions cannot contain line breaks.)

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 (optional)
search  Search string (filter) in MoneyWorks 'Calculations and
        Things' syntax
key     Which field to use as a hash key for each record (the
        key does not need to be included in the list of fields)
        (optional)

If fields is omitted, all fields are returned.

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.

WARNINGS

You may see these messages if you have warnings enabled.

Command contains null chars

If you have warnings enabled and you (directly or indirectly) pass a string to the command method that contains null characters, you will see this message. Null bytes confuse MoneyWorks and cause the input and output to get out of sync, so the module strips them and warns if it finds them.

Argument to mw_cli_quote contains line breaks

Commands cannot contain line breaks. mw_cli_quote is not capable of escaping them, so it warns.

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

The tie interface does not work with the keys and each functions. It would be very hard to implement this efficiently.

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

If you are using perl 5.12 or higher, you will also need the Classic::Perl module.

AUTHOR & COPYRIGHT

Copyright (C) 2009-10, 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