Qore Mapper Module Reference  1.4
 All Classes Namespaces Functions Variables Groups Pages
Mapper.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* Mapper.qm Copyright 2014 - 2017 Qore Technologies, s.r.o.
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
25 // minimum required Qore version
26 
27 // require type definitions everywhere
28 
29 // enable all warnings
30 
31 // do not use "$" for vars
32 
33 
34 /* Version History
35 */
36 
249 namespace Mapper {
252  class Mapper {
253 
254 public:
255  public :
257  const ConstantConflictList = ("name", "struct", "code", "default");
258 
260  const OptionKeys = (
261  "allow_dot": "allows input fields to have a dot in their name without implying a structured format",
262  "allow_output_dot": "allows output fields to have a dot in their name without implying a structured format",
263  "date_format": "gives the default format for parsing dates from strings; ex: \"MM/DD/YYYY HH:mm:SS\"",
264  "encoding": "gives the default output character encoding for string fields",
265  "info_log": "a call reference / closure for informational logging",
266  "input": "a hash describing the input record",
267  "input_log": "a call reference / closure for input record logging",
268  "input_timezone": "the default timezone to assume when parsing input dates",
269  "name": "the name of the Mapper object",
270  "number_format": "the default number format when parsing number fields from strings; ex: \".,\"",
271  "output": "a hash describing the output record",
272  "output_log": "a call reference / closure for input record logging",
273  "timezone": "the default output timezone for date/time values",
274  "runtime": "runtime options as a hash (see also setRuntime(), replaceRuntime())",
275  "empty_strings_to_nothing": "converts out record's empty strings and into NOTHING - actually the value is deleted",
276  );
277 
279  const ValidKeys = (
280  "name": True,
281  "struct": True,
282  "constant": True,
283  "index" : True,
284  "code": True,
285  "default": True,
286  "maxlen": True,
287  "trunc": True,
288  "mand": True,
289  "number": True,
290  "type": True,
291  "date_format": True,
292  "number_format": True,
293  "runtime" : True,
294  "empty_strings_to_nothing" : True,
295  );
296 
298  const ValidTypes = (
299  "number": True,
300  "integer": True,
301  "int": True, // is an alias for "integer"
302  "date": True,
303  "string": True,
304  );
305 
307  const OutputKeys = (
308  "desc": True,
309  "mand": True,
310  "maxlen": True,
311  "type": True,
312  );
313 
314 public:
315 
316  private :
319 
322 
325 
327  string encoding = "utf-8";
328 
330  *string name;
331 
333  *code info_log;
334 
336  *code input_log;
337 
339  *code output_log;
340 
343 
345  Qore::TimeZone input_timezone = TimeZone::get();
346 
348  bool trunc_all = False;
349 
351  bool allow_dot = False;
352 
355 
357  *string date_format;
358 
360  *string number_format;
361 
364 
367 
369  int count = 0;
370 
372 
375 
377 
380 
383 
386 
389 
392 
393 public:
394 
396 
419  constructor(hash mapv, *hash opts);
420 
421 
423 
424 private:
425  constructor();
426 public:
427 
428 
430 
431 private:
432  setup(hash mapv, *hash opts);
433 public:
434 
435 
437 
438 private:
439  checkMap();
440 public:
441 
442 
444 
445 private:
446  convertToHash(int t, string k, reference<any> fh);
447 public:
448 
449 
451 
452 private:
453  checkInputField(string k, string name);
454 public:
455 
456 
458 
462 private:
463  checkMapField(string k, reference<any> fh);
464 public:
465 
466 
468 
469 private:
470  checkTimezoneOption(hash opts, string rn);
471 public:
472 
473 
475 
493  setRuntime(string key, auto value);
494 
495 
497 
515  setRuntime(hash runtime);
516 
517 
519 
537  replaceRuntime(*hash runtime);
538 
539 
541 
552  auto getRuntime(string key);
553 
554 
556  string getFieldName(string fname);
557 
558 
560 
562  hash validKeys();
563 
564 
566 
568  hash validTypes();
569 
570 
572 
574  hash optionKeys();
575 
576 
578  *hash getInputRecord();
579 
580 
583 
584 
586 
595  list<hash> mapAll(list recs);
596 
597 
599 
608  list<hash> mapAll(hash recs);
609 
610 
612 
624  hash mapData(hash rec);
625 
626 
628 
641 private:
642  hash mapDataIntern(hash rec);
643 public:
644 
645 
647 
674 private:
675  nothing mapFieldIntern(reference<hash> h, string key, hash rec, bool do_list, int list_size);
676 public:
677 
678 
680 
681 private:
682  string truncateField(string k, string val, int ix, int sze, int maxlen);
683 public:
684 
685 
687 
688 private:
689  fieldLengthError(string k, string val, int ix, int sze, int maxlen, hash rc);
690 public:
691 
692 
694  logOutput(hash h);
695 
696 
698 
700  int getCount();
701 
702 
704 
706  resetCount();
707 
708 
710 
711 private:
712  mapFieldType(string key, hash m, reference<any> v, hash rec);
713 public:
714 
715 
717 
720 private:
721  error(string fmt);
722 public:
723 
724 
726 
727 private:
728  error2(string ex, string fmt);
729 public:
730 
731 
733 
734 private:
735  auto mapSubclass(hash m, auto v);
736 public:
737 
738  };
739 
742 
743 public:
744  public :
745 
746 public:
747 
748  private :
751 
752 public:
753 
755 
758 
759 
761  bool next();
762 
763 
765  bool valid();
766 
767 
769  bool hasBulk();
770 
771 
773 
777  list<hash> mapBulk(int size);
778 
779  };
780 
783 
784 public:
785  public :
786 
787 public:
788 
789  private :
792 
793 public:
794 
796 
803 
804 
806 
810 
811 
813  hash getValue();
814 
815 
817 
819  int getCount();
820 
821 
823 
825  resetCount();
826 
827  };
828 };
auto getRuntime(string key)
get current runtime option value for a key
Qore::AbstractIterator i
input iterator; AbstractIterator::getValue() must return a hash
Definition: Mapper.qm.dox.h:750
int getCount()
returns the internal record count
*hash getOutputRecord()
returns the value of the &quot;output&quot; option
const ConstantConflictList
field keys that conflict with &quot;constant&quot; and &quot;index&quot;
Definition: Mapper.qm.dox.h:257
*string date_format
the global date format for parsing dates
Definition: Mapper.qm.dox.h:357
hash validTypes()
returns a list of valid field types for this class (can be overridden in subclasses) ...
checkInputField(string k, string name)
raises an error if an invalid input field name is declared; only call this if &quot;input&quot; is defined ...
Mapper::Mapper mapc
data mapper
Definition: Mapper.qm.dox.h:791
nothing mapFieldIntern(reference< hash > h, string key, hash rec, bool do_list, int list_size)
maps a single field to the target
hash mapd
the hash with a subset of the mappings used dynamically
Definition: Mapper.qm.dox.h:321
bool next()
Moves the current position of the iterator to the next element; returns False if there are no more el...
const True
checkMap()
verifies the input map in the constructor
hash consth
map of constant fields
Definition: Mapper.qm.dox.h:388
string getFieldName(string fname)
returns a descriptive name of the given field if possible, otherwise returns the field name itself ...
bool m_empty_strings_to_nothing
flag to enforce deletion of the empty string in the output record
Definition: Mapper.qm.dox.h:379
const OptionKeys
constructor option keys (can be extended by subclassing and reimplementing optionKeys()) ...
Definition: Mapper.qm.dox.h:260
*code output_log
an optional output data logging callback; must accept a hash giving the output data hash ...
Definition: Mapper.qm.dox.h:339
*code info_log
an optional info logging callback; must accept a sprintf()-style format specifier and optional argume...
Definition: Mapper.qm.dox.h:333
provides a hash iterator based on a mapper object and an iterator input source
Definition: Mapper.qm.dox.h:782
convertToHash(int t, string k, reference< any > fh)
convert a field definition to a hash if possible
checkTimezoneOption(hash opts, string rn)
verifies a timezone constructor option
const False
bool allow_dot
do not assume struct when field names have a &quot;.&quot; in them; instead allow input field names to have a &quot;...
Definition: Mapper.qm.dox.h:351
this class is a base class for mapping data; see Mapper Examples for usage examples ...
Definition: Mapper.qm.dox.h:252
list list(...)
hash mapc
the hash providing output field names and mappings
Definition: Mapper.qm.dox.h:318
hash getValue()
returns the current row transformed with the mapper
int count
count of records mapped
Definition: Mapper.qm.dox.h:369
hash mapo
the hash of output records for key order
Definition: Mapper.qm.dox.h:324
resetCount()
resets the internal record count
constructor(Qore::AbstractIterator i, hash mapv, *hash opts)
creates the iterator from the arguments passed
list< hash > mapBulk(int size)
performs bulk mapping; if the iterator does not support bulk mapping then it is simulated in this met...
*string number_format
the global number format for parsing numbers
Definition: Mapper.qm.dox.h:360
auto mapSubclass(hash m, auto v)
to be overridden as necessary in subclasses
Qore::TimeZone input_timezone
the timezone for input fields in case of parsing text values; if not set defaults to the current Time...
Definition: Mapper.qm.dox.h:345
setup(hash mapv, *hash opts)
sets up the mapper object before checking the mapper hash
abstract base class for hash iterator mappping classes based on a mapper object and an iterator input...
Definition: Mapper.qm.dox.h:741
hash validKeys()
returns a list of valid field keys for this class (can be overridden in subclasses) ...
bool allow_output_dot
do not assume structured/hash output when output field names have a &quot;.&quot; in them; instead allow output...
Definition: Mapper.qm.dox.h:354
const ValidKeys
default known mapper hash field keys (can be extended by subclassing and reimplementing validKeys()) ...
Definition: Mapper.qm.dox.h:279
string truncateField(string k, string val, int ix, int sze, int maxlen)
called to truncate fields when processing hashes of lists
*list identl
list of fields to be mapped 1:1 input -&gt; output
Definition: Mapper.qm.dox.h:385
hash identh
map of fields to be mapped 1:1 input -&gt; output
Definition: Mapper.qm.dox.h:382
error(string fmt)
throws a MAP-ERROR exception; prepends the map name to the description if known
*Qore::TimeZone timezone
an optional timezone for output date fields
Definition: Mapper.qm.dox.h:342
logOutput(hash h)
calls the output logging closure or call reference (if any) to log the output record ...
bool trunc_all
truncate all option
Definition: Mapper.qm.dox.h:348
const ValidTypes
default known field types (can be extended by subclassing and reimplementing validTypes() and mapFiel...
Definition: Mapper.qm.dox.h:298
hash mapData(hash rec)
processes the input record and returns a hash of the mapped values where the keys in the hash returne...
constructor(Qore::AbstractIterator iter)
creates the iterator from the arguments passed
*hash output
an optional description of the output data structure
Definition: Mapper.qm.dox.h:366
setRuntime(string key, auto value)
set the runtime option with &quot;key&quot; to value &quot;value&quot;
constructor()
private constructor for subclasses
bool hasBulk()
returns True if the iterator supports bulk mode; this method returns False (the default) ...
*string name
the optional name for the object (for example a table name); will be prepended to field names in erro...
Definition: Mapper.qm.dox.h:330
string encoding
the output character encoding; if not given then the output encoding is assumed to be UTF-8 ...
Definition: Mapper.qm.dox.h:327
int getCount()
returns the internal record count
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
*hash input
an optional description of possible input hash keys
Definition: Mapper.qm.dox.h:363
*hash getInputRecord()
returns the value of the &quot;input&quot; option
hash mapDataIntern(hash rec)
processes the input record and returns a hash of the mapped values where the keys in the hash returne...
list< hash > mapAll(list recs)
maps all input records and returns the mapped data as a list of output records
*code input_log
an optional input data logging callback; must accept a hash giving the input data hash ...
Definition: Mapper.qm.dox.h:336
replaceRuntime(*hash runtime)
replaces runtime options
checkMapField(string k, reference< any > fh)
perform per-field pre-processing on the passed map in the constructor
hash hash(object obj)
mapFieldType(string key, hash m, reference< any > v, hash rec)
performs type handling
hash rconsth
map of constant runtime fields
Definition: Mapper.qm.dox.h:391
const OutputKeys
output option keys
Definition: Mapper.qm.dox.h:307
bool valid()
returns True if the iterator is currently pointing at a valid element, False if not ...
error2(string ex, string fmt)
throws the given exception; prepends the map name to the description if known
*hash m_runtime
current runtime values
Definition: Mapper.qm.dox.h:374
resetCount()
resets the internal record count
fieldLengthError(string k, string val, int ix, int sze, int maxlen, hash rc)
called when a field exceeds its maximum length when processing hashes of lists