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
35namespace 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&lt;MyFeed> (Note that you have to provide
68 * mapper implementations for every feed format then).
69 *
70 * @author Frank Osterfeld
71 */
72template <class T>
73class 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