From: JINMEI Tatuya Date: Sat, 27 Oct 2012 00:11:26 +0000 (-0700) Subject: [2370] overall documentation updates X-Git-Tag: trac2487_base~32^2^2~3 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=33fd1fb0ed8ebfceb01e8a84b1196af29dffde92;p=thirdparty%2Fkea.git [2370] overall documentation updates --- diff --git a/src/lib/dns/master_lexer.h b/src/lib/dns/master_lexer.h index 5abc8c1106..eb37ba3009 100644 --- a/src/lib/dns/master_lexer.h +++ b/src/lib/dns/master_lexer.h @@ -29,71 +29,159 @@ public: class Token; // we define it separate for better readability }; +/// \brief Tokens for \c MasterLexer +/// +/// This is a simple value-class encapsulating a type of a lexer token and +/// (if it has a value) its value. Essentially, the class provides +/// constructors corresponding to different types of tokens, and corresponding +/// getter methods. The type and value are fixed at the time of construction +/// and will never be modified throughout the lifetime of the object. +/// The getter methods are still provided to maximize the safety; an +/// application cannot refer to a value that is invalid for the type of token. +/// +/// This class is intentionally implemented as copyable and assignable +/// (using the default version of copy constructor and assignment operator), +/// but it's mainly for internal implementation convenience. Applications will +/// simply refer to Token object as a reference via the \c MasterLexer class. class MasterLexer::Token { public: + /// \brief Enumeration for token types enum Type { - END_OF_LINE, - END_OF_FILE, - INITIAL_WS, - SPECIAL_TYPE_MAX = INITIAL_WS, - STRING, - QSTRING, - NUMBER, - ERROR + END_OF_LINE, ///< End of line detected (if asked for detecting it) + END_OF_FILE, ///< End of file detected (if asked for detecting it) + INITIAL_WS, ///< White spaces at the beginning of a line + NOVALUE_TYPE_MAX = INITIAL_WS, ///< Max integer corresponding to + /// no-value (type only) types. + /// Mainly for internal use. + STRING, ///< A single string + QSTRING, ///< A single string quoted by double-quotes ("). + NUMBER, ///< A decimal number (unsigned 32-bit) + ERROR ///< Error detected in getting a token }; + /// \brief Enumeration for lexer error codes enum ErrorCode { - NOT_STARTED, - UNBALANCED_PAREN, - UNEXPECTED_END, - UNBALANCED_QUOTES, - MAX_ERROR_CODE = UNBALANCED_QUOTES + NOT_STARTED, ///< The lexer is just initialized and has no token + UNBALANCED_PAREN, ///< Unbalanced parentheses detected + UNEXPECTED_END, ///< The lexer reaches the end of line or file + /// unexpectedly + UNBALANCED_QUOTES, ///< Unbalanced quotations detected + MAX_ERROR_CODE ///< Max integer corresponding to valid error codes. + /// (excluding this one). Mainly for internal use. }; + /// \brief A simple representation of a range of a string. + /// + /// This is a straightforward pair of the start pointer of a string + /// and its length. The \c STRING and \c QSTRING types of tokens + /// will be primarily represented in this form. + /// + /// Any character can be stored in the valid range of the region. + /// In particular, there can be a nul character (\0) in the middle of + /// the region. On the other hand, it is not ensured that the string + /// is nul-terminated. So the usual string manipulation API may not work + /// as expected. struct StringRegion { - const char* beg; - size_t len; + const char* beg; ///< The start address of the string + size_t len; ///< The length of the string in bytes }; + /// \brief Constructor for non-value type of token. + /// + /// \throw InvalidParameter A value type token is specified. + /// \param type The type of the token. It must indicate a non-value + /// type (not larger than \c NOVALUE_TYPE_MAX). explicit Token(Type type) : type_(type) { - if (type > SPECIAL_TYPE_MAX) { + if (type > NOVALUE_TYPE_MAX) { isc_throw(InvalidParameter, "Token per-type constructor " "called with invalid type: " << type); } } + + /// \brief Constructor for string and quoted-string types of token. + /// + /// The optional \c quoted parameter specifies whether it's a quoted or + /// non quoted string. + /// + /// The string is specified as a pair of a pointer to the start address + /// and its length. Any character can be contained in any position of + /// the valid range (see \c StringRegion). + /// + /// When it's a quoted string, the quotation marks must be excluded + /// from the specified range. + /// + /// \param str_beg The start address of the string + /// \param str_len The size of the string in bytes + /// \param quoted true if it's a quoted string; false otherwise. Token(const char* str_beg, size_t str_len, bool quoted = false) : type_(quoted ? QSTRING : STRING) { val_.str_region_.beg = str_beg; val_.str_region_.len = str_len; } + + /// \brief Constructor for number type of token. + /// + /// \brief number An unsigned 32-bit integer corresponding to the token + /// value. explicit Token(uint32_t number) : type_(NUMBER) { val_.number_ = number; } + + /// \brief Constructor for error type of token. + /// + /// \throw InvalidParameter Invalid error code value is specified. + /// \brief error_code A pre-defined constant of \c ErrorCode. explicit Token(ErrorCode error_code) : type_(ERROR) { - if (error_code > MAX_ERROR_CODE) { + if (!(error_code < MAX_ERROR_CODE)) { isc_throw(InvalidParameter, "Invalid master lexer error code: " << error_code); } val_.error_code_ = error_code; } + /// \brief Return the token type. + /// + /// \throw none Type getType() const { return (type_); } - std::string getString() const { + + /// \brief Return the value of a string-variant token. + /// + /// \throw InvalidOperation Called on a non string-variant types of token. + /// \return A reference to \c StringRegion corresponding to the string + /// token value. + const StringRegion& getStringRegion() const { if (type_ != STRING && type_ != QSTRING) { isc_throw(InvalidOperation, - "Token::getString() for non string-variant type"); + "Token::getStringRegion() for non string-variant type"); } - return (std::string(val_.str_region_.beg, - val_.str_region_.beg + val_.str_region_.len)); + return (val_.str_region_); } - const StringRegion& getStringRegion() const { + + /// \brief Return the value of a string-variant token as a string object. + /// + /// Note that the underlying string may contain a nul (\0) character + /// in the middle. The returned string object will contain all characters + /// of the valid range of the underlying string. So some string + /// operations such as c_str() may not work as expected. + /// + /// \throw InvalidOperation Called on a non string-variant types of token. + /// \throw std::bad_alloc Resource allocation failure in constructing the + /// string object. + /// \return A std::string object corresponding to the string token value. + std::string getString() const { if (type_ != STRING && type_ != QSTRING) { isc_throw(InvalidOperation, - "Token::getStringRegion() for non string-variant type"); + "Token::getString() for non string-variant type"); } - return (val_.str_region_); + return (std::string(val_.str_region_.beg, + val_.str_region_.beg + val_.str_region_.len)); } + + /// \brief Return the value of a string-variant token as a string object. + /// + /// \throw InvalidOperation Called on a non number type of token. + /// \return The integer corresponding to the number token value. uint32_t getNumber() const { if (type_ != NUMBER) { isc_throw(InvalidOperation, @@ -101,6 +189,11 @@ public: } return (val_.number_); } + + /// \brief Return the error code of a error type token. + /// + /// \throw InvalidOperation Called on a non error type of token. + /// \return The error code of the token. ErrorCode getErrorCode() const { if (type_ != ERROR) { isc_throw(InvalidOperation, @@ -108,10 +201,25 @@ public: } return (val_.error_code_); }; + + /// \brief Return a textual description of the error of a error type token. + /// + /// The returned string would be useful to produce a log message when + /// a zone file parser encounters an error. + /// + /// \throw InvalidOperation Called on a non error type of token. + /// \throw std::bad_alloc Resource allocation failure in constructing the + /// string object. + /// \return A string object that describes the meaning of the error. std::string getErrorText() const; private: - Type type_; + Type type_; // this is not const so the class can be assignable + + // We use a union to represent different types of token values via the + // unified Token class. The class integrity should ensure valid operation + // on the union; getter methods should only refer to the member set at + // the construction. union { StringRegion str_region_; uint32_t number_; diff --git a/src/lib/dns/tests/master_lexer_token_unittest.cc b/src/lib/dns/tests/master_lexer_token_unittest.cc index ed3b0610b1..a7a8acce90 100644 --- a/src/lib/dns/tests/master_lexer_token_unittest.cc +++ b/src/lib/dns/tests/master_lexer_token_unittest.cc @@ -37,7 +37,7 @@ public: token_err(MasterLexer::Token::UNEXPECTED_END) {} - const MasterLexer::Token token_eof; // an example of special type token + const MasterLexer::Token token_eof; // an example of non-value type token const MasterLexer::Token token_str; const MasterLexer::Token token_num; const MasterLexer::Token token_err; @@ -103,7 +103,7 @@ TEST_F(MasterLexerTokenTest, numbers) { EXPECT_THROW(token_str.getNumber(), isc::InvalidOperation); } -TEST_F(MasterLexerTokenTest, specials) { +TEST_F(MasterLexerTokenTest, novalues) { // Just checking we can construct them and getType() returns correct value. EXPECT_EQ(MasterLexer::Token::END_OF_FILE, token_eof.getType()); EXPECT_EQ(MasterLexer::Token::END_OF_LINE,