Module pica

Handle PICA+ data in Lua. This module provides two classes (PicaField and PicaRecord) for PICA+ data. The programming interface of these classes is optimized for easy access and conversion of PICA+ records. Have a look at the file 'example.lua' for a synopsis.

Author:

  • Jakob Voss

Tables

PicaField Stores an ordered list of PICA+ subfields.
PicaRecord Stores a PICA+ record.

Functions

filtervalue (value, ...) Simply returns a value, optionally filtered by one or more functions.
formatfilter (format) Returns a filter function based on a Lua string format.
patternfilter (pattern) Returns a filter function based on a Lua pattern.
string.notempty (self) Returns a string or nil if the string is empty
table.append (t, a) Insert all values with integer keys from one table to another.

Tables

PicaField
Stores an ordered list of PICA+ subfields. #f returns the number of subfields.

Fields

  • n: (number) the nth subfield value or nil
  • c: (string) the first subfield value of a subfield with code c where c can be a letter (a-z or A-Z) or a digit (0-9). Nil is returned if no such subfields exists.
  • ok: (boolean) whether the field has a tag and is not empty
  • tag: (string) the tag without occurrence
  • full: (string) tag and occurrence combined
  • occ: (string) the occurrence as string
  • num: (number) the occurrence as number between 0 and 99
  • lev: (number) level 0, 1, or 2 (default is 0)

Methods

PicaRecord
Stores a PICA+ record. Basically a PicaRecord is a list of PICA+ fields This class overloads the following operators:
  • #r returns the number of fields.
  • r % l returns whether locator p matches r (see PicaRecord:has).

Fields

  • n: (number) the nth field value
  • locator: (string) the first matching field or value (see PicaRecord:first)

Methods

Functions

PicaField.new (tag, occ, ...)
Creates a new PICA+ field. The newly created field will have no subfields. The optional occurence indicator can only be set in addition to a valid tag. On failure this returns an empty field with its tag set to the empty string. On failure an empty PicaField instance is returned.

Parameters

  • tag: optional tag (e.g. 021A) or tag and occurence (e.g. 009P/09) or a full line of PICA+ format to parse.
  • occ: optional occurence indicator (01 to 99)
  • ...:
PicaField:all (code, ...)
Returns a list of all matching values

Parameters

  • code:
  • ...: locator and/or filters

Usage

  • x,y,z = field:all()
  • n = field:all('a',patternfilter('^%d+$'))
PicaField:append (...)
Appends one or more subfields. Subfields can either be specified in PICA+ format or as pairs of subfield code (one character of [a-zA-Z0-9]) and subfield value. Empty subfield values (the empty string "") are ignored.

Parameters

  • ...:

Usage

  • f:append("x","foo","y","bar")
  • f:append("$xfoo$ybar")

Return value:

the field
PicaField:codes ()
Returns an ordered table of subfield codes. For instance for a field $xfoo$ybar$xdoz this method returns the table {'x','y','x'}.
PicaField:copy (full, subfields)
Copies a field.

Parameters

  • full:
  • subfields:

Usage

  • field:copy() full copy with tag, occ and all subfields
  • field:copy("123@") copy subfields but modify tag
  • field:copy("123@/01") copy subfields but modify tag and occ
  • field:copy("a-d") copy tag, occ, and selected subfields
  • field:copy("") copy only all subfields
PicaField:first (code, ...)
Returns the first value of a given subfield or an empty string.

Parameters

  • code:
  • ...: subfield code and/or optional filters
PicaField:join (sep, map)
Concatenate table of subfield values.

Parameters

  • sep:
  • map:
PicaRecord.new (str)
Creates a new PICA+ record. If you provide a string, it will be parsed as PICA+ format.

Parameters

  • str: (optional string) string to parse
PicaRecord.parse_field_locator (locator, subfield, ...)
Parses a field locator.

Parameters

  • locator:
  • subfield:
  • ...:
PicaRecord:all (field, subfield, ...)
Returns all matching subfield values (as table) or all matching fields (as record). You can filter fields by tag (and occurence indicator) and/or by using a filter method that is called for each field as filter(field). A field is only included in the returned record, if the filter method returns true. Note that the returned record contains references to the original fields instead of copies!

Parameters

  • field: (optional) field locator
  • subfield:
  • ...: function that is applied to each value as filter

Usage:

r:all('021A')

Return value:

table or PicaRecord
PicaRecord:append (field)
Appends a field to the record.

Parameters

  • field: PicaField object to append
PicaRecord:apply (...)
Apply one or more function to each field of the record. In contrast to PicaRecord:filter, the return values of functions are ignored and nothing is returned.

Parameters

  • ...: functions that are called for each field
PicaRecord:first (field, subfield, ...)
Returns the first matching field or subfield value

Parameters

  • field: locator of a field (AAAA or AAAA/ or AAAA/BB or AAAA/00)
  • subfield:
  • ...:

Usage:

rec["028A/"] returns field 028A but not 028A/xx, rec["028A"] returns field 028A or 028A/xx, rec["028A/00"] returns field 028A/xx but not or 028A, rec["028A/01"] returns field 028A/01
PicaRecord:get (query, ...)
Get matching values from the record. with error checking

Parameters

  • query:
  • ...:
PicaRecord:has (...)
Returns whether a given locator matches.

Parameters

  • ...:
PicaRecord:map (map)
Transforms the record to a table using a mapping table.

Parameters

  • map: mapping table

Return values:

  1. table of transformed values
  2. table of errors or nil of no errors occurred
filtervalue (value, ...)
Simply returns a value, optionally filtered by one or more functions. If a filter function returns true, the original value is returned. If a filter function returns no string or the empty string, nil is returned.

Parameters

  • value:
  • ...:
formatfilter (format)
Returns a filter function based on a Lua string format.

Parameters

Usage:

field:first('a',formatfilter('a is: %s'))
patternfilter (pattern)
Returns a filter function based on a Lua pattern. The returned filter function removes all values that do not match the pattern. If the pattern contains a capture expression, each value is replaced by the first captured value.

Parameters

Usage

  • check digit: record:find(tag,sf,patternfilter('%d'))
  • extract digit: record:find(tag,sf,patternfilter('(%d)'))
string.notempty (self)
Returns a string or nil if the string is empty

Parameters

  • self:
table.append (t, a)
Insert all values with integer keys from one table to another.

Parameters

  • t: the table to modify
  • a: the table to concat to table a

Valid XHTML 1.0!