# 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.query
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 (default stdin)
  - cnfg tab options table: can override `delim` (a string pattern), `fieldnames` (a list), specify `no_convert` (default is to conversion), `numfields` (indices of columns known to be numbers) and `thousands_dot` (thousands separator in Excel CSV is '.'). If `csv` is set then fields may be double-quoted and contain commas;

  ### 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')
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.3 Last updated Tue, 18 Aug 2015 11:21:53 +0200