Read Me

################################################################################
                            currxchange version 0.1
################################################################################

[License]
Copyright (c) 2007 Ciaran Farrell <ciaranfarrell@babelworx.net>
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

  1.    Redistributions of source code must retain the above copyright notice,
        this list of conditions and the following disclaimer.
  2.    Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the 
        documentation and/or other materials provided with the distribution.
  3.    The name of the author may not be used to endorse or promote products
        derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY CIARAN FARRELL ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL CIARAN FARRELL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE

[Description]
currxchange is a collection of (at the moment) three python scripts which can 
get the current currency exchange rates from the European Central Bank's 
website and perform currency conversions based on the most up to date exchange 
rates.

The script has some limitations. For example, the script results are only as 
accurate as the most up to date data provided by the European Central Bank. It
has been observed that the European Central Bank do not update their website on
weekends. This means that, if you run this script on a Saturday or Sunday, you
will be using the exchange rate as of Friday evening. The next available data 
will most probably by Monday 10:00 CET.


[Bugs, suggestions, contact]
If you discover bugs in the script, want to make suggestions and/or improve the
script, you can contact the author at <ciaranfarrell@babelworx.net>.


[Files]
currxchange.ini - contains configuration data required
currxchangeCmdline - provides the commandline user interface
currxchangeConfig.py - parses currxchange.ini to provide script with objects
currxchangeBackend.py - carries out getting the data and doing the conversion

[Requirements]
Python (the script was developed using python 2.5)
    - optparse needed
    - ConfigParser needed
    - xml.dom/minidom needed
    - urllib needed
Unix based OS (script hasn't been tested on Windows)

[Installation]
Once you have downloaded and unpacked the tarball (obviously you already have
else you wouldn't be reading this) you need to make sure that you give the 
script execute permission:

    - chmod +x currxchangeCmdline

Once the currxchangeCmdline script is executable, you should be ready to run it.
You may want to rename the currxchangeCmdline script to something shorter.

As it can be imagined that you will often want to convert from foreign currencies
into you own (home) currency, there is a configure option in currxchange.ini 
called mycurrency=EUR. You can change the default EUR to any of the supported
currencies. This will mean you can leave out the destination currency when you 
call the script (read Running the script for more information)

[Running the script]
Note that currxchangeCmdline supports short and long form commandline options. 
This means that you can type currxchangeCmdline -h or currxchangeCmdline --help
and you will be presented with the help dialog for the script.

To run the script you need to know the AMOUNT you wish to convert, the SOURCE 
CURRENCY (this refers to the currency of AMOUNT) and the DESTINATION CURRENCY 
(you can omit the DESTINATION CURRENCY if you have set a valid mycurrency in the
currxchange.ini file). Note that SOURCE CURRENCY and DESTINATION CURRENCY are 
both specified in ISO currency codes. For example US dollars are expressed as
USD and Great British Pounds are expressed as GBP (note that all the letters 
are uppercase). If you don't know the currency code for the SOURCE CURRENCY or
DESTINATION CURRENCY you can view the list of supported currencies using:

    - ./currxchangeCmdline -l

Thus, once you have a valid SOURCE CURRENCY and DESTINATION CURRENCY, you can
enter a command such as:

    - ./currxchangeCmdline 12.34 USD EUR

This command instructs the script to convert  12.34 US dollars into Euro. If 
you had set EUR as mycurrency in the currxchange.ini file (the default is EUR)
then you could have achieved the same result as above by entering only:

    - ./currxchangeCmdline 12.34 USD

When entering AMOUNT (in the above examples 12.34) make sure that you use a 
decimal point (.) and NO OTHER NOTATION. This means (for Germans etc) no 
commas (,) and no spaces to separate thousands and millions.