lib/Yara/Parser.h

   1 /*
   2  * Yara: Yet Another RSS Aggregator
   3  * Copyright (C) 2007  Ronald Landheer-Cieslak
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation, either version 3 of the License.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17 #ifndef _yara_parser_h
  18 #define _yara_parser_h
  19
  20 #include "Details/prologue.h"
  21 #include <iostream>
  22 #include <string>
  23 #include "Details/Language.h"
  24 #include "Details/ChannelInfo.h"
  25 #include "Details/ItemInfo.h"
  26
  27 namespace Yara
  28 {
  29         class Parser;
  30
  31         /** Parse everything there is to parse in an input stream. */
  32         Yara_API Parser & operator>>(std::istream & is, Parser & parser);
  33
  34         /** An full-fledged RSS parser for versions 0.92, 0.93 and 2.0 of the
  35          * specification. */
  36         class Yara_API Parser
  37         {
  38         public :
  39                 //! A type convertible to bool but with no other utility
  40                 typedef int Parser::* Bool;
  41
  42                 //! Construct a parser that is ready to parse a feed
  43                 Parser();
  44                 //! Destroy the parser and free all related resources
  45                 ~Parser();
  46
  47                 /** Parse a feed.
  48                  * Parsing a feed will add the data in it to the internal state of
  49                  * the parser. You can only do this with a fresh parser or one on which
  50                  * you have called reset() since the last complete parse. If a parse
  51                  * is still en-route (because the previous parse was not complete)
  52                  * you can use this method to add chunks of the feed to the parse result.
  53                  * You can find out whether the parser is in a state in which it can parse
  54                  * by casting it to Bool.
  55                  *
  56                  * \param feed the feed to parse
  57                  * \throws a plethora of exceptions if the feed is not valid, all
  58                  *         directly or indirectly derived from std::exception. */
  59                 void parse(const std::string & rss_feed);
  60
  61                 /** Finish parsing the internal buffers.
  62                  * Once all of the feed has been parsed, you can use this function to try
  63                  * and finish parsing. In stead of throwing an exception at you if it fails
  64                  * to finalize, it will tell you politely with a return value. Accessors
  65                  * that allow you to access the contents of the parsed feed will implicitly
  66                  * call this function if needed, but they will throw if the feed is not complete.
  67                  * Once this function is called, you can no longer add input to the parser without
  68                  * resetting first. */
  69                 bool finish();
  70
  71                 /** Cast to Bool operator.
  72                  * Bool is convertible to bool, so you can use an instance of the parser
  73                  * in a branch expression (if, while, etc.). The result of this cast
  74                  * will be convertible to true if the parser is in a state in which it
  75                  * can parse more input, false otherwise. */
  76                 operator Bool ();
  77
  78                 /** Reset the parser and clear its contents.
  79                  * Resets the state of the parser, after which it will be able to parse
  80                  * fresh input. */
  81                 void reset();
  82
  83         /* querying the parse result */
  84                 //! Get the version of the RSS stream we've passed, as reported by the stream itself
  85                 std::string getRSSVersion() const;
  86
  87                 //! Get the title of the parsed channel
  88                 Details::ChannelInfo getChannelInfo() const;
  89
  90                 //! Get the number of items parsed
  91                 unsigned int getItemCount() const;
  92                 //! Get an item by index
  93                 Details::ItemInfo getItem(unsigned int index) const;
  94         private :
  95                 struct Data;
  96                 struct NoThrow {};
  97
  98                 // neither CopyConstructible nor Assignable
  99                 Parser(const Parser &);
 100                 Parser & operator=(const Parser &);
 101
 102                 void finish_() const;
 103                 bool finish_(const NoThrow &) const;
 104
 105                 int unused_except_for_cast_;
 106                 Data * data_;
 107
 108                 friend Yara_API Parser & operator>>(std::istream & is, Parser & parser);
 109         };
 110 }
 111
 112 #endif