Added documentation for CANDatabase + parse from directly from string + work on the interface of CANDatabase

Author: xatavian

include/CANDatabase.h

@@ -9,32 +9,128 @@
 #include "CANFrame.h"
 #include "CANDatabaseException.h"
 
+/**
+ * @brief A CAN database object
+ *
+ * A CAN database is an object regrouping frames and their signals' descriptions.
+ * 
+ * Public API: 
+ * - contains to check if a frame name/frame id is registered in the database
+ * - at to get the frame associated with the given frame name/frame id
+ *   the same operations are available with operator[]
+ * - addFrame and removeFrame to alter the database's content
+ *
+ * If the database was parsed from a file, the filename() method can be used to
+ * retrieve the name of the source file.
+ */
 class CANDatabase {
 public:
+  /**
+   * @brief Parse a CANDatabase from the given source file.
+   * @param filename Path to the file to parse
+   * @throw CANDatabaseException if the parsing failed
+   */
   static CANDatabase fromFile(const std::string& filename);
 
+  /**
+   * @brief Construct a CANDatabase object from a database described by src_string
+   * @param src_string Source string to parse
+   * @throw CANDatabaseException if the parsing failed
+   */
+  static CANDatabase fromString(const std::string& src_string);
+
 public:
+  /**
+   * @brief Creates a CANDatabase object with no source file
+   */
+  CANDatabase() = default;
+
+  /**
+   * @brief Creates a CANDatabase object that has been constructed from a file
+   * @param filename Name of the source file 
+   */
   CANDatabase(const std::string& filename);
 
 public:
-  std::weak_ptr<CANFrame> getFrameById(unsigned int idx) const;
-  std::weak_ptr<CANFrame> getFrameByName(const std::string& name) const;
-  std::vector<std::weak_ptr<CANFrame>> frames() const;
+  /**
+   * @brief Get the frame with the given frame name
+   */
+  std::weak_ptr<CANFrame> at(unsigned int frame_name) const;
+  
+  /**
+   * @brief Get the frame with the given frame id
+   */
+  std::weak_ptr<CANFrame> at(const std::string& frame_name) const;
+
+  /**
+   * @brief Get the frame with the given frame id
+   * @see getFrame
+   */
+  std::weak_ptr<CANFrame> operator[](unsigned int frame_idx) const;
+  
+  /**
+   * @brief Get the frame with the given frame name
+   */
+  std::weak_ptr<CANFrame> operator[](const std::string& frame_name) const;
 
-  bool hasFrame(unsigned int can_id) const;
-  bool hasFrame(const std::string& name) const;
+  /**
+   * @return true if the CANDatabase contains a frame with the given frame id
+   */
+  bool contains(unsigned int frame_id) const;
 
+  /**
+   * @return true if the CANDatabase contains a frame with the given frame name
+   */
+  bool contains(const std::string& frame_name) const;
+
+  /**
+   * @return File name of the source file if the database was constructed from a file.
+   *         Otherwise, returns an empty string.
+   */
   const std::string& filename() const;
+
+  
+  /* Set of methods used to behave like a STL container.
+     Very useful for range-based for loops. Inspired from std::map but
+     some features are missing. 
+     
+     The iterators have a random order. */
+public:
+  using container_type = std::map<unsigned int, std::shared_ptr<CANFrame>>;
+  using str_container_type = std::map<std::string, std::shared_ptr<CANFrame>>;
+  using iterator = container_type::iterator;
+  using const_iterator = container_type::const_iterator;
+  using reverse_iterator = container_type::reverse_iterator;
+  using const_reverse_iterator = container_type::const_reverse_iterator;
+
+  iterator begin();
+  const_iterator begin() const;
+  const_iterator cbegin() const;
+  
+  iterator end();
+  const_iterator end() const;
+  const_iterator cend() const;
+  
+  reverse_iterator rbegin();
+  const_reverse_iterator rbegin() const;
+  const_reverse_iterator crbegin() const;
+  
+  reverse_iterator rend();
+  const_reverse_iterator rend() const;
+  const_reverse_iterator crend() const;
+
   std::size_t size() const;
 
+  void clear();
+
   void addFrame(std::shared_ptr<CANFrame> frame);
   void removeFrame(unsigned int idx);
   void removeFrame(const std::string& name);
 
 private:
   std::string filename_;
-  std::map<std::string, std::shared_ptr<CANFrame>> strIndex_; // Index by frame name
-  std::map<unsigned int, std::shared_ptr<CANFrame>> intIndex_; // Index by CAN ID
+  str_container_type strIndex_; // Index by frame name
+  container_type intIndex_; // Index by CAN ID
 };
 
 #endif

include/DBCParser.h

@@ -9,6 +9,8 @@
 namespace DBCParser {
   CANDatabase fromTokenizer(const std::string& name,
                             Tokenizer& tokenizer);
+
+  CANDatabase fromTokenizer(Tokenizer& tokenizer);
 };
 
 #endif

include/Tokenizer.h

@@ -8,44 +8,56 @@
 
 class Tokenizer {
 public:
-  Tokenizer(const std::string& filename) :
-    inputstream(filename), currentChar(0), currentToken(), started(false), eofReached(false), addLine(false),
-    charCnt(0), lineCnt(0) {}
-
-  bool is_valid() const {
-    return inputstream.is_open();
-  }
-
+  Tokenizer();
+  virtual ~Tokenizer() = default;
+  
   Token getNextToken();
   Token getCurrentToken() const;
+  
   void skipLine();
   void skipUntil(const std::string& token);
   void saveToken(const Token& token);
 
   unsigned long long charCount() const;
   unsigned long long lineCount() const;
 
-private:
+protected:
   char getNextChar();
-
+  char getCurrentChar() const;
+  
 private:
-  bool isSeparator(char c) const;
-  bool isEOF(char c) const;
-  bool isDigit(char c) const;
-  bool isSpace(char c) const;
-  bool isIdentifierStart(char c) const;
-  bool isIdentifierPart(char c) const;
+  virtual char doGetNextChar() = 0;
 
 private:
-  std::ifstream inputstream;
   char currentChar;
   Token currentToken;
   std::vector<Token> tokenStack;
   bool started;
-  bool eofReached;
-  bool addLine;
+
+protected:
   unsigned long long charCnt;
   unsigned long long lineCnt;
+  bool addLine;
 };
 
+class FileTokenizer : public Tokenizer {
+public:
+  FileTokenizer(const std::string& filename);
+
+  virtual char doGetNextChar();
+
+private:
+  std::ifstream inputstream;
+
+};
+
+class StringTokenizer : public Tokenizer {
+public:
+  StringTokenizer(const std::string& src_string);
+
+  virtual char doGetNextChar();
+
+private:
+  std::string src_str;
+};
 #endif

src/models/CANDatabase.cpp

@@ -15,16 +15,21 @@ std::size_t CANDatabase::size() const {
 }
 
 CANDatabase CANDatabase::fromFile(const std::string& filename) {
-  Tokenizer tokenizer(filename);
-
-  if(!tokenizer.is_valid()) {
+  std::ifstream test_stream(filename);
+  if (!test_stream.good()) {
     throw CANDatabaseException("Cannot find file " + filename);
   }
-
+  
+  FileTokenizer tokenizer(filename);
   return DBCParser::fromTokenizer(filename, tokenizer);
 }
 
-std::weak_ptr<CANFrame> CANDatabase::getFrameByName(const std::string& name) const {
+CANDatabase CANDatabase::fromString(const std::string & src_string) {
+  StringTokenizer tokenizer(src_string);
+  return DBCParser::fromTokenizer(tokenizer);
+}
+
+std::weak_ptr<CANFrame> CANDatabase::at(const std::string& name) const {
   std::weak_ptr<CANFrame> result;
 
   auto ite = strIndex_.find(name);
@@ -34,7 +39,7 @@ std::weak_ptr<CANFrame> CANDatabase::getFrameByName(const std::string& name) con
   return result;
 }
 
-std::weak_ptr<CANFrame> CANDatabase::getFrameById(unsigned int id) const {
+std::weak_ptr<CANFrame> CANDatabase::at(unsigned int id) const {
   std::weak_ptr<CANFrame> result;
 
   auto ite = intIndex_.find(id);
@@ -44,16 +49,6 @@ std::weak_ptr<CANFrame> CANDatabase::getFrameById(unsigned int id) const {
   return result;
 }
 
-std::vector<std::weak_ptr<CANFrame>> CANDatabase::frames() const {
-  std::vector<std::weak_ptr<CANFrame>> result;
-  result.reserve(intIndex_.size());
-
-  for(const auto& sigIte: intIndex_) {
-    result.emplace_back(sigIte.second);
-  }
-  return result;
-}
-
 void CANDatabase::addFrame(std::shared_ptr<CANFrame> frame) {
   if(strIndex_.find(frame->name()) != strIndex_.end()) {
     std::cout << "WARNING: Double declaration of a frame with name "
@@ -94,10 +89,75 @@ void CANDatabase::removeFrame(unsigned int can_id) {
   strIndex_.erase(strIndex_.find(strIdx));
 }
 
-bool CANDatabase::hasFrame(unsigned int can_id) const {
+bool CANDatabase::contains(unsigned int can_id) const {
   return intIndex_.find(can_id) != intIndex_.end();
 }
 
-bool CANDatabase::hasFrame(const std::string& name) const {
+bool CANDatabase::contains(const std::string& name) const {
   return strIndex_.find(name) != strIndex_.end();
 }
+
+CANDatabase::iterator 
+CANDatabase::begin() {
+  return intIndex_.begin();
+}
+
+CANDatabase::const_iterator 
+CANDatabase::begin() const {
+  return intIndex_.begin();
+}
+
+CANDatabase::const_iterator
+CANDatabase::cbegin() const {
+  return intIndex_.cbegin();
+}
+
+CANDatabase::iterator 
+CANDatabase::end() {
+  return intIndex_.end();
+}
+
+CANDatabase::const_iterator 
+CANDatabase::end() const {
+  return intIndex_.end();
+}
+
+CANDatabase::const_iterator
+CANDatabase::cend() const {
+  return intIndex_.cend();
+}
+
+CANDatabase::reverse_iterator 
+CANDatabase::rbegin() {
+  return intIndex_.rbegin();
+}
+
+CANDatabase::const_reverse_iterator 
+CANDatabase::rbegin() const {
+  return intIndex_.rbegin();
+}
+
+CANDatabase::const_reverse_iterator
+CANDatabase::crbegin() const {
+  return intIndex_.crbegin();
+}
+
+CANDatabase::reverse_iterator 
+CANDatabase::rend() {
+  return intIndex_.rend();
+}
+
+CANDatabase::const_reverse_iterator 
+CANDatabase::rend() const {
+  return intIndex_.rend();
+}
+
+CANDatabase::const_reverse_iterator
+CANDatabase::crend() const {
+  return intIndex_.crend();
+}
+
+void CANDatabase::clear() {
+  intIndex_.clear();
+  strIndex_.clear();
+}