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...

Public Attributes
const	ConstantConflictList = ("name", "struct", "code", "default")
	field keys that conflict with "constant"

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
*hash	crec
	(deprecated) constant hash value for output mappings
*string	date_format
	the global date format for parsing dates
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
*string	number_format
	the global number format for parsing numbers
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)