File indexing completed on 2024-12-22 04:59:44

 /*
    SPDX-FileCopyrightText: 2017 Volker Krause <vkrause@kde.org>
 
    SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #pragma once
 
 #include "kitinerary_export.h"
 
 #include <QList>
 #include <QVariant>
 
 #include <memory>
 
 namespace KItinerary {
 
 class ExtractorPostprocessorPrivate;
 
 /** Post-process extracted data to filter out garbage and augment data from other sources.
  *
  *  In detail, this performs the tasks listed below for all data elements fed into it.
  *
  *  @section postproc_normalize Normalization
  *
  *  Basic normalization for e.g. renamed properties of older schema.org versions is already
  *  covered by JsonLdImportFilter, post-processing covers the more elaborate normalization steps,
  *  such as:
  *  - translate human readable and possibly localized country names into ISO 3166-1 codes.
  *  - expand IATA BCBP ticket tokens (see IataParser).
  *
  *  @section postproc_augment Augmentation
  *
  *  That is, add additional information derived from a built-in knowledge base (see KnowledgeDb).
  *  This includes:
  *  - Add timezone information to arrival and departure times.
  *  - Add geo coordinates and country information to known airports or train stations.
  *
  *  @section postproc_merge Merge Duplicates
  *
  *  Duplicate elements that might have been the result of two overlapping extractors (e.g. when
  *  extracting two different MIME parts of an email referring to the same reservation) are merged.
  *
  *  @section postproc_validation Validation
  *
  *  At this point, all invalid elements are discarded. The definition of invalid is fairly loose though,
  *  and typically only covers elements that are explicitly considered unusable. Examples:
  *  - A Flight missing a departure day or destination.
  *  - A LodigingReservation without an attached LodgingBusiness.
  *  - etc.
  *
  *  Validation can be disabled and done separately using KItinerary::ExtractorValidator, in case you
  *  want more control over which elements are considered valid. See setValidationEnabled().
  *
  *  @section postproc_sort Sorting
  *
  *  Finally the remaining elements are sorted based on their relevant date (see SortUtil). This
  *  makes the data usable for basic display right away, but it for example doesn't do multi-traveler
  *  aggregation, that's still left for the display layer.
  */
 class KITINERARY_EXPORT ExtractorPostprocessor
 {
 public:
     ExtractorPostprocessor();
     ExtractorPostprocessor(const ExtractorPostprocessor&) = delete;
     ExtractorPostprocessor(ExtractorPostprocessor&&) noexcept;
     ~ExtractorPostprocessor();
 
     /** This will normalize and augment the given data elements and merge them with
      *  already added data elements if applicable.
      */
     void process(const QList<QVariant> &data);
 
     /** This returns the final result of all previously executed processing steps
      *  followed by sorting and filtering out all invalid data elements.
      */
     QList<QVariant> result() const;
 
     /** The date the reservation(s) processed here have been made, if known.
      *  This is used for determining the year of incomplete dates provided by
      *  various sources. Therefore this has to be somewhen before the reservation
      *  becomes due.
      */
     void setContextDate(const QDateTime &dt);
 
     /** Enable or disable validation.
      *  By default this is enabled, and will discard all unknown types
      *  and incomplete items. If you need more control over this, disable
      *  this here and pass the items through ExtractorValidator yourself
      *  (or even use an entirely different validation mechanism entirely).
      *  @see ExtractorValidator.
      *  @deprecated Has no functionality anymore, remove and use ExtractorValidator
      *  explicitly instead.
      */
     [[deprecated("has no functionality anymore")]] void setValidationEnabled(bool validate);
 
 private:
     std::unique_ptr<ExtractorPostprocessorPrivate> d;
 };
 
 }