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 | checkInputField (string k, string name)
| raises an error if an invalid input field name is declared; only call this if "input" is defined
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 mapv, *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 More...
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...
string | getFieldName (string fname)
| returns a descriptive name of the given field if possible, otherwise returns the field name itself
*hash | getInputRecord ()
| returns the value of the `"input"` option
*hash | getOutputRecord ()
| returns the value of the `"output"` option
any | getRuntime (string key)
| get current runtime option value for a key More...
| logOutput (hash h)
| calls the output logging closure or call reference (if any) to log the output record
list | mapAll (list recs)
| maps all input records and returns the mapped data as a list of output records More...
list | mapAll (hash 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 hash | mapDataIntern (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...
| replaceRuntime (*hash runtime)
| replaces runtime options More...
| resetCount ()
| resets the internal record count More...
| setRuntime (string key, any value)
| set the runtime option with "key" to value "value" More...
| setRuntime (hash runtime)
| adds runtime options to the current runtime option hash More...
private | setup (hash mapv, *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...

## Public Attributes

const | ConstantConflictList = ("name", "struct", "code", "default")
| field keys that conflict with "constant" and "index"
const | OptionKeys
| constructor option keys (can be extended by subclassing and reimplementing optionKeys())
const | OutputKeys
| output option keys
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())

## 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
bool | allow_output_dot = False
| do not assume structured/hash output when output field names have a `"."` in them; instead allow output field names to have a `"."` in them
int | count = 0
| count of records mapped
*string | date_format
| the global date format for parsing dates
string | encoding = "utf-8"
| the output character encoding; if not given then the output encoding is assumed to be UTF-8
*code | info_log
| an optional info logging callback; must accept a sprintf()-style format specifier and optional arguments
*hash | input
| an optional description of possible input hash keys
*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())
bool | m_empty_strings_to_nothing = False
| flag to enforce deletion of the empty string in the output record More...
*hash | m_runtime
| current runtime values More...
hash | mapc
| 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
*string | number_format
| the global number format for parsing numbers
*hash | output
| an optional description of the output data structure
*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
bool | trunc_all = False
| truncate all option

## 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 | mapv,
|  | *hash | opts
| ) |  |

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

Example:
  {.py}
  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"),
  );
  Mapper mapv(DataMap);

Parameters

  mapv | 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 documentation 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)

private Mapper::Mapper::error | ( | string | fmt | ) |

throws a `MAP-ERROR` exception; prepends the map name to the description if known

if this method is subclassed, it must also cause an exception to be thrown

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

returns the internal record count

See Also
  resetCount()

any Mapper::Mapper::getRuntime | ( | string | key | ) |

get current runtime option value for a key

Parameters

  key | the runtime option key

Returns
  a runtime value if the key exists in the current runtime option hash and is set

See Also
  - Mapper Runtime Options
  - replaceRuntime()
  - setRuntime()

Since
  Mapper 1.1

list Mapper::Mapper::mapAll | ( | list | 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

list Mapper::Mapper::mapAll | ( | hash | 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 | a hash of lists 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())
  - uses mapDataIntern() to map the data, then logOutput() is called for each output row

private hash Mapper::Mapper::mapDataIntern | ( | 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())
  - this is the same as mapData() except no output logging is performed

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::replaceRuntime | ( | *hash | runtime | ) |

replaces runtime options

Parameters

  runtime | a hash of runtime options to use to replace the current runtime option hash

See Also
  - Mapper Runtime Options
  - getRuntime()
  - setRuntime()

Since
  Mapper 1.1

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

resets the internal record count

See Also
  getCount()

Mapper::Mapper::setRuntime | ( | string | key,
|  | any | value
| ) |  |

set the runtime option with "key" to value "value"

Parameters

  key | a string with valid runtime key
  value | anything passed to the current runtime `key`

See Also
  - Mapper Runtime Options
  - replaceRuntime()
  - setRuntime()

Since
  Mapper 1.1

Mapper::Mapper::setRuntime | ( | hash | runtime | ) |

adds runtime options to the current runtime option hash

Parameters

  runtime | a hash of runtime options to add to the current runtime option hash

See Also
  - Mapper Runtime Options
  - replaceRuntime()
  - setRuntime()

Since
  Mapper 1.1

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)

## Member Data Documentation

bool Mapper::Mapper::m_empty_strings_to_nothing = False

private

flag to enforce deletion of the empty string in the output record

Since
  Mapper 1.1

*hash Mapper::Mapper::m_runtime

private

current runtime values

Since
  Mapper 1.1