Syndication

parsercollection.h
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 * 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 */
56template<class T>
57class SYNDICATION_EXPORT ParserCollection
58{
59public:
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
Interface for all parsers.
A mapper maps an SpecificDocument to something else.
Definition mapper.h:92
A collection of format-specific parser implementations.
virtual ~ParserCollection()
destructor
virtual QSharedPointer< T > parse(const DocumentSource &source, const QString &formatHint=QString())=0
tries to parse a given source with the parsers registered.
virtual ErrorCode lastError() const =0
returns the error code of the last parse() call.
virtual void changeMapper(const QString &format, Mapper< T > *mapper)=0
Changes the specific format to abstraction mapping for a parser.
virtual bool registerParser(AbstractParser *parser, Mapper< T > *mapper)=0
Adds a parser and corresponding mapper to the collection.
ErrorCode
error code indicating fetching or parsing errors
Definition global.h:70
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:56:56 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.