Add DECLARE_FSTR_OBJECT macro, and rearrange custom object sample to use it

Author: mikee47

src/include/FlashString/Array.hpp

@@ -36,7 +36,7 @@
  * @param ElementType
  * @note Use `DEFINE_FSTR_ARRAY` to instantiate the global Object
  */
-#define DECLARE_FSTR_ARRAY(name, ElementType) extern const FSTR::Array<ElementType>& name;
+#define DECLARE_FSTR_ARRAY(name, ElementType) DECLARE_FSTR_OBJECT(name, FSTR::Array<ElementType>)
 
 /**
  * @brief Define an Array Object with global reference

src/include/FlashString/Map.hpp

@@ -39,7 +39,7 @@
  * @param ContentType Object type to declare for content
  * @note Use DEFINE_FSTR_MAP to instantiate the global object
  */
-#define DECLARE_FSTR_MAP(name, KeyType, ContentType) extern const FSTR::Map<KeyType, ContentType>& name;
+#define DECLARE_FSTR_MAP(name, KeyType, ContentType) DECLARE_FSTR_OBJECT(name, DECL((FSTR::Map<KeyType, ContentType>)))
 
 /**
  * @brief Define a Map Object with global reference

src/include/FlashString/Object.hpp

@@ -33,6 +33,13 @@
  * @{
  */
 
+/**
+ * @brief Declare a global Object reference
+ * @param name
+ * @param ObjectType
+ */
+#define DECLARE_FSTR_OBJECT(name, ObjectType) extern const ObjectType& name;
+
 /**
  * @brief Define a reference to an object
  * @param name Name for reference

src/include/FlashString/String.hpp

@@ -60,7 +60,7 @@ typedef const __FlashStringHelper* flash_string_t;
  * @param name
  * @note Define the FSTR::String object using DEFINE_STR()
  */
-#define DECLARE_FSTR(name) extern const FSTR::String& name;
+#define DECLARE_FSTR(name) DECLARE_FSTR_OBJECT(name, FSTR::String)
 
 /**
  * @brief Define a FSTR::String object with global reference

src/include/FlashString/Vector.hpp

@@ -36,7 +36,7 @@
  * @param ObjectType
  * @note Use `DEFINE_VECTOR` to instantiate the global Object
  */
-#define DECLARE_FSTR_VECTOR(name, ObjectType) extern const FSTR::Vector<ObjectType>& name;
+#define DECLARE_FSTR_VECTOR(name, ObjectType) DECLARE_FSTR_OBJECT(name, FSTR::Vector<ObjectType>)
 
 /**
  * @brief Define a Vector Object with global reference

test/app/custom.cpp

@@ -20,80 +20,13 @@
  ****/
 
 #include <SmingTest.h>
-#include <FlashString/Array.hpp>
+#include "custom.h"
 
 /*
- * This is the structure for our custom object, the contents of which will be
- * loaded from an external file.
+ * Import the data and define a reference for it.
+ * If we don't want `customObject` to be global, use `IMPORT_FSTR_OBJECT_LOCAL`.
  */
-struct MyCustomStruct {
-	FSTR::ObjectBase object;
-	char name[12];
-	char description[20];
-	/*
-	 * A contained Object. This could be:
-	 *
-	 * 	- A String
-	 * 	- An Array
-	 * 	- Another MyCustomObject
-	 * 	- Another custom object
-	 *
-	 * Structures cannot contain pointers when loaded from a file,
-	 * so Vectors and Maps aren't possible.
-	 */
-	FSTR::ObjectBase dataArray;
-};
-
-class CustomObject : public FSTR::Object<CustomObject, char>
-{
-};
-
-class MyCustomObject : public CustomObject
-{
-public:
-	String name() const
-	{
-		return readString(offsetof(MyCustomStruct, name), sizeof(MyCustomStruct::name));
-	}
-
-	String description() const
-	{
-		return readString(offsetof(MyCustomStruct, description), sizeof(MyCustomStruct::description));
-	}
-
-	/*
-	 * Access the contained object as uint8_t[]
-	 */
-	const FSTR::Array<uint8_t>& content() const
-	{
-		return data()->dataArray.as<FSTR::Array<uint8_t>>();
-	}
-
-	/*
-	 * Provide a pointer to the raw data as defined by our structure
-	 */
-	const MyCustomStruct* data() const
-	{
-		return reinterpret_cast<const MyCustomStruct*>(CustomObject::data());
-	}
-
-private:
-	// Helper method so we can pull out the text strings more easily
-	String readString(size_t offset, size_t len) const
-	{
-		char buf[len + 1];
-		read(offset, buf, len);
-		buf[len] = '\0';
-		return buf;
-	}
-};
-
-/*
- * Import the data and define a symbol for it.
- * Note that the symbol _is_ the data, it's not a pointer or a reference.
- */
-IMPORT_FSTR_DATA(customObject, COMPONENT_PATH "/files/custom.bin");
-extern "C" const MyCustomObject customObject;
+IMPORT_FSTR_OBJECT(customObject, MyCustomObject, COMPONENT_PATH "/files/custom.bin");
 
 class CustomTest : public TestGroup
 {

test/app/custom.h

@@ -0,0 +1,99 @@
+/**
+ * custom.h - Test creation of custom objects
+ *
+ * Copyright 2019 mikee47 <[email protected]>
+ *
+ * This file is part of the FlashString Library
+ *
+ * This library is free software: you can redistribute it and/or modify it under the terms of the
+ * GNU General Public License as published by the Free Software Foundation, version 3 or later.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with FlashString.
+ * If not, see <https://www.gnu.org/licenses/>.
+ *
+ * @author: Nov 2019 - mikee47 <[email protected]>
+ *
+ ****/
+
+#include <WString.h>
+#include <FlashString/Array.hpp>
+
+/*
+ * This is the structure for our custom object, the contents of which will be
+ * loaded from an external file.
+ */
+struct MyCustomStruct {
+	FSTR::ObjectBase object;
+	char name[12];
+	char description[20];
+	/*
+	 * A contained Object. This could be:
+	 *
+	 * 	- A String
+	 * 	- An Array
+	 * 	- Another MyCustomObject
+	 * 	- Another custom object
+	 *
+	 * Structures cannot contain pointers when loaded from a file,
+	 * so Vectors and Maps aren't possible.
+	 */
+	FSTR::ObjectBase dataArray;
+};
+
+/*
+ * Define a base object type using char[]
+ */
+class CustomObject : public FSTR::Object<CustomObject, char>
+{
+protected:
+	// Helper method so we can pull out text strings more easily
+	String readString(size_t offset, size_t len) const
+	{
+		char buf[len + 1];
+		len = read(offset, buf, len);
+		buf[len] = '\0';
+		return buf;
+	}
+};
+
+/*
+ * Now derive our custom object with appropriate accessor methods
+ */
+class MyCustomObject : public CustomObject
+{
+public:
+	String name() const
+	{
+		return readString(offsetof(MyCustomStruct, name), sizeof(MyCustomStruct::name));
+	}
+
+	String description() const
+	{
+		return readString(offsetof(MyCustomStruct, description), sizeof(MyCustomStruct::description));
+	}
+
+	/*
+	 * Access the contained object as uint8_t[]
+	 */
+	const FSTR::Array<uint8_t>& content() const
+	{
+		return data()->dataArray.as<FSTR::Array<uint8_t>>();
+	}
+
+	/*
+	 * Provide a pointer to the raw data as defined by our structure
+	 */
+	const MyCustomStruct* data() const
+	{
+		return reinterpret_cast<const MyCustomStruct*>(CustomObject::data());
+	}
+};
+
+/*
+ * Declare the global object (imported and defined in custom.cpp).
+ */
+DECLARE_FSTR_OBJECT(customObject, MyCustomObject);

utility.rst

@@ -53,7 +53,7 @@ You'll need to define an appropriate symbol::
    struct MyCustomStruct {
       uint32_t length;
       char name[12];
-      char description[256];
+      char description[20];
       uint8_t data[1024];
    };
 
@@ -65,8 +65,33 @@ you can just copy it into RAM::
    MyCustomStruct buf;
    memcpy_P(&buf, &myCustomData, sizeof(buf));
 
-However, a better way is to define a custom Object to handle it.
-You can find an example of how to do this in ``test/app/custom.cpp``.
+
+Custom Objects
+--------------
+
+A better way to handle large, complex structures is to define a custom Object to handle it.
+You can find an example of how to do this in ``test/app/custom.cpp``, which does this:
+
+1. Define ``MyCustomStruct``::
+   
+      struct MyCustomStruct {
+         FSTR::ObjectBase object;
+         char name[12];
+         char description[20];
+         FSTR::ObjectBase dataArray;
+      };
+
+2. Define a base object type (``CustomObject``) using the :cpp:class:`FSTR::Object` class template.
+   This determines the underlying element type, generally ``char`` or ``uint8_t`` are most useful.
+
+3. Derive an Object class (``MyCustomObject``) to encapsulate access to ``MyCustomStruct``.
+
+4. Use the :c:func:`IMPORT_FSTR_OBJECT` macro to import the custom data and define a global
+   reference (``customObject``) of type ``MyCustomObject&``.
+
+5. Use :c:func:`DECLARE_FSTR_OBJECT` macro to declare the reference in a header.
+ 
+More complex examples may involve multiple custom Object types.
 
 
 API Reference