File indexing completed on 2024-12-29 04:49:58

 /*
    SPDX-FileCopyrightText: 2017-2021 Volker Krause <vkrause@kde.org>
 
    SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #pragma once
 
 #include "abstractextractor.h"
 
 #include <memory>
 #include <vector>
 
 class QJsonObject;
 class QString;
 
 namespace KItinerary {
 class ExtractorFilter;
 class ScriptExtractorPrivate;
 
 /** A single unstructured data extraction rule set.
  *
  * These rules are loaded from JSON meta-data files in a compiled-in qrc file,
  * or from $XDG_DATA_DIRS/kitinerary/extractors.
  *
  * @section extractor_metadata Meta Data Format
  *
  * The meta-data files either contain a single JSON object or an array of JSON objects
  * with the following content:
  * - \c mimeType: The MIME type of the extractor, \c text if not specified.
  * - \c filter: An array of filters that are used to select this extractor for a given input file.
  * - \c script: A JavaScript file to execute.
  * - \c function: The entry point in the above mentioned script, @c main if not specified.
  *
  * The following extractor types are supported:
  * - \c text/plain: plain text, the argument to the script function is a single string.
  * - \c text/html: HTML documents, the argument to the script function is a KItinerary::HtmlDocument instance.
  * - \c application/pdf: PDF documents, the argument to the script function is a KItinerary::PdfDocument instance.
  * - \c application/vnd.apple.pkpass: Apple Wallet passes, the argument to the script function is a KPkPass::Pass instance.
  * - \c internal/event: iCalendar events, the argument to the script function is a KCalendarCore::Event instance.
  *
  * Filter definitions have the following field:
  * - \c mimeType: The MIME type of the document part this filter can match against.
  * - \c field: The name of the field to match against. This can be a field id in a Apple Wallet pass,
  *      A MIME message header name, a property on a Json-LD object or an iCal calendar or event.
  *      For plain text or binary content, this is ignored.
  * - \c match: A regular expression that is matched against the specified value (see QRegularExpression).
  * - \c scope: Specifies how the filter should be applied relative to the document node that is being extracted.
  *      One of @c Current, @c Parent, @c Children, @c Ancestors, @c Descendants (@c Current is the default).
  *
  * Example:
  * @code
  * [
  *   {
  *     "mimeType": "application/pdf",
  *     "filter": [ { "field": "From", "match": "@swiss.com", "mimeType": "message/rfc822", "scope": "Ancestors" } ],
  *     "script": "swiss.js",
  *     "function": "parsePdf"
  *   },
  *   {
  *     "mimeType": "application/vnd.apple.pkpass",
  *     "filter": [ { "field": "passTypeIdentifier", "match": "pass.booking.swiss.com", "mimeType": "application/vnd.apple.pkpass", "scope": "Current" } ],
  *     "script": "swiss.js",
  *     "function": "parsePkPass"
  *   }
  * ]
  * @endcode
  *
  * @section extractor_development Development
  *
  * For development it's convenient to symlink the extractors source folder to
  * $XDG_DATA_DIRS/kitinerary/extractors, so you can re-run a changed extractor
  * script without recompiling or restarting the application.
  *
  */
 class KITINERARY_EXPORT ScriptExtractor : public AbstractExtractor
 {
 public:
     explicit ScriptExtractor();
     ~ScriptExtractor();
 
     QString name() const override;
     bool canHandle(const ExtractorDocumentNode &node) const override;
     ExtractorResult extract(const ExtractorDocumentNode &node, const ExtractorEngine *engine) const override;
 
     /** The JS script containing the code of the extractor. */
     QString scriptFileName() const;
     /** The JS function entry point for this extractor, @c main if empty. */
     QString scriptFunction() const;
     /** Mime type this script extractor supports. */
     QString mimeType() const;
     /** Returns the filters deciding whether this extractor should be applied. */
     const std::vector<ExtractorFilter> &filters() const;
 
     ///@cond internal
     /** Load meta data from the given JSON object. */
     bool load(const QJsonObject &obj, const QString &fileName, int index = -1);
     /** Save extractor meta data to a JSON object. */
     QJsonObject toJson() const;
 
     /** Source file name. */
     QString fileName() const;
 
     void setMimeType(const QString &mimeType);
     void setScriptFileName(const QString &script);
     void setScriptFunction(const QString &func);
     void setFilters(std::vector<ExtractorFilter> &&filters);
     void setFilters(const std::vector<ExtractorFilter> &filters);
     ///@endcond
 
 private:
     std::unique_ptr<ScriptExtractorPrivate> d;
 };
 
 }