Syndication

parsercollection.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2005 Frank Osterfeld <[email protected]>
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 <syndication/abstractparser.h>
12 #include <syndication/documentsource.h>
13 #include <syndication/feed.h>
14 #include <syndication/global.h>
15 #include <syndication/mapper.h>
16 #include <syndication/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&lt;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 */
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
FeedPtr parse(const DocumentSource &src, const QString &formatHint)
parses a document from a source and returns a new Feed object wrapping the feed content.
Definition: global.cpp:54
virtual ~ParserCollection()
destructor
Interface for all parsers.
ErrorCode
error code indicating fetching or parsing errors
Definition: global.h:70
A mapper maps an SpecificDocument to something else.
Definition: mapper.h:91
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 03:52:05 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.