minor improvements to documentation and style

JSON/include/Poco/JSON/Array.h

@@ -35,9 +35,9 @@ class Object;
 
 
 class JSON_API Array
-	/// Represents a JSON array. JSON array provides a representation
+	/// Represents a JSON array. Array provides a representation
 	/// based on shared pointers and optimized for performance. It is possible to 
-	/// convert object to Poco::Dynamic::Array. Conversion requires copying and therefore
+	/// convert Array to Poco::Dynamic::Array. Conversion requires copying and therefore
 	/// has performance penalty; the benefit is in improved syntax, eg:
 	/// 
 	///    // use pointers to avoid copying
@@ -57,7 +57,7 @@ class JSON_API Array
 	///    i = da[0]["test"];     // i == 0
 	///    i = da[1]["test1"][1]; // i == 2
 	///    i = da[1]["test2"];    // i == 4
-	/// 
+	/// ----
 {
 public:
 	typedef std::vector<Dynamic::Var>                 ValueVec;
@@ -66,27 +66,27 @@ public:
 	typedef SharedPtr<Array> Ptr;
 
 	Array();
-		/// Default constructor
+		/// Creates an empty Array.
 
 	Array(const Array& copy);
-		/// Copy Constructor
+		/// Creates an Array by copying another one.
 
 	virtual ~Array();
-		/// Destructor
+		/// Destroys the Array.
 
 	ValueVec::const_iterator begin() const;
-		/// Returns iterator
+		/// Returns the begin iterator for values.
 
 	ValueVec::const_iterator end() const;
-		/// Returns iterator
+		/// Returns the end iterator for values.
 
 	Dynamic::Var get(unsigned int index) const;
-		/// Retrieves an element. Will return an empty value
+		/// Retrieves the element at the given index. 
-		/// when the element doesn't exist.
+		/// Will return an empty value when the element doesn't exist.
 
 	Array::Ptr getArray(unsigned int index) const;
 		/// Retrieves an array. When the element is not
-		/// an array or doesn't exist, an empty SharedPtr is returned.
+		/// an Array or doesn't exist, an empty SharedPtr is returned.
 
 	template<typename T>
 	T getElement(unsigned int index) const
@@ -105,29 +105,29 @@ public:
 		/// an object or doesn't exist, an empty SharedPtr is returned.
 
 	std::size_t size() const;
-		/// Returns the size of the array
+		/// Returns the size of the array.
 
 	bool isArray(unsigned int index) const;
-		/// Returns true when the element is an array
+		/// Returns true when the element is an array.
 
 	bool isArray(const Dynamic::Var& value) const;
-		/// Returns true when the element is an array
+		/// Returns true when the element is an array.
 
 	bool isArray(ConstIterator& value) const;
-		/// Returns true when the element is an array
+		/// Returns true when the element is an array.
 
 	bool isNull(unsigned int index) const;
 		/// Returns true when the element is null or
 		/// when the element doesn't exist.
 
 	bool isObject(unsigned int index) const;
-		/// Returns true when the element is an object
+		/// Returns true when the element is an object.
 
 	bool isObject(const Dynamic::Var& value) const;
-		/// Returns true when the element is an object
+		/// Returns true when the element is an object.
 
 	bool isObject(ConstIterator& value) const;
-		/// Returns true when the element is an object
+		/// Returns true when the element is an object.
 
 	template<typename T>
 	T optElement(unsigned int index, const T& def) const
@@ -180,6 +180,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline Array::ValueVec::const_iterator Array::begin() const
 {
 	return _values.begin();
@@ -236,7 +239,8 @@ inline void Array::remove(unsigned int index)
 	_values.erase(_values.begin() + index);
 }
 
-}} // Namespace Poco::JSON
+
+} } // namespace Poco::JSON
 
 
 namespace Poco {
@@ -521,7 +525,7 @@ private:
 };
 
 
-}} // namespace Poco::JSON
+} } // namespace Poco::Dynamic
 
 
 #endif // JSON_Array_INCLUDED

JSON/include/Poco/JSON/Handler.h

@@ -31,39 +31,44 @@ namespace JSON {
 
 
 class JSON_API Handler
+	/// Interface for handling parsing events generated by the JSON Parser.
+	///
+	/// An application can implement a subclass of Handler to implement
+	/// callback-based parsing of a JSON document, similar to how a SAX
+	/// parser would handle XML.
 {
 public:
 	typedef SharedPtr<Handler> Ptr;
 
 	Handler();
-		/// Constructor;
+		/// Creates an empty Handler.
 	
 	virtual ~Handler();
-		/// Destructor
+		/// Destroys the Handler.
 
 	virtual void reset() = 0;
 		/// Resets the handler state.
 
 	virtual void startObject() = 0;
-		/// The parser has read a {, meaning a new object will be read
+		/// The parser has read a {, meaning a new object will be read.
 
 	virtual void endObject() = 0;
-		/// The parser has read a }, meaning the object is read
+		/// The parser has read a }, meaning the object is read.
 
 	virtual void startArray() = 0;
-		/// The parser has read a [, meaning a new array will be read
+		/// The parser has read a [, meaning a new array will be read.
 
 	virtual void endArray() = 0;
-		/// The parser has read a ], meaning the array is read
+		/// The parser has read a ], meaning the array is read.
 
 	virtual void key(const std::string& k) = 0;
-		/// A key of an object is read
+		/// A key of an object is read.
 
 	virtual void null() = 0;
-		/// A null value is read
+		/// A null value is read.
 
 	virtual void value(int v) = 0;
-		/// An integer value is read
+		/// An integer value is read.
 
 	virtual void value(unsigned v) = 0;
 		/// An unsigned value is read. This will only be triggered if the
@@ -71,7 +76,7 @@ public:
 
 #if defined(POCO_HAVE_INT64)
 	virtual void value(Int64 v) = 0;
-		/// A 64-bit integer value is read
+		/// A 64-bit integer value is read.
 
 	virtual void value(UInt64 v) = 0;
 		/// An unsigned 64-bit integer value is read. This will only be
@@ -82,10 +87,10 @@ public:
 		/// A string value is read.
 
 	virtual void value(double d) = 0;
-		/// A double value is read
+		/// A double value is read.
 
 	virtual void value(bool b) = 0;
-		/// A boolean value is read
+		/// A boolean value is read.
 
 	virtual Poco::Dynamic::Var asVar() const;
 		/// Returns the result of the parser (an object, array or string),

JSON/include/Poco/JSON/Object.h

@@ -39,9 +39,9 @@ namespace JSON {
 
 
 class JSON_API Object
-	/// Represents a JSON object. JSON object provides a representation
+	/// Represents a JSON object. Object provides a representation
 	/// based on shared pointers and optimized for performance. It is possible to 
-	/// convert object to DynamicStruct. Conversion requires copying and therefore
+	/// convert Object to DynamicStruct. Conversion requires copying and therefore
 	/// has performance penalty; the benefit is in improved syntax, eg:
 	/// 
 	///    std::string json = "{ \"test\" : { \"property\" : \"value\" } }";
@@ -58,7 +58,7 @@ class JSON_API Object
 	///    // copy/convert to Poco::DynamicStruct
 	///    Poco::DynamicStruct ds = *object;
 	///    val = ds["test"]["property"]; // val holds "value"
-	/// 
+	/// ----
 {
 public:
 	typedef SharedPtr<Object>                   Ptr;
@@ -68,16 +68,19 @@ public:
 	typedef ValueMap::const_iterator            ConstIterator;
 
 	explicit Object(bool preserveInsertionOrder = false);
-		/// Default constructor. If preserveInsertionOrder, object
+		/// Creates an empty Object.
-		/// will preserve the items insertion order. Otherwise, items
+		///
-		/// will be sorted by keys.
+		/// If preserveInsertionOrder, object will preserve the items insertion 
+		/// order. Otherwise, items will be sorted by keys.
 
 	Object(const Object& copy);
-		/// Copy constructor. Struct is not copied to keep the operation as
+		/// Creates an Object by copying another one.
+		///
+		/// Struct is not copied to keep the operation as
 		/// efficient as possible (when needed, it will be generated upon request).
 
 	virtual ~Object();
-		/// Destroys Object.
+		/// Destroys the Object.
 
 	Iterator begin()
 	{
@@ -117,7 +120,7 @@ public:
 	T getValue(const std::string& key) const
 		/// Retrieves the property with the given name and will
 		/// try to convert the value to the given template type.
-		/// The convert<T> method of Dynamic is called
+		/// The convert<T>() method of Var is called
 		/// which can also throw exceptions for invalid values.
 		/// Note: This will not work for an array or an object.
 	{
@@ -129,8 +132,8 @@ public:
 	Poco::Nullable<T> getNullableValue(const std::string& key) const
 		/// Retrieves the property with the given name and will
 		/// try to convert the value to the given template type.
-		/// Returns null if isNull.
+		/// 
-		/// The convert<T> method of Dynamic is called
+		/// The convert<T> method of Var is called
 		/// which can also throw exceptions for invalid values.
 		/// Note: This will not work for an array or an object.
 	{
@@ -142,25 +145,25 @@ public:
 	}
 
 	void getNames(std::vector<std::string>& names) const;
-		/// Returns all property names
+		/// Returns all property names.
 
 	bool has(const std::string& key) const;
-		/// Returns true when the given property exists
+		/// Returns true when the given property exists.
 
 	bool isArray(const std::string& key) const;
-		/// Returns true when the given property contains an array
+		/// Returns true when the given property contains an array.
 
 	bool isArray(ConstIterator& it) const;
-		/// Returns true when the given property contains an array
+		/// Returns true when the given property contains an array.
 
 	bool isNull(const std::string& key) const;
-		/// Returns true when the given property contains a null value
+		/// Returns true when the given property contains a null value.
 
 	bool isObject(const std::string& key) const;
-		/// Returns true when the given property contains an object
+		/// Returns true when the given property contains an object.
 
 	bool isObject(ConstIterator& it) const;
-		/// Returns true when the given property contains an object
+		/// Returns true when the given property contains an object.
 
 	template<typename T>
 	T optValue(const std::string& key, const T& def) const
@@ -185,17 +188,19 @@ public:
 	}
 
 	std::size_t size() const;
-		/// Returns the number of properties
+		/// Returns the number of properties.
 
 	void set(const std::string& key, const Dynamic::Var& value);
-		/// Sets a new value
+		/// Sets a new value.
 
 	void stringify(std::ostream& out, unsigned int indent = 0, int step = -1) const;
-		/// Prints the object to out stream. When indent is 0, the object
+		/// Prints the object to out stream. 
-		/// will be printed on a single line without indentation.
+		///
+		/// When indent is 0, the object will be printed on a single 
+		/// line without indentation.
 
 	void remove(const std::string& key);
-		/// Removes the property with the given key
+		/// Removes the property with the given key.
 
 	static Poco::DynamicStruct makeStruct(const Object::Ptr& obj);
 		/// Utility function for creation of struct.
@@ -204,8 +209,9 @@ public:
 		/// Cast operator to Poco::DynamiStruct.
 
 	void clear();
-		/// Clears the contents of the object. Insertion order 
+		/// Clears the contents of the object.
-		/// preservation property is left intact.
+		///
+		/// Insertion order preservation property is left intact.
 
 private:
 	template <typename C>
@@ -233,8 +239,7 @@ private:
 
 		if (indent >= step) indent -= step;
 
-		for (unsigned int i = 0; i < indent; i++)
+		for (unsigned int i = 0; i < indent; i++) out << ' ';
-			out << ' ';
 
 		out << '}';
 	}
@@ -254,6 +259,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline bool Object::has(const std::string& key) const
 {
 	ValueMap::const_iterator it = _values.find(key);
@@ -341,7 +349,7 @@ inline const Dynamic::Var& Object::getValue(KeyPtrList::const_iterator& it) cons
 }
 
 
-}} // Namespace Poco::JSON
+} } // namespace Poco::JSON
 
 
 namespace Poco {
@@ -632,7 +640,7 @@ private:
 };
 
 
-}} // namespace Poco::JSON
+} } // namespace Poco::Dynamic
 
 
 #endif // JSON_Object_INCLUDED

JSON/include/Poco/JSON/ParseHandler.h

@@ -29,13 +29,18 @@ namespace JSON {
 
 
 class JSON_API ParseHandler: public Handler
-	/// Provides a default handler for the JSON parser.
+	/// ParseHandler is the default handler for the JSON Parser.
-	/// This handler will build up an object or array based
+	///
-	/// on the handlers called by the parser.
+	/// This handler will construct an Object or Array based
+	/// on the handlers called by the Parser.
 {
 public:
 	ParseHandler(bool preserveObjectOrder = false);
 		/// Creates the ParseHandler.
+		///
+		/// If preserveObjectOrder is true, the order of properties
+		/// inside objects is preserved. Otherwise, items
+		/// will be sorted by keys.
 
 	virtual ~ParseHandler();
 		/// Destroys the ParseHandler.
@@ -100,6 +105,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline Dynamic::Var ParseHandler::asVar() const
 {
 	return _result;
@@ -157,10 +165,6 @@ inline void ParseHandler::null()
 }
 
 
-typedef ParseHandler ParseHandler;
-//@ deprecated
-
-
 } } // namespace Poco::JSON
 
 

JSON/include/Poco/JSON/Parser.h

@@ -15,6 +15,7 @@
 // SPDX-License-Identifier:	BSL-1.0
 //
 
+
 /*
 Copyright (c) 2005 JSON.org
 
@@ -39,6 +40,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+
 #ifndef JSON_JSONParser_INCLUDED
 #define JSON_JSONParser_INCLUDED
 
@@ -58,22 +60,34 @@ namespace JSON {
 
 
 class JSON_API Parser
-	/// A RFC 4627 compatible class for parsing JSON strings or streams.
+	/// A parser for reading RFC 4627 compliant JSON from strings or streams.
 	/// 
-	/// See http://www.ietf.org/rfc/rfc4627.txt for specification.
+	/// Simple usage example:
-	/// 
-	/// Usage example:
 	/// 
 	///    std::string json = "{ \"name\" : \"Franky\", \"children\" : [ \"Jonas\", \"Ellen\" ] }";
 	///    Parser parser;
 	///    Var result = parser.parse(json);
-	///    // ... use result
+	///    // ... use result (see next example)
 	///    parser.reset();
 	///    std::ostringstream ostr;
 	///    PrintHandler::Ptr pHandler = new PrintHandler(ostr);
 	///    parser.setHandler(pHandler);
 	///    parser.parse(json); // ostr.str() == json
+	/// ----
 	///
+	/// The result of parsing a valid JSON document will be either an Object
+	/// or an Array. Therefore the result of parse() is a Poco::Dynamic::Var
+	/// containing a Poco::SharedPtr to an Object or Array instance.
+	///
+	/// Example:
+	/// 
+	///    std::string json = "{ \"name\" : \"Franky\", \"children\" : [ \"Jonas\", \"Ellen\" ] }";
+	///    Parser parser;
+	///    Var result = parser.parse(json);
+	///    Object::Ptr object = result.extract<Object::Ptr>();
+	///    std::string name = object.getValue<std::string>("name");
+	///    Array::Ptr children = object.getArray("children");
+	/// ----
 {
 public:
 	typedef std::char_traits<char> CharTraits;
@@ -201,7 +215,7 @@ public:
 	static const int         JSON_UNLIMITED_DEPTH = -1;
 
 	Parser(const Handler::Ptr& pHandler = new ParseHandler, std::size_t bufSize = JSON_PARSE_BUFFER_SIZE);
-		/// Creates JSON Parser.
+		/// Creates JSON Parser, using the given Handler and buffer size.
 
 	virtual ~Parser();
 		/// Destroys JSON Parser.
@@ -210,17 +224,21 @@ public:
 		/// Resets the parser.
 
 	void setAllowComments(bool comments);
-		/// Allow comments. By default, comments are not allowed.
+		/// Allow or disallow comments. By default, comments are not allowed.
 
 	bool getAllowComments() const;
 		/// Returns true if comments are allowed, false otherwise.
+		///
 		/// By default, comments are not allowed.
 		
 	void setAllowNullByte(bool nullByte);
-		/// Allow null byte in strings. By default, null byte is allowed.
+		/// Allow or disallow null byte in strings. 
+		///
+		/// By default, null byte is allowed.
 
 	bool getAllowNullByte() const;
 		/// Returns true if null byte is allowed, false otherwise.
+		///
 		/// By default, null bytes are allowed.
 
 	void setDepth(std::size_t depth);
@@ -230,16 +248,16 @@ public:
 		/// Returns the allowed JSON depth.
 
 	Dynamic::Var parse(const std::string& json);
-		/// Parses a string.
+		/// Parses JSON from a string.
 
 	Dynamic::Var parse(std::istream& in);
-		/// Parses a JSON from the input stream.
+		/// Parses JSON from an input stream.
 
 	void setHandler(const Handler::Ptr& pHandler);
-		/// Set the handler.
+		/// Set the Handler.
 
 	const Handler::Ptr& getHandler();
-		/// Returns the handler.
+		/// Returns the Handler.
 
 	Dynamic::Var asVar() const;
 		/// Returns the result of parsing;
@@ -261,23 +279,14 @@ private:
 		/// Returns false if there is underflow or if the modes mismatch.
 
 	void growBuffer();
-
 	void clearBuffer();
-
 	void parseBufferPushBackChar(char c);
-
 	void parseBufferPopBackChar();
-
 	void addCharToParseBuffer(CharIntType nextChar, int nextClass);
-
 	void addEscapedCharToParseBuffer(CharIntType nextChar);
-
 	CharIntType decodeUnicodeChar();
-
 	void assertNotStringNullBool();
-
 	void assertNonContainer();
-
 	void parseBuffer();
 
 	template <typename IT>
@@ -315,7 +324,7 @@ private:
 		unsigned char ch = static_cast<unsigned char>(CharTraits::to_char_type(nextChar));
 
 		// Determine the character's class.
-		if ((!_allowNullByte && ch == 0)) return false;
+		if (!_allowNullByte && ch == 0) return false;
 		if (ch >= 0x80)
 		{
 			nextClass = C_ETC;
@@ -591,8 +600,10 @@ private:
 	}
 
 	bool done();
-
 	static CharIntType utf8CheckFirst(char byte);
+	bool isHighSurrogate(unsigned uc);
+	bool isLowSurrogate(unsigned uc);
+	unsigned decodeSurrogatePair(unsigned hi, unsigned lo);
 
 	static const int _asciiClass[128];
 		/// This array maps the 128 ASCII characters into character classes.
@@ -602,10 +613,6 @@ private:
 	static const int _stateTransitionTable[NR_STATES][NR_CLASSES];
 	static const int xx = -1;
 
-	bool isHighSurrogate(unsigned uc);
-	bool isLowSurrogate(unsigned uc);
-	unsigned decodeSurrogatePair(unsigned hi, unsigned lo);
-
 	Handler::Ptr   _pHandler;
 	signed char    _state;
 	signed char    _beforeCommentState;
@@ -623,6 +630,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline void Parser::setAllowComments(bool comments)
 {
 	_allowComments = comments;

JSON/include/Poco/JSON/PrintHandler.h

@@ -30,8 +30,8 @@ namespace JSON {
 
 class JSON_API PrintHandler: public Handler
 	/// PrintHandler formats and prints the JSON object
-	/// to either user-provided std::ostream or standard out.
+	/// to either user-provided std::ostream or standard output.
-	/// If indent i zero, the output is condensed JSON string,
+	/// If indent is zero, the output is a condensed JSON string,
 	/// otherwise, the proper indentation is applied to elements.
 {
 public:
@@ -104,7 +104,6 @@ public:
 		/// Sets indentation.
 
 private:
-
 	const char* endLine() const;
 	unsigned indent();
 	bool printFlat() const;
@@ -119,6 +118,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline void PrintHandler::setIndent(unsigned indent)
 {
 	_indent = indent;
@@ -131,7 +133,6 @@ inline bool PrintHandler::array() const
 }
 
 
-
 } } // namespace Poco::JSON
 
 

JSON/include/Poco/JSON/Query.h

@@ -15,6 +15,7 @@
 // SPDX-License-Identifier:	BSL-1.0
 //
 
+
 #ifndef JSON_JSONQuery_INCLUDED
 #define JSON_JSONQuery_INCLUDED
 
@@ -33,44 +34,56 @@ class JSON_API Query
 {
 public:
 	Query(const Dynamic::Var& source);
-		/// Creates the Query; source must be JSON Object, Array, Object::Ptr,
+		/// Creates a Query/
+		///
+		/// Source must be JSON Object, Array, Object::Ptr,
 		/// Array::Ptr or empty Var. Any other type will trigger throwing of 
 		/// InvalidArgumentException.
+		///
 		/// Creating Query holding Ptr will typically result in faster
 		/// performance.
 
 	virtual ~Query();
-		/// Destructor
+		/// Destroys the Query.
 
 	Object::Ptr findObject(const std::string& path) const;
-		/// Search for an object. When the object can't be found, a zero Ptr
+		/// Search for an object. 
-		/// is returned; otherwise, a shared pointer to internally held object
+		///
+		/// When the object can't be found, a zero Ptr is returned; 
+		/// otherwise, a shared pointer to internally held object
 		/// is returned.
 		/// If object (as opposed to a pointer to object) is held
 		/// internally, a shared pointer to new (heap-allocated) Object is
 		/// returned; this may be expensive operation.
 
 	Object& findObject(const std::string& path, Object& obj) const;
-		/// Search for an object. If object is found, it is assigned to the
+		/// Search for an object. 
+		///
+		/// If object is found, it is assigned to the
 		/// Object through the reference passed in. When the object can't be 
 		/// found, the provided Object is emptied and returned.
 
 	Array::Ptr findArray(const std::string& path) const;
-		/// Search for an array. When the array can't be found, a zero Ptr
+		/// Search for an array. 
-		/// is returned; otherwise, a shared pointer to internally held array
+		///
+		/// When the array can't be found, a zero Ptr is returned; 
+		/// otherwise, a shared pointer to internally held array
 		/// is returned.
 		/// If array (as opposed to a pointer to array) is held
 		/// internally, a shared pointer to new (heap-allocated) Object is
 		/// returned; this may be expensive operation.
 
 	Array& findArray(const std::string& path, Array& obj) const;
-		/// Search for an array. If array is found, it is assigned to the
+		/// Search for an array. 
+		///
+		/// If array is found, it is assigned to the
 		/// Object through the reference passed in. When the array can't be 
 		/// found, the provided Object is emptied and returned.
 
 	Dynamic::Var find(const std::string& path) const;
-		/// Searches a value
+		/// Searches a value.
-		/// For example: "person.children[0].name" will return the
+		///
+		/// Example: "person.children[0].name" will return the
 		/// the name of the first child. When the value can't be found
 		/// an empty value is returned.
 
@@ -88,7 +101,9 @@ public:
 			{
 				result = value.convert<T>();
 			}
-			catch(...) { }
+			catch (...) 
+			{ 
+			}
 		}
 		return result;
 	}

JSON/include/Poco/JSON/Stringifier.h

@@ -30,21 +30,24 @@ namespace JSON {
 
 
 class JSON_API Stringifier
-	/// Helper class for creating a String from a JSON object or array
+	/// Helper class for creating a string from a JSON object or array.
 {
 public:
 	static void condense(const Dynamic::Var& any, std::ostream& out);
 		/// Writes a condensed string representation of the value to the output stream while preserving the insertion order.
+		///
 		/// This is just a "shortcut" to stringify(any, out) with name indicating the function effect.
 
 	static void stringify(const Dynamic::Var& any, bool preserveInsertionOrder, std::ostream& out, unsigned int indent = 0);
 		/// Writes a string representation of the value to the output stream while optionally preserving the insertion order.
+		///
 		/// When indent is 0, the generated string will be created as small as possible (condensed).
 		/// When preserveInsertionOrder is true, the original order of object members will be preserved.
 		/// This is a "shortcut" to stringify(any, out, indent, -1, preserveInsertionOrder).
 
 	static void stringify(const Dynamic::Var& any, std::ostream& out, unsigned int indent = 0, int step = -1, bool preserveInsertionOrder = false);
 		/// Writes a string representation of the value to the output stream.
+		///
 		/// When indent is 0, the string will be created as small as possible.
 		/// When preserveInsertionOrder is true, the original order of object members will be preserved;
 		/// otherwise, object members are sorted by their names.
@@ -54,6 +57,9 @@ public:
 };
 
 
+//
+// inlines
+//
 inline void Stringifier::condense(const Dynamic::Var& any, std::ostream& out)
 {
 	stringify(any, out, 0, -1, true);

JSON/include/Poco/JSON/Template.h

@@ -15,6 +15,7 @@
 // SPDX-License-Identifier:	BSL-1.0
 //
 
+
 #ifndef JSON_JSONTemplate_INCLUDED
 #define JSON_JSONTemplate_INCLUDED
 
@@ -42,7 +43,7 @@ class JSON_API Template
 	/// Template is a template engine which uses JSON as input
 	/// for generating output. There are commands for
 	/// looping over JSON arrays, include other templates,
-	/// conditional output, ...
+	/// conditional output, etc.
 	///
 	/// All text is send to the outputstream. A command is placed
 	/// between 
@@ -91,13 +92,13 @@ public:
 	typedef SharedPtr<Template> Ptr;
 
 	Template();
-		/// Constructor.
+		/// Creates a Template.
 
 	Template(const Path& templatePath);
-		/// Constructor. Creates a template from a file.
+		/// Creates a Template from the file with the given templatePath.
 
 	virtual ~Template();
-		/// Destructor.
+		/// Destroys the Template.
 
 	void parse();
 		/// Parse a template from a file.
@@ -106,7 +107,7 @@ public:
 		/// Parse a template from a string.
 
 	void parse(std::istream& in);
-		/// Parse a template from a input stream.
+		/// Parse a template from an input stream.
 
 	Timestamp parseTime() const;
 		/// Returns the time when the template was parsed.
@@ -130,6 +131,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline void Template::parse(const std::string& source)
 {
 	std::istringstream is(source);

JSON/include/Poco/JSON/TemplateCache.h

@@ -15,6 +15,7 @@
 // SPDX-License-Identifier:	BSL-1.0
 //
 
+
 #ifndef JSON_JSONTemplateCache_INCLUDED
 #define JSON_JSONTemplateCache_INCLUDED
 
@@ -41,11 +42,13 @@ class JSON_API TemplateCache
 {
 public:
 	TemplateCache();
-		/// Constructor. The cache must be created
+		/// Creates an empty TemplateCache.
-		/// and not destroyed as long as it is used.
+		///
+		/// The cache must be created and not destroyed 
+		/// as long as it is used.
 
 	virtual ~TemplateCache();
-		/// Destructor.
+		/// Destroys the TemplateCache.
 
 	void addPath(const Path& path);
 		/// Add a path for resolving template paths.
@@ -61,22 +64,25 @@ public:
 		/// the cache.
 
 	static TemplateCache* instance();
-		/// Returns the only instance of this cache
+		/// Returns the only instance of this cache.
 
 	void setLogger(Logger& logger);
 		/// Sets the logger for the cache.
 
 private:
-	static TemplateCache*                _instance;
-	std::vector<Path>                    _includePaths;
-	std::map<std::string, Template::Ptr> _cache;
-	Logger*                              _logger;
-	
 	void setup();
 	Path resolvePath(const Path& path) const;
+
+	static TemplateCache*                _pInstance;
+	std::vector<Path>                    _includePaths;
+	std::map<std::string, Template::Ptr> _cache;
+	Logger*                              _pLogger;
 };
 
 
+//
+// inlines
+//
 inline void TemplateCache::addPath(const Path& path)
 {
 	_includePaths.push_back(path);
@@ -85,17 +91,17 @@ inline void TemplateCache::addPath(const Path& path)
 
 inline TemplateCache* TemplateCache::instance()
 {
-	return _instance;
+	return _pInstance;
 }
 
 
 inline void TemplateCache::setLogger(Logger& logger)
 {
-	_logger = &logger;
+	_pLogger = &logger;
 }
 
 
-}} // Namespace Poco::JSON
+} } // namespace Poco::JSON
 
 
 #endif // JSON_JSONTemplateCache_INCLUDED

JSON/src/JSONException.cpp

@@ -25,4 +25,4 @@ namespace JSON {
 POCO_IMPLEMENT_EXCEPTION(JSONException, Exception, "JSON Exception")
 
 
-} } // Namespace Poco::JSON
+} } // namespace Poco::JSON

JSON/src/Parser.cpp

@@ -34,7 +34,8 @@ namespace JSON {
 static const unsigned char UTF8_LEAD_BITS[4] = { 0x00, 0xC0, 0xE0, 0xF0 };
 
 
-const int Parser::_asciiClass[] = {
+const int Parser::_asciiClass[] = 
+{
     xx,      xx,      xx,      xx,      xx,      xx,      xx,      xx,
     xx,      C_WHITE, C_WHITE, xx,      xx,      C_WHITE, xx,      xx,
     xx,      xx,      xx,      xx,      xx,      xx,      xx,      xx,
@@ -57,7 +58,8 @@ const int Parser::_asciiClass[] = {
 };
 
 
-const int Parser::_stateTransitionTable[NR_STATES][NR_CLASSES] = {
+const int Parser::_stateTransitionTable[NR_STATES][NR_CLASSES] = 
+{
 /*
                  white                                      1-9                                   ABCDF  etc
              space |  {  }  [  ]  :  ,  "  \  /  +  -  .  0  |  a  b  c  d  e  f  l  n  r  s  t  u  |  E  |  * */
@@ -465,6 +467,7 @@ void Parser::parseBuffer()
 	clearBuffer();
 }
 
+
 int Parser::utf8CheckFirst(char byte)
 {
 	unsigned char u = (unsigned char) byte;
@@ -506,4 +509,5 @@ int Parser::utf8CheckFirst(char byte)
 	}
 }
 
+
 } } // namespace Poco::JSON

JSON/src/PrintHandler.cpp

@@ -207,7 +207,8 @@ void PrintHandler::comma()
 void PrintHandler::arrayValue()
 {
 	if (!_objStart) comma();
-	if (array()) {
+	if (array()) 
+	{
 		_out << _tab;
 	}
 }

JSON/src/Query.cpp

@@ -171,4 +171,4 @@ Var Query::find(const std::string& path) const
 }
 
 
-} } // Namespace Poco::JSON
+} } // namespace Poco::JSON

JSON/src/Stringifier.cpp

@@ -90,4 +90,4 @@ void Stringifier::formatString(const std::string& value, std::ostream& out)
 }
 
 
-} }  // Namespace Poco::JSON
+} }  // namespace Poco::JSON

JSON/src/Template.cpp

@@ -305,9 +305,9 @@ class IncludePart: public Part
 {
 public:
 
-	IncludePart(const Path& parentPath, const Path& path)
+	IncludePart(const Path& parentPath, const Path& path): 
-		: Part()
+		Part(), 
-		, _path(path)
+		_path(path)
 	{
 		// When the path is relative, try to make it absolute based
 		// on the path of the parent template. When the file doesn't
@@ -331,7 +331,7 @@ public:
 	void render(const Var& data, std::ostream& out) const
 	{
 		TemplateCache* cache = TemplateCache::instance();
-		if ( cache == NULL )
+		if (cache == 0)
 		{
 			Template tpl(_path);
 			tpl.parse();
@@ -349,17 +349,17 @@ private:
 };
 
 
-Template::Template(const Path& templatePath)
+Template::Template(const Path& templatePath): 
-	: _parts(0)
+	_parts(0), 
-	, _currentPart(0)
+	_currentPart(0), 
-	, _templatePath(templatePath)
+	_templatePath(templatePath)
 {
 }
 
 
-Template::Template()
+Template::Template():
-	: _parts(0)
+	_parts(0), 
-	, _currentPart(0)
+	_currentPart(0)
 {
 }
 
@@ -385,7 +385,7 @@ void Template::parse(std::istream& in)
 {
 	_parseTime.update();
 
-	_parts = new MultiPart();
+	_parts = new MultiPart;
 	_currentPart = _parts;
 
 	while (in.good())
@@ -445,7 +445,7 @@ void Template::parse(std::istream& in)
 			}
 			_currentPart = _partStack.top();
 			LogicPart* lp = dynamic_cast<LogicPart*>(_currentPart);
-			if ( lp == NULL )
+			if (lp == 0)
 			{
 				throw JSONTemplateException("Missing <? if ?> or <? ifexist ?> for <? else ?>");
 			}
@@ -453,8 +453,7 @@ void Template::parse(std::istream& in)
 			lp->addPart(part);
 			_currentPart = part;
 		}
-		else if (    command.compare("elsif") == 0
+		else if (command.compare("elsif") == 0 || command.compare("elif") == 0)
-		             || command.compare("elif") == 0 )
 		{
 			std::string query = readQuery(in);
 			if (query.empty())
@@ -469,7 +468,7 @@ void Template::parse(std::istream& in)
 
 			_currentPart = _partStack.top();
 			LogicPart* lp = dynamic_cast<LogicPart*>(_currentPart);
-			if ( lp == NULL )
+			if (lp == 0)
 			{
 				throw JSONTemplateException("Missing <? if ?> or <? ifexist ?> for <? elsif / elif ?>");
 			}
@@ -485,7 +484,7 @@ void Template::parse(std::istream& in)
 			}
 			MultiPart* loopPart = _partStack.top();
 			LoopPart* lp = dynamic_cast<LoopPart*>(loopPart);
-			if ( lp == NULL )
+			if (lp == 0)
 			{
 				throw JSONTemplateException("Missing <? for ?> command");
 			}
@@ -502,7 +501,7 @@ void Template::parse(std::istream& in)
 
 			_currentPart = _partStack.top();
 			LogicPart* lp = dynamic_cast<LogicPart*>(_currentPart);
-			if ( lp == NULL )
+			if (lp == 0)
 			{
 				throw JSONTemplateException("Missing <? if ?> or <? ifexist ?> for <? endif ?>");
 			}
@@ -511,8 +510,7 @@ void Template::parse(std::istream& in)
 			_currentPart = _partStack.top();
 			_partStack.pop();
 		}
-		else if (    command.compare("if") == 0
+		else if (command.compare("if") == 0 || command.compare("ifexist") == 0)
-		             || command.compare("ifexist") == 0 )
 		{
 			std::string query = readQuery(in);
 			if (query.empty())
@@ -702,4 +700,4 @@ void Template::render(const Var& data, std::ostream& out) const
 }
 
 
-} } // Namespace Poco::JSON
+} } // namespace Poco::JSON

JSON/src/TemplateCache.cpp

@@ -22,10 +22,10 @@ namespace Poco {
 namespace JSON {
 
 
-TemplateCache* TemplateCache::_instance = NULL;
+TemplateCache* TemplateCache::_pInstance = 0;
 
 
-TemplateCache::TemplateCache() : _logger(NULL)
+TemplateCache::TemplateCache(): _pLogger(0)
 {
 	setup();
 }
@@ -33,28 +33,32 @@ TemplateCache::TemplateCache() : _logger(NULL)
 
 TemplateCache::~TemplateCache()
 {
-	_instance = NULL;
+	_pInstance = 0;
 }
 
+
 void TemplateCache::setup()
 {
-	poco_assert (_instance == NULL);
+	poco_assert (_pInstance == 0);
-	_instance = this;
+	_pInstance = this;
 }
 
 
 Template::Ptr TemplateCache::getTemplate(const Path& path)
 {
-	if ( _logger )
+	if (_pLogger)
 	{
-		poco_trace_f1(*_logger, "Trying to load %s", path.toString());
+		poco_trace_f1(*_pLogger, "Trying to load %s", path.toString());
 	}
+
 	Path templatePath = resolvePath(path);
 	std::string templatePathname = templatePath.toString();
-	if ( _logger )
+	
+	if (_pLogger)
 	{
-		poco_trace_f1(*_logger, "Path resolved to %s", templatePathname);
+		poco_trace_f1(*_pLogger, "Path resolved to %s", templatePathname);
 	}
+	
 	File templateFile(templatePathname);
 
 	Template::Ptr tpl;
@@ -64,9 +68,9 @@ Template::Ptr TemplateCache::getTemplate(const Path& path)
 	{
 		if (templateFile.exists())
 		{
-			if ( _logger )
+			if (_pLogger)
 			{
-				poco_information_f1(*_logger, "Loading template %s", templatePath.toString());
+				poco_information_f1(*_pLogger, "Loading template %s", templatePath.toString());
 			}
 
 			tpl = new Template(templatePath);
@@ -78,17 +82,17 @@ Template::Ptr TemplateCache::getTemplate(const Path& path)
 			}
 			catch (JSONTemplateException& jte)
 			{
-				if ( _logger )
+				if (_pLogger)
 				{
-					poco_error_f2(*_logger, "Template %s contains an error: %s", templatePath.toString(), jte.message());
+					poco_error_f2(*_pLogger, "Template %s contains an error: %s", templatePath.toString(), jte.message());
 				}
 			}
 		}
 		else
 		{
-			if ( _logger )
+			if (_pLogger)
 			{
-				poco_error_f1(*_logger, "Template file %s doesn't exist", templatePath.toString());
+				poco_error_f1(*_pLogger, "Template file %s doesn't exist", templatePath.toString());
 			}
 			throw FileNotFoundException(templatePathname);
 		}
@@ -98,9 +102,9 @@ Template::Ptr TemplateCache::getTemplate(const Path& path)
 		tpl = it->second;
 		if (tpl->parseTime() < templateFile.getLastModified())
 		{
-			if ( _logger )
+			if (_pLogger)
 			{
-				poco_information_f1(*_logger, "Reloading template %s", templatePath.toString());
+				poco_information_f1(*_pLogger, "Reloading template %s", templatePath.toString());
 			}
 
 			tpl = new Template(templatePath);
@@ -112,9 +116,9 @@ Template::Ptr TemplateCache::getTemplate(const Path& path)
 			}
 			catch (JSONTemplateException& jte)
 			{
-				if ( _logger )
+				if (_pLogger)
 				{
-					poco_error_f2(*_logger, "Template %s contains an error: %s", templatePath.toString(), jte.message());
+					poco_error_f2(*_pLogger, "Template %s contains an error: %s", templatePath.toString(), jte.message());
 				}
 			}
 		}
@@ -136,15 +140,15 @@ Path TemplateCache::resolvePath(const Path& path) const
 		File templateFile(templatePath);
 		if (templateFile.exists())
 		{
-			if ( _logger )
+			if (_pLogger)
 			{
-				poco_trace_f2(*_logger, "%s template file resolved to %s", path.toString(), templatePath.toString());
+				poco_trace_f2(*_pLogger, "%s template file resolved to %s", path.toString(), templatePath.toString());
 			}
 			return templatePath;
 		}
-		if ( _logger )
+		if (_pLogger)
 		{
-			poco_trace_f1(*_logger, "%s doesn't exist", templatePath.toString());
+			poco_trace_f1(*_pLogger, "%s doesn't exist", templatePath.toString());
 		}
 	}