Fix FSTR_IMPORT and IMPORT_FSTR_ARRAY so they're compatible with DECLARE_xxx

Thanks to @aemseemann for this suggestion

aemseemann/Sming#4 (comment)

Global C symbols are named using standard __fstr__ prefix and code uses references.

Author: mikee47

src/include/FlashString/Array.hpp

@@ -95,13 +95,15 @@
 
 /**
  * @brief Define an Array containing data from an external file
- * @param name Name for the object
- * @param ElementType
+ * @param name Name for the Array object
+ * @param ElementType Array element type
  * @param file Absolute path to the file containing the content
+ * @See See also `IMPORT_FSTR_DATA`
+ * @{
  */
-#define IMPORT_FSTR_ARRAY(name, ElementType, file)                                                                     \
-	IMPORT_FSTR_DATA(name, file)                                                                                       \
-	extern "C" const FSTR::Array<ElementType> name;
+#define IMPORT_FSTR_ARRAY(name, ElementType, file) IMPORT_FSTR_OBJECT(name, FSTR::Array<ElementType>, file)
+#define IMPORT_FSTR_ARRAY_LOCAL(name, ElementType, file) IMPORT_FSTR_OBJECT_LOCAL(name, FSTR::Array<ElementType>, file)
+/** @} */
 
 namespace FSTR
 {

src/include/FlashString/Object.hpp

@@ -81,6 +81,26 @@
 	static_assert(std::is_pod<decltype(name)>::value, "FSTR structure not POD");                                       \
 	static_assert(offsetof(decltype(name), data) == sizeof(uint32_t), "FSTR structure alignment error");
 
+/**
+ * @brief Import an object from an external file with reference
+ * @param name Name for the object
+ * @param ObjectType Object type for reference
+ * @param file Absolute path to the file containing the content
+ * @See See also `IMPORT_FSTR_DATA`
+ * @note Can only be used at file scope
+ * @{
+ */
+#define IMPORT_FSTR_OBJECT(name, ObjectType, file)                                                                     \
+	IMPORT_FSTR_DATA(FSTR_DATA_NAME(name), file)                                                                       \
+	extern "C" const FSTR::ObjectBase FSTR_DATA_NAME(name);                                                            \
+	DEFINE_FSTR_REF(name, ObjectType, FSTR_DATA_NAME(name));
+
+#define IMPORT_FSTR_OBJECT_LOCAL(name, ObjectType, file)                                                               \
+	IMPORT_FSTR_DATA(FSTR_DATA_NAME(name), file)                                                                       \
+	extern "C" const FSTR::ObjectBase FSTR_DATA_NAME(name);                                                            \
+	static constexpr DEFINE_FSTR_REF(name, ObjectType, FSTR_DATA_NAME(name));
+/** @} */
+
 namespace FSTR
 {
 /**

src/include/FlashString/String.hpp

@@ -130,10 +130,12 @@ typedef const __FlashStringHelper* flash_string_t;
  * @brief Define a FSTR::String containing data from an external file
  * @param name Name for the FSTR::String object
  * @param file Absolute path to the file containing the content
+ * @See See also `IMPORT_FSTR_DATA`
+ * @{
  */
-#define IMPORT_FSTR(name, file)                                                                                        \
-	IMPORT_FSTR_DATA(name, file)                                                                                       \
-	extern "C" const FSTR::String name;
+#define IMPORT_FSTR(name, file) IMPORT_FSTR_OBJECT(name, FSTR::String, file)
+#define IMPORT_FSTR_LOCAL(name, file) IMPORT_FSTR_OBJECT_LOCAL(name, FSTR::String, file)
+/** @} */
 
 /**
  * @brief declare a table of FlashStrings

test/app/data.cpp

@@ -58,8 +58,8 @@ DEFINE_FSTR_MAP(arrayMap, int, FSTR::Array<float>, {1, &row1}, {2, &row2});
 
 DEFINE_FSTR_LOCAL(key1, "key1");
 DEFINE_FSTR_LOCAL(key2, "key2");
-IMPORT_FSTR(FS_content1, COMPONENT_PATH "/files/content1.txt");
-IMPORT_FSTR(FS_content2, COMPONENT_PATH "/files/content2.txt");
+IMPORT_FSTR_LOCAL(FS_content1, COMPONENT_PATH "/files/content1.txt");
+IMPORT_FSTR_LOCAL(FS_content2, COMPONENT_PATH "/files/content2.txt");
 DEFINE_FSTR_MAP(stringMap, FSTR::String, FSTR::String, {&key1, &FS_content1}, {&key2, &FS_content2});
 
 DEFINE_FSTR_MAP(enumMap, MapKey, FSTR::String, {KeyA, &FS_content1}, {KeyB, &FS_content2});

utility.rst

@@ -9,14 +9,24 @@ using :c:func:`IMPORT_FSTR` or :c:func:`IMPORT_FSTR_ARRAY`. For example::
 
    IMPORT_FSTR(myData, PROJECT_DIR "/files/myData.bin");
 
+This defines a C++ reference to the data called ``myData`` so it can be referred to using
+:c:func:`DECLARE_FSTR` if required.
+
 .. note::
 
    File paths must be absolute or the compiler won't be able to locate it reliably.
 
    Sming provides :envvar:`PROJECT_DIR` and :envvar:`COMPONENT_PATH` to help with this.
 
-A single global C symbol ``myFlashString`` will be defined so take care
-with naming to avoid the risk of conflicts, especially if used within a Component.
+
+.. note::
+
+   A corresponding global C symbol will also be defined, based on the provided name,
+   to provide linkage with the imported data.
+
+   Such symbols cannot be localised as it requires use of ``extern``, so take care with
+   naming to avoid the risk of conflicts, especially if used within a Component.
+
 
 One use for imported files is to serve content via HTTP, like this::