Add INIReader::ParseErrorMessage() to provide brief textual error messages (#205)

Provides a message describing an error when parsing fails.

Also fixed the documentation for INIReader::ParseError() to acknowledge memory
allocation errors.

Added a simple test for the INIReader::ParseErrorMessage() method.

Author: msquire

cpp/INIReader.cpp

@@ -32,6 +32,33 @@ int INIReader::ParseError() const
     return _error;
 }
 
+string INIReader::ParseErrorMessage() const
+{
+    // If _error is positive it means it is the line number on which a parse
+    // error occurred. This could be an overlong line, that ValueHandler
+    // indicated a user defined error, an unterminated section name, or a name
+    // without a value.
+    if (_error > 0) {
+        return "parse error on line " + std::to_string(_error) + "; missing ']' or '='?";
+    }
+
+    // If _error is negative it is a system type error, and 0 means success.
+    switch (_error) {
+    case -2:
+        return "unable to allocate memory";
+
+    case -1:
+        return "unable to open file";
+
+    case 0:
+        return "";
+    }
+
+    // This should never be reached. It probably means a new error code was
+    // added to the C API without updating this method.
+    return "unknown error " + std::to_string(_error);
+}
+
 string INIReader::Get(const string& section, const string& name, const string& default_value) const
 {
     string key = MakeKey(section, name);

cpp/INIReader.h

@@ -53,9 +53,14 @@ class INIReader
     INI_API explicit INIReader(const char *buffer, size_t buffer_size);
 
     // Return the result of ini_parse(), i.e., 0 on success, line number of
-    // first error on parse error, or -1 on file open error.
+    // first error on parse error, -1 on file open error, or -2 if there was a
+    // memory allocation error.
     INI_API int ParseError() const;
 
+    // Return a message that describes the type of error that occurred.
+    // It will return "" (empty string) if there was no error.
+    INI_API std::string ParseErrorMessage() const;
+
     // Get a string value from INI file, returning default_value if not found.
     INI_API std::string Get(const std::string& section, const std::string& name,
                     const std::string& default_value) const;

examples/INIReaderExampleErrors.cpp

@@ -0,0 +1,18 @@
+// Example that demonstrates the ParseErrorMessage() method.
+
+#include <iostream>
+#include "../cpp/INIReader.h"
+
+int main()
+{
+    INIReader reader_file_not_found("/file_that_does_not_exist.ini");
+    INIReader reader_parse_error("../tests/name_only_after_error.ini");
+    INIReader reader_success("../tests/normal.ini");
+
+    std::cout
+        << "reader_file_not_found errmsg: \"" << reader_file_not_found.ParseErrorMessage() << "\"\n"
+        << "reader_parse_error errmsg: \"" << reader_parse_error.ParseErrorMessage() << "\"\n"
+        << "reader_success errmsg: \"" << reader_success.ParseErrorMessage() << "\"\n";
+
+    return 0;
+}

examples/cpptest.sh

@@ -3,3 +3,7 @@
 g++ -Wall INIReaderExample.cpp ../cpp/INIReader.cpp ../ini.c -o INIReaderExample
 ./INIReaderExample > cpptest.txt
 rm INIReaderExample
+
+g++ -Wall INIReaderExampleErrors.cpp ../cpp/INIReader.cpp ../ini.c -o INIReaderExampleErrors
+./INIReaderExampleErrors > cpptesterrors.txt
+rm INIReaderExampleErrors

examples/cpptesterrors.txt

@@ -0,0 +1,3 @@
+reader_file_not_found errmsg: "unable to open file"
+reader_parse_error errmsg: "parse error on line 5; missing ']' or '='?"
+reader_success errmsg: ""