Module pl.data

Reading and querying simple tabular data.

data.read 'test.txt'
==> {{10,20},{2,5},{40,50},fieldnames={'x','y'},delim=','}

Provides a way of creating basic SQL-like queries.

require 'pl'
local d = data.read('xyz.txt')
local q = d:select('x,y,z where x > 3 and z < 2 sort by y')
for x,y,z in q do
    print(x,y,z)
end

See the Guide

Dependencies: pl.utils, pl.array2d (fallback methods)

Functions

Data.column_by_name (name) return a particular column as a list of values (method).
Data.select (condn) return a query iterator on this data (method).
Data.select_row (condn) return a row iterator on this data (method).
Data.copy_select (condn) return a new data object based on this query (method).
Data.column_names () return the field names of this data object (method).
Data.write_row (f) write out a row (method).
Data.write (f) write data out to file (method).
read (file, cnfg) read a delimited file in a Lua table.
write (data, file[, fieldnames[, delim='\t']]) write 2D data to a file.
new (d[, fieldnames]) create a new dataset from a table of rows.
query (data, condn, context, return_row) create a query iterator from a select string.
filter (Q, infile, outfile, dont_fail) Filter input using a query.


Functions

Data.column_by_name (name)
return a particular column as a list of values (method).

Parameters:

  • name either name of column, or numerical index.
Data.select (condn)
return a query iterator on this data (method).

Parameters:

  • condn string the query expression

See also:

Data.select_row (condn)
return a row iterator on this data (method).

Parameters:

  • condn string the query expression
Data.copy_select (condn)
return a new data object based on this query (method).

Parameters:

  • condn string the query expression
Data.column_names ()
return the field names of this data object (method).
Data.write_row (f)
write out a row (method).

Parameters:

  • f file-like object
Data.write (f)
write data out to file (method).

Parameters:

  • f file-like object
read (file, cnfg)
read a delimited file in a Lua table. By default, attempts to treat first line as separated list of fieldnames.

Parameters:

  • file a filename or a file-like object
  • cnfg parsing options
    • delim string a string pattern to split fields
    • fieldnames array (i.e. don’t read from first line)
    • no_convert bool (default is to try conversion on first data line)
    • convert tab table of custom conversion functions with column keys
    • numfields int indices of columns known to be numbers
    • last_field_collect bool only split as many fields as fieldnames.
    • thousands_dot int thousands separator in Excel CSV is ‘.’
    • csv bool fields may be double-quoted and contain commas; Also, empty fields are considered to be equivalent to zero.

Returns:

  1. data object, or nil
  2. error message. May be a file error, ‘not a file-like object’ or a conversion error
write (data, file[, fieldnames[, delim='\t']])
write 2D data to a file. Does not assume that the data has actually been generated with new or read.

Parameters:

  • data 2D array
  • file filename or file-like object
  • fieldnames {string} list of fields (optional) (optional)
  • delim string delimiter (default tab) (default '\t')

Returns:

    true or nil, error
new (d[, fieldnames])
create a new dataset from a table of rows. Can specify the fieldnames, else the table must have a field called ‘fieldnames’, which is either a string of delimiter-separated names, or a table of names.
If the table does not have a field called ‘delim’, then an attempt will be made to guess it from the fieldnames string, defaults otherwise to tab.

Parameters:

  • d the table.
  • fieldnames {string} optional fieldnames (optional)

Returns:

    the table.
query (data, condn, context, return_row)
create a query iterator from a select string. Select string has this format:
FIELDLIST [ where LUA-CONDN [ sort by FIELD] ]
FIELDLIST is a comma-separated list of valid fields, or ‘*’.

The condition can also be a table, with fields ‘fields’ (comma-sep string or table), ‘sort_by’ (string) and ‘where’ (Lua expression string or function)

Parameters:

  • data table produced by read
  • condn select string or table
  • context a list of tables to be searched when resolving functions
  • return_row if true, wrap the results in a row table

Returns:

  1. an iterator over the specified fields, or nil
  2. an error message
filter (Q, infile, outfile, dont_fail)
Filter input using a query.

Parameters:

  • Q string a query string
  • infile filename or file-like object
  • outfile filename or file-like object
  • dont_fail bool true if you want to return an error, not just fail
generated by LDoc 1.4.6 Last updated 2017-07-18 16:28:41