================================================================================
  ASV 0.4   2 April 2001   Copyright (c)2001 Laurence Tratt   laurie@tratt.net
================================================================================



   Introduction
  ==============

This is the second public release of ASV, my replacement module for my own surprisingly popular CSV.py. ASV is intended to be more feature rich, better designed and reliable. As this is the first public release there may well be bugs to be found.

ASV is distributed under a BSD style licence.


New versions of ASV will become available from:

  http://tratt.net/~laurie/python/asv/
  
Please mail me with any comments you might have at laurie@tratt.net.



   Features
  ==========

ASV features include:

* Format dependant input / output
* Extendable input / output scheme
* Built in input routines possess `good enough' heuristics to parse even badly
    formed files
* A command line interface for quick conversion between different formats



   Installation
  ==============

Please read the accompanying INSTALL file.



   Usage
  =======

There are two distinct ways of using ASV:

  * Using it as a Python module
  * Using it as an executeable program

Please note that either way, you *must* have Python 2.0 or greater already installed on your computer.


 Executeable usage
===================

ASV has a simple command line interface to allow you to convert between differing types of input format. For example, if you need to convert x.tsv into the more common x.csv:

  asv -tsv x.tsv -csv y.csv

The general format for invoking ASV is thus:

  asv [-c] -<input builder> [<input file name>] [-c] -<output builder>
    [<output file name>]

A `builder' is effectively a file format. Standard ASV builders include:

    colonsv  :  for files seperated by ;
    csv      :  for files seperated by ,
    tsv      :  for files seperated by <tab>

Run ASV with no command line arguments to get a list of the installed builders and a description of what each one does.

A builder can both read in and write to the format it satisfies. There is no need for example to have seperate `csv reader' and `csv writer' builders.

If you wish to read from standard input or write to standard output, omit the file name and place -c before the builder of your choice. For example:

  asv -tsv x.tsv -c -csv

will read in a TSV file, convert it to CSV and output the result to screen. Similarly if, under Unix, you have a program z which outputs tsv data which you need to convert straight away into CSV data:

  z | asv -c -tsv -csv output.csv

This command runs z, then pipes all the output data from z straight into ASV which converts it and stores the converted data into a file called output.csv.


 Module usage
==============

ASV.py has doc strings for all the important `public' methods. This section is intended as an overview of how ASV works.

The ASV class - which implements all applicable list methods to appear to be a Python list - inside the ASV module holds 0 or more rows of data (stored in the format of the Row class) but has no concept of how this data has been input or how it will be output. In other words it simply stores data, converting it into and out of its internal format transparently when you make a call on it.

When you wish to input or output data, you have to give it a "helper" class instance which understands the physical representation of the data. To input from a file:

    # Import the ASV module
    
    import ASV
    
    
    # Create a blank ASV instance
    
    my_data = ASV.ASV()
    
    # We are loading from a file called "test_data.csv"
    # We are using the CSV loader
    # The CSV file we are loading has column headings so that we can access data
    #   by name rather than number
    
    my_data.input_from_file("test_data.csv", ASV.CSV(), has_field_names = 1)
    
So now `my_data' will hold some rows of data (presuming test_data.csv wasn't blank). You can use `my_data' just like a normal Python list:

    # Iterate over every row in my_data

    for row in my_data:
        # Print the row out - this gives us back an instance of the Row class
        
        print row
        
        # Print out a single element from the row
        
        print row[1]
        
        # Because our input file had field names, we can print out a named
        #   element in the row without having to know what its index is
        
        print row["address"]
    
    # Add a row to the end of `my_data'
    
    my_data.append(["Laurie", "England"])
    
    # Print out the row we just added
    
    print my_data[-1]

If having done all that, you want to save the data out as a TSV file just do:

    my_data.output_to_file("test_data_out.tsv", ASV.TSV())

If you wanted to just view the TSV output rather than saving it, then you can use the output method which just returns a string (input_from_file is similarly matched by input):

    print my_data.output(ASV.TSV())
