1 | /* |
2 | * This file is part of the syndication library |
3 | * |
4 | * Copyright (C) 2005 Frank Osterfeld <osterfeld@kde.org> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Library General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Library General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | * |
21 | */ |
22 | |
23 | #ifndef SYNDICATION_PARSERCOLLECTION_H |
24 | #define SYNDICATION_PARSERCOLLECTION_H |
25 | |
26 | #include <syndication/specificdocument.h> |
27 | #include <syndication/abstractparser.h> |
28 | #include <syndication/documentsource.h> |
29 | #include <syndication/feed.h> |
30 | #include <syndication/global.h> |
31 | #include <syndication/mapper.h> |
32 | |
33 | #include <QtCore/QString> |
34 | |
35 | namespace Syndication { |
36 | |
37 | |
38 | /** |
39 | * A collection of format-specific parser implementations. |
40 | * To parse a feed source, pass it to the parse() method of this class. |
41 | * In most cases, you should use the global singleton instance |
42 | * Syndication::parserCollection(). |
43 | * When loading the source from the web, use Loader instead of using |
44 | * this class directly. |
45 | * |
46 | * Example code: |
47 | * |
48 | * @code |
49 | * ... |
50 | * QFile someFile(somePath); |
51 | * ... |
52 | * DocumentSource src(someFile.readAll()); |
53 | * someFile.close(); |
54 | * |
55 | * FeedPtr feed = parserCollection()->parse(src); |
56 | * |
57 | * if (feed) |
58 | * { |
59 | * QString title = feed->title(); |
60 | * QList<ItemPtr> items = feed->items(); |
61 | * ... |
62 | * } |
63 | * @endcode |
64 | * |
65 | * The template parameter T is the abstraction class parsed documents |
66 | * should be mapped to. If you want to use your own abstraction MyFeed, |
67 | * implement ParserCollection<MyFeed> (Note that you have to provide |
68 | * mapper implementations for every feed format then). |
69 | * |
70 | * @author Frank Osterfeld |
71 | */ |
72 | template <class T> |
73 | class SYNDICATION_EXPORT ParserCollection |
74 | { |
75 | public: |
76 | |
77 | /** destructor */ |
78 | virtual ~ParserCollection() {} |
79 | |
80 | /** |
81 | * tries to parse a given source with the parsers registered. |
82 | * The source is passed to the first parser that accepts it. |
83 | * |
84 | * @param source The source to be parsed |
85 | * @param formatHint An optional hint which parser to test first. If |
86 | * there is a parser with the given hint as format string (e.g., |
87 | * "rss2", "atom", "rdf"...), it is asked first to accept the source. |
88 | * This can avoid unnecessary AbstractParser::accept() checks and speed |
89 | * up parsing. See also AbstractParser::format(). |
90 | * @return The feed document parsed from the source, or NULL if no |
91 | * parser accepted the source. |
92 | */ |
93 | virtual boost::shared_ptr<T> parse(const DocumentSource& source, |
94 | const QString& formatHint=QString()) = 0; |
95 | |
96 | |
97 | /** |
98 | * returns the error code of the last parse() call. |
99 | * |
100 | * @return the last error, or Success if parse() was successful |
101 | * or not yet called at all. |
102 | */ |
103 | virtual ErrorCode lastError() const = 0; |
104 | |
105 | /** |
106 | * Adds a parser and corresponding mapper to the collection. |
107 | * AbstractParser::format() must be unique |
108 | * in the collection. If there is already a parser with the same format |
109 | * string, the parser isn't added. |
110 | * |
111 | * @note ownership for both @c parser and @c mapper is taken by the |
112 | * implementation, so don't delete them in your code! |
113 | * |
114 | * @param parser The parser to be registered |
115 | * @param mapper the mapper that should be used for building the |
116 | * abstraction |
117 | * @return whether the parser was successfully registered or not. |
118 | */ |
119 | virtual bool registerParser(AbstractParser* parser, Mapper<T>* mapper) = 0; |
120 | |
121 | /** |
122 | * Changes the specific format to abstraction mapping for a parser. |
123 | * |
124 | * @param format the format string of the parser whose |
125 | * mapping should be changed. See AbstractParser::format. |
126 | * @param mapper Mapper implementation doing the mapping from the |
127 | * format specific representation to abstraction of type T. |
128 | */ |
129 | virtual void changeMapper(const QString& format, Mapper<T>* mapper) = 0; |
130 | |
131 | }; |
132 | |
133 | } // namespace Syndication |
134 | |
135 | #endif // SYNDICATION_PARSERCOLLECTION_H |
136 | |