Slight improvement to Eet documentation.

It was mostly done already and examples were there, but some things were
revamped, clarified and now there's a detailed explanation on more important
groups.


SVN revision: 60308

legacy/eet/doc/Doxyfile.in

@@ -1,7 +1,7 @@
 PROJECT_NAME           = Eet
 PROJECT_NUMBER         = @PACKAGE_VERSION@
 OUTPUT_DIRECTORY       = .
-INPUT                  = @srcdir@/eet.dox @srcdir@/examples.dox @srcdir@/src/lib
+INPUT                  = @srcdir@/eet.dox @srcdir@/examples.dox @top_srcdir@/src/lib
 IMAGE_PATH             = img
 OUTPUT_LANGUAGE        = English
 GENERATE_HTML          = YES

legacy/eet/doc/examples.dox

@@ -12,6 +12,20 @@
  * <a href="examples.html">List of examples</a>
  */
 
+/**
+ * @page Example_Eet_Basic Very basic Eet example
+ *
+ * @includelineno eet-basic.c
+ * @example eet-basic.c
+ */
+
+/**
+ * @page Example_Eet_File Example of the various ways to interface with an Eet File
+ *
+ * @includelineno eet-file.c
+ * @example eet-file.c
+ */
+
 /**
  * @page Example_Eet_Data_Simple Simple data example
  *

legacy/eet/doc/foot.html

@@ -9,6 +9,7 @@
   <div id="footer">
     <table><tr>
       <td class="poweredby"><img src="doxygen.png"></td>
+      <td>Samsung Electronics is supporting the EFL Documentation Project</td>
       <td class="copyright">Copyright &copy;$year Enlightenment</td>
       <td class="generated">Docs generated $datetime</td>
     </tr></table>

legacy/eet/src/examples/Makefile.am

@@ -7,7 +7,13 @@ AM_CPPFLAGS = \
 -I$(top_srcdir)/src/lib \
 @EINA_CFLAGS@
 
-pkglib_PROGRAMS = eet_data_simple eet_data_nested eet_data_file_descriptor
+pkglib_PROGRAMS = eet_basic eet_file eet_data_simple eet_data_nested eet_data_file_descriptor
+
+eet_basic_SOURCES = eet-basic.c
+eet_basic_LDADD = $(top_builddir)/src/lib/libeet.la @EINA_LIBS@
+
+eet_file_SOURCES = eet-file.c
+eet_file_LDADD = $(top_builddir)/src/lib/libeet.la @EINA_LIBS@
 
 eet_data_simple_SOURCES = eet-data-simple.c
 eet_data_simple_LDADD = $(top_builddir)/src/lib/libeet.la @EINA_LIBS@
@@ -25,6 +31,8 @@ files_DATA =
 if INSTALL_EXAMPLES
 
 files_DATA += \
+eet-basic.c \
+eet-file.c \
 eet-data-simple.c \
 eet-data-nested.c \
 eet-data-file_descriptor.c

legacy/eet/src/examples/eet-basic.c

@@ -0,0 +1,36 @@
+#include <Eet.h>
+
+int
+main(void)
+{
+  Eet_File *ef;
+  char     *ret;
+  int       size;
+  char     *entries[] =
+    {
+      "Entry 1",
+      "Big text string here compared to others",
+      "Eet is cool"
+    };
+
+  eet_init();
+
+  // blindly open an file for output and write strings with their NUL char
+  ef = eet_open("test.eet", EET_FILE_MODE_WRITE);
+  eet_write(ef, "Entry 1", entries[0], strlen(entries[0]) + 1, 0);
+  eet_write(ef, "Entry 2", entries[1], strlen(entries[1]) + 1, 1);
+  eet_write(ef, "Entry 3", entries[2], strlen(entries[2]) + 1, 0);
+  eet_close(ef);
+
+  // open the file again and blindly get the entries we wrote
+  ef = eet_open("test.eet", EET_FILE_MODE_READ);
+  ret = eet_read(ef, "Entry 1", &size);
+  printf("%s\n", ret);
+  ret = eet_read(ef, "Entry 2", &size);
+  printf("%s\n", ret);
+  ret = eet_read(ef, "Entry 3", &size);
+  printf("%s\n", ret);
+  eet_close(ef);
+
+  eet_shutdown();
+}

legacy/eet/src/examples/eet-data-file_descriptor.c

@@ -1,3 +1,6 @@
+/*
+ * build: gcc -o eet_data_file_descriptor eet-data-file_descriptor.c `pkg-config --cflags --libs eet eina`
+ */
 #include <Eina.h>
 #include <Eet.h>
 #include <stdio.h>
@@ -9,9 +12,9 @@
 // complex real-world structures based on elmdentica database
 typedef struct
 {
-   const char * screen_name;
-   const char * name;
-   const char * message;
+   const char  *screen_name;
+   const char  *name;
+   const char  *message;
    unsigned int id;
    unsigned int status_id;
    unsigned int date;
@@ -20,22 +23,23 @@ typedef struct
 
 typedef struct
 {
-   const char * dm_to;
-   const char * message;
+   const char *dm_to;
+   const char *message;
 } My_Post;
 
 typedef struct
 {
    unsigned int id;
-   const char * name;
-   Eina_List *  messages;
-   Eina_List *  posts;
+   const char  *name;
+   Eina_List   *messages;
+   My_Post     *posts;
+   int          posts_count;
 } My_Account;
 
 typedef struct
 {
    unsigned int version; // it is recommended to use versioned configuration!
-   Eina_List *  accounts;
+   Eina_Hash   *accounts;
 } My_Cache;
 
 // string that represents the entry in eet file, you might like to have
@@ -46,14 +50,14 @@ static const char MY_CACHE_FILE_ENTRY[] = "cache";
 // keep the descriptor static global, so it can be
 // shared by different functions (load/save) of this and only this
 // file.
-static Eet_Data_Descriptor * _my_cache_descriptor;
-static Eet_Data_Descriptor * _my_account_descriptor;
-static Eet_Data_Descriptor * _my_message_descriptor;
-static Eet_Data_Descriptor * _my_post_descriptor;
+static Eet_Data_Descriptor *_my_cache_descriptor;
+static Eet_Data_Descriptor *_my_account_descriptor;
+static Eet_Data_Descriptor *_my_message_descriptor;
+static Eet_Data_Descriptor *_my_post_descriptor;
 
 // keep file handle alive, so mmap()ed strings are all alive as well
-static Eet_File * _my_cache_file = NULL;
-static Eet_Dictionary * _my_cache_dict = NULL;
+static Eet_File *_my_cache_file = NULL;
+static Eet_Dictionary *_my_cache_dict = NULL;
 
 static void
 _my_cache_descriptor_init(void)
@@ -107,7 +111,7 @@ _my_cache_descriptor_init(void)
    EET_DATA_DESCRIPTOR_ADD_LIST
       (_my_account_descriptor, My_Account, "messages", messages,
       _my_message_descriptor);
-   EET_DATA_DESCRIPTOR_ADD_LIST
+   EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY
       (_my_account_descriptor, My_Account, "posts",    posts,
       _my_post_descriptor);
 
@@ -117,7 +121,7 @@ _my_cache_descriptor_init(void)
    ADD_BASIC(version, EET_T_UINT);
 #undef ADD_BASIC
 
-   EET_DATA_DESCRIPTOR_ADD_LIST
+   EET_DATA_DESCRIPTOR_ADD_HASH
       (_my_cache_descriptor, My_Cache, "accounts", accounts,
       _my_account_descriptor);
 } /* _my_cache_descriptor_init */
@@ -168,18 +172,22 @@ _my_message_free(My_Message * msg)
    free(msg);
 } /* _my_message_free */
 
-static My_Post *
-_my_post_new(const char * message)
+static Eina_Bool
+_my_post_add(My_Account *acc, const char * message)
 {
-   My_Post * post = calloc(1, sizeof(My_Post));
+   int new_count = acc->posts_count + 1;
+   My_Post *post = realloc(acc->posts, new_count * sizeof(My_Post));
    if (!post)
      {
-        fprintf(stderr, "ERROR: could not calloc My_Post\n");
-        return NULL;
+        fprintf(stderr, "ERROR: could add My_Post\n");
+        return EINA_FALSE;
      }
 
-   post->message = eina_stringshare_add(message);
-   return post;
+   post[acc->posts_count].message = eina_stringshare_add(message);
+   post[acc->posts_count].dm_to = NULL;
+   acc->posts_count = new_count;
+   acc->posts = post;
+   return EINA_TRUE;;
 } /* _my_post_new */
 
 static void
@@ -187,7 +195,6 @@ _my_post_free(My_Post * post)
 {
    _eet_string_free(post->dm_to);
    _eet_string_free(post->message);
-   free(post);
 } /* _my_post_free */
 
 static My_Account *
@@ -208,15 +215,16 @@ static void
 _my_account_free(My_Account * acc)
 {
    My_Message * m;
-   My_Post * p;
+   int i;
 
    _eet_string_free(acc->name);
 
    EINA_LIST_FREE(acc->messages, m)
-   _my_message_free(m);
+      _my_message_free(m);
 
-   EINA_LIST_FREE(acc->posts, p)
-   _my_post_free(p);
+   for (i = 0; i < acc->posts_count; i++)
+     _my_post_free(&acc->posts[i]);
+   free(acc->posts);
 
    free(acc);
 } /* _my_account_free */
@@ -231,29 +239,32 @@ _my_cache_new(void)
         return NULL;
      }
 
+   my_cache->accounts = eina_hash_string_small_new(NULL);
+
    my_cache->version = 1;
    return my_cache;
 } /* _my_cache_new */
 
+static Eina_Bool
+_my_cache_account_free_cb(const Eina_Hash *hash, const void *key, void *data, void *fdata)
+{
+   _my_account_free(data);
+   return EINA_TRUE;
+}
+
 static void
 _my_cache_free(My_Cache * my_cache)
 {
    My_Account * acc;
-   EINA_LIST_FREE(my_cache->accounts, acc)
-   _my_account_free(acc);
+   eina_hash_foreach(my_cache->accounts, _my_cache_account_free_cb, NULL);
+   eina_hash_free(my_cache->accounts);
    free(my_cache);
 } /* _my_cache_free */
 
 static My_Account *
 _my_cache_account_find(My_Cache * my_cache, const char * name)
 {
-   My_Account * acc;
-   Eina_List * l;
-   EINA_LIST_FOREACH(my_cache->accounts, l, acc)
-   if (strcmp(acc->name, name) == 0)
-      return acc;
-
-   return NULL;
+   return eina_hash_find(my_cache->accounts, name);
 } /* _my_cache_account_find */
 
 static My_Cache *
@@ -349,6 +360,7 @@ int main(int argc, char * argv[])
 {
    My_Cache * my_cache;
    const Eina_List * l_acc;
+   Eina_Iterator *it;
    My_Account * acc;
    int ret = 0;
 
@@ -391,8 +403,7 @@ int main(int argc, char * argv[])
                   if (!acc)
                     {
                        acc = _my_account_new(argv[4]);
-                       my_cache->accounts = eina_list_append
-                             (my_cache->accounts, acc);
+                       eina_hash_direct_add(my_cache->accounts, acc->name, acc);
                     }
                   else
                      fprintf(stderr, "ERROR: account '%s' already exists.\n",
@@ -410,8 +421,7 @@ int main(int argc, char * argv[])
                   My_Account * acc = _my_cache_account_find(my_cache, argv[4]);
                   if (acc)
                     {
-                       My_Post * post = _my_post_new(argv[5]);
-                       acc->posts = eina_list_append(acc->posts, post);
+                       _my_post_add(acc, argv[5]);
                     }
                   else
                      fprintf(stderr, "ERROR: unknown account: '%s'\n", argv[4]);
@@ -447,15 +457,16 @@ int main(int argc, char * argv[])
           "\tversion.: %#x\n"
           "\taccounts: %u\n",
           my_cache->version,
-          eina_list_count(my_cache->accounts));
-   EINA_LIST_FOREACH(my_cache->accounts, l_acc, acc)
+          eina_hash_population(my_cache->accounts));
+   it = eina_hash_iterator_data_new(my_cache->accounts);
+   EINA_ITERATOR_FOREACH(it, acc)
    {
       const My_Post * post;
 
       printf("\t  > %-#8x '%.20s' stats: m=%u, p=%u\n",
              acc->id, acc->name ? acc->name : "",
              eina_list_count(acc->messages),
-             eina_list_count(acc->posts));
+             acc->posts_count);
 
       if (eina_list_count(acc->messages))
         {
@@ -473,14 +484,15 @@ int main(int argc, char * argv[])
            }
         }
 
-      if (eina_list_count(acc->posts))
+      if (acc->posts_count)
         {
-           const Eina_List * l;
            const My_Post * post;
+           int i;
            printf("\t  |posts:\n");
 
-           EINA_LIST_FOREACH(acc->posts, l, post)
+           for (i = 0; i < acc->posts_count; i++)
            {
+              post = &acc->posts[i];
               if (post->dm_to)
                  printf("\t  |  @%s: '%.20s'\n", post->dm_to, post->message);
               else
@@ -490,6 +502,7 @@ int main(int argc, char * argv[])
 
       printf("\n");
    }
+   eina_iterator_free(it);
 
    if (!_my_cache_save(my_cache, argv[2]))
       ret = -3;
@@ -497,6 +510,8 @@ int main(int argc, char * argv[])
    _my_cache_free(my_cache);
 
 end:
+   if (_my_cache_file)
+     eet_close(_my_cache_file);
    _my_cache_descriptor_shutdown();
    eet_shutdown();
    eina_shutdown();

legacy/eet/src/examples/eet-data-nested.c

@@ -1,3 +1,6 @@
+/*
+ * build: gcc -o eet_data_nested eet-data-nested.c `pkg-config --cflags --libs eet eina`
+ */
 #include <Eina.h>
 #include <Eet.h>
 #include <stdio.h>

legacy/eet/src/examples/eet-data-simple.c

@@ -1,3 +1,6 @@
+/*
+ * build: gcc -o eet_data_simple eet-data-simple.c `pkg-config --cflags --libs eet eina`
+ */
 #include <Eina.h>
 #include <Eet.h>
 #include <stdio.h>

legacy/eet/src/examples/eet-file.c

@@ -0,0 +1,126 @@
+/*
+ * build: gcc -o eet_file eet-file.c `pkg-config --cflags --libs eet`
+ */
+#include <Eet.h>
+#include <stdio.h>
+#include <string.h>
+
+static int
+create_eet_file(void)
+{
+   Eet_File *ef;
+   char buf[1024], *ptr;
+   int size, len, i;
+   const char *some_strings[] = {
+        "And some more strings",
+        "spread across several",
+        "elements of an array!"
+   };
+   const char some_data[] =
+      "\x1e\xe7\x0f\x42\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x35"
+      "\x00\x00\x00\xa0\x00\x00\x00\xa0\x00\x00\x00\x24\x00\x00\x00\x11"
+      "\x00\x00\x00\x00\x2f\x6d\x69\x73\x74\x65\x72\x69\x6f\x75\x73\x2f"
+      "\x64\x61\x74\x61\x00\x41\x6e\x20\x45\x45\x54\x20\x69\x6e\x73\x69"
+      "\x64\x65\x20\x6f\x66\x20\x61\x6e\x20\x45\x45\x54\x21\x0a\x54\x68"
+      "\x69\x73\x20\x77\x61\x73\x6e\x27\x74\x20\x72\x65\x61\x6c\x6c\x79"
+      "\x20\x75\x73\x65\x66\x75\x6c\x20\x62\x75\x74\x20\x69\x74\x20\x68"
+      "\x65\x6c\x70\x65\x64\x20\x74\x6f\x20\x73\x68\x6f\x77\x20\x68\x6f"
+      "\x77\x0a\x74\x6f\x20\x75\x73\x65\x20\x65\x65\x74\x5f\x6d\x65\x6d"
+      "\x6f\x70\x65\x6e\x5f\x72\x65\x61\x64\x28\x29\x20\x74\x6f\x20\x6f"
+      "\x70\x65\x6e\x20\x61\x6e\x20\x65\x65\x74\x20\x66\x69\x6c\x65\x20"
+      "\x66\x72\x6f\x6d\x0a\x64\x61\x74\x61\x20\x61\x6c\x72\x65\x61\x64"
+      "\x79\x20\x6c\x6f\x61\x64\x65\x64\x20\x69\x6e\x20\x6d\x65\x6d\x6f"
+      "\x72\x79\x2e\x0a\x00";
+
+   ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE);
+   if (!ef) return 0;
+
+   strcpy(buf, "Here is a string of data to save!");
+   size = eet_write(ef, "/key/to_store/at", buf, sizeof(buf), 1);
+   if (!size)
+     {
+        fprintf(stderr, "Error writing data!\n");
+        eet_close(ef);
+        return 0;
+     }
+   len = strlen(buf);
+   printf("strlen() = %d, eet_write() = %d\n", len, size);
+
+   ptr = buf;
+   for (i = 0; i < 3; i++)
+     {
+        len = strlen(some_strings[i]) + 1;
+        memcpy(ptr, some_strings[i], len);
+        ptr += len;
+     }
+   eet_write(ef, "/several/strings", buf, sizeof(buf), 1);
+   eet_sync(ef);
+
+   eet_write(ef, "/some/misterious/data", some_data, sizeof(some_data) - 1, 1);
+
+   eet_delete(ef, "/several/strings");
+
+   return (eet_close(ef) == EET_ERROR_NONE);
+}
+
+int
+main(void)
+{
+  Eet_File *ef;
+  char *ret, **list;
+  int size, num, i;
+
+  eet_init();
+
+  if (!create_eet_file())
+    return -1;
+
+  ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_READ);
+  if (!ef) return -1;
+
+  list = eet_list(ef, "*", &num);
+  if (list)
+    {
+      for (i = 0; i < num; i++)
+        printf("Key stored: %s\n", list[i]);
+      free(list);
+    }
+
+  ret = eet_read(ef, "/key/to_store/at", &size);
+  if (ret)
+    {
+      printf("Data read (%i bytes):\n%s\n", size, ret);
+      free(ret);
+    }
+
+  ret = eet_read(ef, "/several/strings", &size);
+  if (ret)
+    {
+       printf("More data read (%i bytes):\n%s\n", size, ret);
+       free(ret);
+    }
+
+  ret = eet_read(ef, "/some/misterious/data", &size);
+  if (ret)
+    {
+       Eet_File *ef2;
+
+       ef2 = eet_memopen_read(ret, size);
+
+       num = eet_num_entries(ef2);
+       printf("Misterious data has %d entries\n", num);
+
+       printf("Misterious data:\n%s\n",
+              (char *)eet_read_direct(ef2, "/misterious/data", NULL));
+
+       eet_close(ef2);
+
+       free(ret);
+    }
+
+  eet_close(ef);
+
+  eet_shutdown();
+
+  return 0;
+}