CsvUtil.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
// @file CsvUtil.qm Qore user module for working with CSV files

/*  CsvUtil.qm Copyright 2012 - 2014 Qore Technologies, sro

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/

// minimum required Qore version


/* see release notes below for version history
*/

// private class used to iterate a list and skip elements without any value
class ListValueIterator : public ListIterator {

public:
    constructor(*list l);


    bool next();

};

class CsvHelper {

public:
    private :
        const Types = (
            "int": True,
            "*int": True,
            "float": True, 
            "*float": True,
            "number": True,
            "*number": True,
            "string": True,
            "*string": True,
            "date": True,
            "*date": True,
        );

        const FieldAttrs = ("type", "format", "timezone", "code");

public:
    
    private setFields();

    
    checkType(string key, string value);

}; // class CsvHelper

namespace CsvUtil {
    const EOL_UNIX = "\n";
    const EOL_WIN = "\r\n";
    const EOL_MACINTOSH = "\r";

    // helper list of end of line values
    const EOLS = (EOL_UNIX, EOL_WIN, EOL_MACINTOSH, );


class CsvAbstractIterator : public Qore::AbstractIterator, private CsvHelper {

public:
        private :
            const Options = (
                "encoding": True,
                "separator": True,
                "quote": True,
                "eol": True,
                "ignore-empty": True,
                "ignore-whitespace": True,
                "header-lines": True,
                "header-names": True,
                "headers": True,
                "verify-columns": True,
                "fields": True,
                "timezone": True,
                );

public:

        private :
            // field separator
            string separator = ",";

            // field content delimiter
            string quote = "\"";

            // number of header lines
            softint headerLines = 0;

            // flag to use string names from the first header row if possible
            bool headerNames = False;

            // True if empty lines should be ignored
            bool ignoreEmptyLines = True;

            // Flag to trim the field content (trim leading and trailing whitespace) from unquoted fields
            bool ignoreWhitespace = True;

            // headers / column names for lines iterated
            *softlist headers;

            // hash of field information (types, formats, and possible code), hash key = column name or number (starting with 0)
            *hash fields;

            // list of field descriptions (from fields, ordered when headers are set)
            *list fdesc;

            // the @ref Qore::TimeZone to use when parsing dates (default: current time zone)
            *TimeZone tz;

            // verify the column count for every row; if a row does not match, then throw a \c CSVFILEITERATOR-DATA-ERROR exception
            bool checkElementCounts = False;

            // column count for verifying column counts
            int cc;

            // current record count for the index() method
            int rc = 0;

public:


        constructor(*hash opts);


        private *string getDataName();


        private abstract int lineNumberImpl();

        private abstract string getLineValueImpl();

        private abstract bool nextLineImpl();
        

        bool next();



        any memberGate(string name);



        hash getValue();



        hash getRecord();



        list getRecordList();



        string getSeparator();



        string getQuote();



        *list getHeaders();



        int index();



        int lineNumber();


        private any handleType(hash fh, *string val);


        private list parseLine();

    };


class CsvFileIterator : public CsvUtil::CsvAbstractIterator,public  Qore::FileLineIterator, private CsvHelper {

public:

        constructor(string path, *hash opts);


        private *string getDataName();


        private int lineNumberImpl();


        private string getLineValueImpl();


        private bool nextLineImpl();

    }; // CsvFileIterator class


class CsvDataIterator : public CsvUtil::CsvAbstractIterator, private CsvHelper {

public:
        private :
            string data;
            *string eol;
            *string line;
            int pos = 0;
            int lineno = 0;
            bool valid = False;

public:


        constructor(string data, *hash opts);



        bool valid();


        private int lineNumberImpl();


        private string getLineValueImpl();


        private bool nextLineImpl();

    };


class AbstractCsvWriter : private CsvHelper {

public:
        private :
            const Options = (
                "encoding": True,
                "separator": True,
                "quote": True,
                "eol": True,
                "verify-columns": True,
                "fields": True,
                "headers": True,
                "date-format": True,
                "write-headers": True,
                "optimal-quotes": True,
                );

public:

        private :
            // TODO/FIXME
            string encoding = get_default_encoding();

            // field separator
            string separator = ",";

            // field content delimiter
            string quote = "\"";
            
            // end of line sequence
            string eol = EOL_UNIX;
            
            // default date->string format
            string dateFormat = 'DD/MM/YYYY hh:mm:SS';

            // headers / column names for lines iterated
            *softlist headers;

            // hash of field information (types, formats, and possible code), hash key = column name or number (starting with 0)
            *hash fields;

            // list of field descriptions (from fields, ordered when headers are set)
            *list fdesc;

            // verify the column count for every row; if a row does not match, then throw a \c CSVFILEITERATOR-DATA-ERROR exception
            bool checkElementCounts = False;

            // the latest line number
            int lineNo = 0;

            // base template for value format
            string baseTemplate;
            
            string errname;

            // this flag determines if any stored headers are output
            bool write_headers = True;

            // stores the optimal quotes option
            bool optimal_quotes = True;

public:


        constructor(string errname, *hash opts);



        writeLine(list values);

        

        writeLine(hash values);

        

        write(AbstractIterator iterator);


        abstract private writeRawLine(list values);
        

        private string prepareRawLine(list values);


        private string dateFormat(int ix);


    }; // AbstractCsvWriter class
      
class CsvFileWriter : private AbstractCsvWriter {

public:
        
        private :
            // a file to write
            File file;

public:
        

        constructor(string path, *hash opts);


        private writeRawLine(list values);

    
    }; // CsvFileWriter

class CsvStringWriter : private AbstractCsvWriter {

public:
        
        private :
            // a csv content
            string content;

public:
        

        constructor(*hash opts);


        private writeRawLine(list values);

        
        string getContent();

    
    }; // CsvStringWriter

}; // CsvUtil namespace