All Classes Namespaces Functions Variables Groups Pages
Mapper::Mapper Class Reference

this class is a base class for mapping data; see Mapper Examples for usage examples More...

## Public Member Functions

private | checkMap ()
| verifies the input map in the constructor
private | checkMapField (string k, reference fh, *hash th)
| perform per-field pre-processing on the passed map in the constructor More...
private | checkTimezoneOption (hash opts, string rn)
| verifies a timezone constructor option
| constructor (hash map, *hash opts)
| builds the object based on a hash providing field mappings, data constraints, and optionally custom mapping logic More...
private | constructor ()
| private constructor for subclasses
private | convertToHash (int t, string k, reference fh)
| convert a field definition to a hash if possible
private | error (string fmt)
| throws a `MAP-ERROR` exception; prepends the map name to the description if known
private | error2 (string ex, string fmt)
| throws the given exception; prepends the map name to the description if known
int | getCount ()
| returns the internal record count More...
private bool | hasMapping (hash fh)
| returns True if the field has a mapping, False if not
list | mapAll (softlist recs)
| maps all input records and returns the mapped data as a list of output records More...
hash | mapData (hash rec)
| processes the input record and returns a hash of the mapped values where the keys in the hash returned are the target field names; the order of the fields in the hash returned is the same order as the keys in the map hash. More...
private | mapFieldType (string key, hash m, reference v, hash rec)
| performs type handling
private any | mapSubclass (hash m, any v)
| to be overridden as necessary in subclasses
hash | optionKeys ()
| returns a list of valid constructor options for this class (can be overridden in subclasses) More...
| resetCount ()
| resets the internal record count More...
private | setup (hash map, *hash opts)
| sets up the mapper object before checking the mapper hash
hash | validKeys ()
| returns a list of valid field keys for this class (can be overridden in subclasses) More...
hash | validTypes ()
| returns a list of valid field types for this class (can be overridden in subclasses) More...

## Private Attributes

bool | allow_dot = False
| do not assume struct when field names have a `"."` in them; instead allow input field names to have a `"."` in them
int | count = 0
| count of records mapped
*hash | crec
| constant hash value for output mappings
string | enc = "utf-8"
| the output character encoding; if not given then the output encoding is assumed to be UTF-8
*code | input_log
| an optional input data logging callback; must accept a hash giving the input data hash
Qore::TimeZone | input_timezone = TimeZone::get()
| the timezone for input fields in case of parsing text values; if not set defaults to the current TimeZone (see Qore::TimeZone::get())
hash | map
| the hash providing output field names and mappings
*string | name
| the optional name for the object (for example a table name); will be prepended to field names in error messages
const | OptionKeys
| constructor option keys (can be extended by subclassing and reimplementing optionKeys())
*code | output_log
| an optional output data logging callback; must accept a hash giving the output data hash
*Qore::TimeZone | timezone
| an optional timezone for output date fields
*code | trunc
| an optional field truncation callback
bool | trunc_all = False
| truncate all option
const | ValidKeys
| default known mapper hash field keys (can be extended by subclassing and reimplementing validKeys())
const | ValidTypes
| default known field types (can be extended by subclassing and reimplementing validTypes() and mapFieldType())

## Detailed Description

this class is a base class for mapping data; see Mapper Examples for usage examples

## Member Function Documentation

private Mapper::Mapper::checkMapField | ( | string | k,
|  | reference | fh,
|  | *hash | th
| ) |  |

perform per-field pre-processing on the passed map in the constructor

Parameters

  k | the field name
  fh | a reference to the field's value in the map

Mapper::Mapper::constructor | ( | hash | map,
|  | *hash | opts
| ) |  |

builds the object based on a hash providing field mappings, data constraints, and optionally custom mapping logic

Example:
  const DataMap = (
  # output field: "id" mapper from the "Id" element of any "^attributes^" hash in the input record
  "id": "^attributes^.Id",
  # output field: "name": maps from an input field with the same name (no translations are made)
  "name": True,
  # output field: "explicit_count": maps from the input "Count" field, if any value is present then it is converted to an integer
  "explicit_count": ("type": "int", "name": "Count"),
  # output field: "implicit_count": runs the given code on the input record and retuns the result, the code returns the number of "Products" sub-records
  "implicit_count": int sub (any $ignored, hash $rec) { return $rec.Products.size(); },
  # output field: "order_date": converts the "OrderDate" string input field to a date in the specified format
  "order_date": ("name": "OrderDate", "date_format": "DD.MM.YYYY HH:mm:SS.us"),
  );
  my Mapper $map(DataMap);

Parameters

  map | a hash providing field mappings; each hash key is the name of the output field; each value is either True (meaning no translations are done; the data is copied 1:1) or a hash describing the mapping; see Mapper Specification Format for detailed documnentation for this option
  opts | an optional hash of options for the mapper; see Mapper Options for a description of valid mapper options

Exceptions

  MAP-ERROR | the map hash has a logical error (ex: `"trunc"` key given without `"maxlen"`, invalid map key)

int Mapper::Mapper::getCount | ( |  | ) |

returns the internal record count

See Also
  resetCount()

list Mapper::Mapper::mapAll | ( | softlist | recs | ) |

maps all input records and returns the mapped data as a list of output records

this method applies the mapData() method to all input records and returns the resulting list

Parameters

  recs | the list of input records

Returns
  the mapped data as a list of output records

Exceptions

  MISSING-INPUT | a field marked mandatory is missing
  STRING-TOO-LONG | a field value exceeds the maximum value and the 'trunc' key is not set
  INVALID-NUMBER | the field is marked as numeric but the input value contains non-numeric data

hash Mapper::Mapper::mapData | ( | hash | rec | ) |

processes the input record and returns a hash of the mapped values where the keys in the hash returned are the target field names; the order of the fields in the hash returned is the same order as the keys in the map hash.

Parameters

  rec | the record to translate

Returns
  a hash of field values in the target format based on the input data and processed according to the logic in the map hash

Exceptions

  MISSING-INPUT | a field marked mandatory is missing
  STRING-TOO-LONG | a field value exceeds the maximum value and the 'trunc' key is not set
  INVALID-NUMBER | the field is marked as numeric but the input value contains non-numeric data

Note
  each time this method is executed successfully, the record count is updated (see getCount() and resetCount())

hash Mapper::Mapper::optionKeys | ( |  | ) |

returns a list of valid constructor options for this class (can be overridden in subclasses)

Returns
  a list of valid constructor options for this class (can be overridden in subclasses)

Mapper::Mapper::resetCount | ( |  | ) |

resets the internal record count

See Also
  getCount()

hash Mapper::Mapper::validKeys | ( |  | ) |

returns a list of valid field keys for this class (can be overridden in subclasses)

Returns
  a list of valid field keys for this class (can be overridden in subclasses)

hash Mapper::Mapper::validTypes | ( |  | ) |

returns a list of valid field types for this class (can be overridden in subclasses)

Returns
  a list of valid types for this class (can be overridden in subclasses)