1/*
2 This file is part of the syndication library
3 SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef SYNDICATION_MAPPER_H
9#define SYNDICATION_MAPPER_H
10
11#include "syndication_export.h"
12
13#include <QSharedPointer>
14
15namespace Syndication
16{
17class SpecificDocument;
18typedef QSharedPointer<SpecificDocument> SpecificDocumentPtr;
19
20/*!
21 * \class Syndication::Mapper
22 * \inmodule Syndication
23 * \inheaderfile Syndication/Mapper
24 *
25 * \brief A mapper maps an SpecificDocument to something else.
26 *
27 * The type of this "something else" is specified by the template
28 * parameter T.
29 *
30 * In the default implementation it is used with the Feed interface,
31 * but it is not limited to that. T can be an arbitrary class.
32 *
33 * There are three (advanced and hopefully rare) use cases
34 * that require you to implement your own mapper.
35 * For more information on the possible uses, see TODO: link docs.
36 *
37 * 1) Add your own feed parser. In case you need support for another
38 * feed format (Okay! News, CDF, completely backward-incompatible Atom 5.0,
39 * you name it), you can
40 * implement AbstractParser and SpecificDocument for it and provide a
41 * Mapper&lt;Feed>
42 *
43 * \code
44 * class OkayNewsMapper : public Mapper<Feed>
45 * {
46 * public:
47 *
48 * virtual FeedPtr map(SpecificDocumentPtr doc) const { ... }
49 * };
50 *
51 * parserCollection()->registerParser(new OkayNews::Parser, new OkayNewsMapper);
52 * \endcode
53 *
54 * 2) Implement your own mapper for the Feed abstraction, for an
55 * existing parser. E.g. if you think Syndication does map Atom
56 * all wrong, you can implement your own Atom mapper and use that instead
57 * of the default one.
58 *
59 * \code
60 * class MyAtomMapper : public Mapper<Feed>
61 * {
62 * public:
63 *
64 * virtual FeedPtr map(SpecificDocumentPtr doc) const { ... }
65 * };
66 *
67 * parserCollection()->changeMapper("atom", new MyAtomMapper);
68 * \endcode
69 *
70 * 3) Use your own abstraction. In case the Feed interface
71 * does not fit your needs, you can use your own interface, let's
72 * say "MyFeed". Be aware you have to implement custom mappings for
73 * all feed formats then:
74 *
75 * \code
76 * class MyFeed
77 * {
78 * public:
79 *
80 * QString title() const; // my special title
81 * QList<Article> articles() const; // I name it articles
82 * };
83 *
84 * class MyAtomMapper : public Mapper<MyFeed> { ... };
85 * class MyRDFMapper : public Mapper<MyFeed> { ... };
86 * class MyRSS2Mapper : public Mapper<MyFeed> { ... };
87 *
88 * ParserCollection<MyFeed>* coll = new ParserCollection<MyFeed>;
89 * coll->registerParser(new Atom::Parser, new MyAtomMapper);
90 * coll->registerParser(new RDF::Parser, new MyRDFMapper);
91 * coll->registerParser(new RSS2::Parser, new MyRSS2Mapper);
92 * \endcode
93 */
94template<class T>
95class SYNDICATION_EXPORT Mapper
96{
97public:
98 virtual ~Mapper()
99 {
100 }
101
102 /*!
103 * maps a format-specific document to abstraction of type T.
104 *
105 * \note implementations may assume \a doc to have the
106 * type whose mapping they implement and may just statically cast
107 * to the subclass without further checking. If you register your
108 * own mapper, it's your responsibility to register the mapper
109 * only for the format it actually handles.
110 *
111 * \a doc the document to map.
112 *
113 * Returns a newly created object implementing the abstraction T.
114 */
115 virtual QSharedPointer<T> map(SpecificDocumentPtr doc) const = 0;
116};
117
118} // namespace syndication
119
120#endif // SYNDICATION_MAPPER_H
121

source code of syndication/src/mapper.h