1/*
2 This file is part of the syndication library
3 SPDX-FileCopyrightText: 2005 Frank Osterfeld <osterfeld@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef SYNDICATION_PARSERCOLLECTION_H
9#define SYNDICATION_PARSERCOLLECTION_H
10
11#include "abstractparser.h"
12#include "documentsource.h"
13#include "feed.h"
14#include "global.h"
15#include "mapper.h"
16#include "specificdocument.h"
17
18#include <QString>
19
20namespace Syndication
21{
22/*!
23 * \class Syndication::ParserCollection
24 * \inmodule Syndication
25 * \inheaderfile Syndication/ParserCollection
26 *
27 * \brief A collection of format-specific parser implementations.
28 *
29 * To parse a feed source, pass it to the parse() method of this class.
30 *
31 * In most cases, you should use the global singleton instance
32 * Syndication::parserCollection().
33 *
34 * When loading the source from the web, use Loader instead of using
35 * this class directly.
36 *
37 * Example code:
38 *
39 * \code
40 * ...
41 * QFile someFile(somePath);
42 * ...
43 * DocumentSource src(someFile.readAll());
44 * someFile.close();
45 *
46 * FeedPtr feed = parserCollection()->parse(src);
47 *
48 * if (feed)
49 * {
50 * QString title = feed->title();
51 * QList<ItemPtr> items = feed->items();
52 * ...
53 * }
54 * \endcode
55 *
56 * The template parameter T is the abstraction class parsed documents
57 * should be mapped to. If you want to use your own abstraction MyFeed,
58 * implement ParserCollection<MyFeed> (Note that you have to provide
59 * mapper implementations for every feed format then).
60 */
61template<class T>
62class SYNDICATION_EXPORT ParserCollection
63{
64public:
65 virtual ~ParserCollection()
66 {
67 }
68
69 /*!
70 * tries to parse a given source with the parsers registered.
71 * The source is passed to the first parser that accepts it.
72 *
73 * \a source The source to be parsed
74 *
75 * \a formatHint An optional hint which parser to test first. If
76 * there is a parser with the given hint as format string (e.g.,
77 * "rss2", "atom", "rdf"...), it is asked first to accept the source.
78 * This can avoid unnecessary AbstractParser::accept() checks and speed
79 * up parsing. See also AbstractParser::format().
80 *
81 * Returns the feed document parsed from the source, or NULL if no
82 * parser accepted the source.
83 */
84 virtual QSharedPointer<T> parse(const DocumentSource &source, const QString &formatHint = QString()) = 0;
85
86 /*!
87 * Returns the error code of the last parse() call, or Success if parse() was successful
88 * or not yet called at all.
89 */
90 virtual ErrorCode lastError() const = 0;
91
92 /*!
93 * Adds a parser and corresponding mapper to the collection.
94 *
95 * AbstractParser::format() must be unique
96 * in the collection. If there is already a parser with the same format
97 * string, the parser isn't added.
98 *
99 * \note ownership for both \c parser and \c mapper is taken by the
100 * implementation, so don't delete them in your code!
101 *
102 * \a parser The parser to be registered
103 *
104 * \a mapper the mapper that should be used for building the
105 * abstraction
106 *
107 * Returns whether the parser was successfully registered or not.
108 */
109 virtual bool registerParser(AbstractParser *parser, Mapper<T> *mapper) = 0;
110
111 /*!
112 * Changes the specific format to abstraction mapping for a parser.
113 *
114 * \a format the format string of the parser whose
115 * mapping should be changed. See AbstractParser::format.
116 *
117 * \a mapper Mapper implementation doing the mapping from the
118 * format specific representation to abstraction of type T.
119 */
120 virtual void changeMapper(const QString &format, Mapper<T> *mapper) = 0;
121};
122
123} // namespace Syndication
124
125#endif // SYNDICATION_PARSERCOLLECTION_H
126

source code of syndication/src/parsercollection.h