Commit 37d79010 authored by JINMEI Tatuya's avatar JINMEI Tatuya
Browse files

[2371] documentation updates

parent 70649947
......@@ -25,16 +25,105 @@
namespace isc {
namespace dns {
/// \brief Tokenizer for parsing DNS master files.
///
/// The \c MasterLexer class provides tokenize interfaces for parsing DNS
/// master files. It understands some special rules of master files as
/// defined in RFC 1035, such as comments, character escaping, or multi-line
/// data, and provides the user application with the actual data in a
/// more convenient form such as a std::string object.
///
/// In order to support the $INCLUDE notation, this class is designed to be
/// able to operate on multiple files or input streams in the nested way.
/// The \c open() and \c close() methods correspond to the push and pop
/// operations.
///
/// While this class is public, it is less likely to be used by normal
/// applications; it's mainly expected to be used within this library,
/// specifically by the \c MasterLoader class and \c Rdata implementation
/// classes.
class MasterLexer {
public:
class Token; // we define it separately for better readability
/// \brief The constructor.
///
/// \throw std::bad_alloc Internal resource allocation fails (rare case).
MasterLexer();
/// \brief The destructor.
///
/// It internally closes any remaining input sources.
~MasterLexer();
/// \brief Open a file and make it the current input source of MasterLexer.
///
/// The opened file can be explicitly closed by the \c close() method;
/// if \c close() is not called within the lifetime of the \c MasterLexer,
/// it will be closed in the destructor.
///
/// \throw InvalidParameter filename is NULL
/// \throw some_other The specified cannot be opened
/// \param filename A non NULL string specifying a master file
void open(const char* filename);
/// \brief Make the given stream the current input source of MasterLexer.
///
/// The caller still holds the ownership of the passed stream; it's the
/// caller's responsibility to keep it valid as long as it's used in
/// \c MasterLexer or to release any resource for the stream after that.
/// The caller can explicitly tell \c MasterLexer to stop using the
/// stream by calling the \c close() method.
///
/// \param input An input stream object that produces textual
/// representation of DNS RRs.
void open(std::istream& input);
/// \brief Close the most recently opened input source (file or stream).
///
/// If it's a file, the opened file will be literally closed.
/// If it's a stream, \c MasterLexer will simply release the reference to
/// the stream; the caller can assume it will be never used in
/// \c MasterLexer thereafter.
///
/// This method must not be called when there is no opened source for
/// \c MasterLexer. This method is otherwise exception free.
///
/// \throw isc::InvalidOperation Called with no opened source.
void close();
/// \brief Return a name of the current input source name.
///
/// If it's a file, it will be the C string given at the corresponding
/// \c open() call, that is, its file name. If it's a stream, it will
/// be formatted as "stream-%p" where %p is hex representation of the
/// address of the stream object.
///
/// If there is no opened source at the time of the call, this method
/// returns an empty string.
///
/// \throw std::bad_alloc Resource allocation failed for string
/// construction (rare case)
///
/// \return A string representation of the current source (see the
/// description)
std::string getSourceName() const;
/// \brief Return the input source line number.
///
/// If there is an opened source, the return value will be a non-0
/// integer indicating the line number of the current source where
/// the \c MasterLexer is currently working. The expected usage of
/// this value is to print a helpful error message when parsing fails
/// by specifically identifying the position of the error.
///
/// If there is no opened source at the time of the call, this method
/// returns 0.
///
/// \throw None
///
/// \return A string representation of the current source (see the
/// description)
size_t getSourceLine() const;
private:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment