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