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) 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: the query expression

see also:

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

Parameters:

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

Parameters:

  • condn: 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 (default stdin)
  • cnfg: options table: can override delim (a string pattern), fieldnames (a list), specify no_convert (default is to convert), numfields (indices of columns known to be numbers) and thousands_dot (thousands separator in Excel CSV is ‘.’)
write (data, file, fieldnames, delim)
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: list of fields (optional)
  • delim: delimiter (default tab)
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: optional fieldnames

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: a query string
  • infile: filename or file-like object
  • outfile: filename or file-like object
  • dont_fail: true if you want to return an error, not just fail
generated by LDoc 1.2