Experimental: Renamed c_autovar => c_with, c_autoscope => c_scope, c_autodefer => c_defer. May or may not be reverted before V4.0 release.

5 files changed, 40 insertions, 35 deletions

diff --git a/docs/carray_api.md b/docs/carray_api.md
index 579bf119..cede295e 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -91,8 +91,8 @@ int main()
     // Ex1
     int xd = 30, yd = 20, zd = 10;
     // define arr3[30][20][10], initialized with zeros.
-    c_autovar (carr3_f arr3 = carr3_f_with_size(xd, yd, zd, 0.0f), 
-                              carr3_f_drop(&arr3)) {
+    c_with (carr3_f arr3 = carr3_f_with_size(xd, yd, zd, 0.0f), 
+                           carr3_f_drop(&arr3)) {
         arr3.data[5][4][3] = 3.14f;
 
         float *arr1 = arr3.data[5][4];
@@ -105,7 +105,7 @@ int main()
 
     // Ex2
     int w = 256, h = 128;
-    c_autovar (carr2_i image = carr2_i_new_uninit(w, h), carr2_i_drop(&image)) {
+    c_with (carr2_i image = carr2_i_new_uninit(w, h), carr2_i_drop(&image)) {
         int n = 0;
         c_foreach (i, carr2_i, image) {
             uint32_t t = n++ % 256;
diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index 6745317d..d37d4d04 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -2,38 +2,41 @@
 
 The following macros are recommended to use, and they safe/have no side-effects.
 
-### c_auto, c_autovar, c_autoscope, c_autodefer
+### c_auto, c_with, c_scope, c_defer
 General ***defer*** mechanics for resource acquisition. These macros allows you to specify the
 freeing of the resources at the point where the acquisition takes place.
 The **checkauto** utility described below, ensures that the `c_auto*` macros are used correctly.
 
-| Usage                                  | Description                                          |
-|:---------------------------------------|:-----------------------------------------------------|
-| `c_auto (Type, var...)`                | `c_autovar (Type var=Type_init(), Type_drop(&var))`  |
-| `c_autovar (Type var=init, end...)`    | Declare `var`. Defer `end...` to end of block        |
-| `c_autoscope (init, end...)`           | Execute `init`. Defer `end...` to end of block       |
-| `c_autodefer (end...)`                 | Defer `end...` to end of block                       |
-| `c_breakauto` or `continue`            | Break out of a `c_auto*`-block/scope without memleak |
-
-For multiple variables, use either multiple **c_autovar** in sequence, or declare variable outside
-scope and use **c_autoscope**. Also, **c_auto** support up to 4 variables.
+| Usage                                  | Description                                               |
+|:---------------------------------------|:----------------------------------------------------------|
+| `c_auto (Type, var...)`                | Same as `c_with (Type var=Type_init(), Type_drop(&var))`  |
+| `c_with (Type var=init, drop)`         | Declare `var`. Defer `drop...` to end of scope            |
+| `c_with (Type var=init, pred, drop)`   | Adds a predicate in order to exit early if init failed    |
+| `c_scope (init, drop...)`              | Execute `init` and defer `drop...` to end of scope        |
+| `c_defer (drop...)`                    | Defer `drop...` to end of scope                           |
+| `continue`                             | Exit a `c_auto/c_with/c_scope...` without memory leaks    |
+
+For multiple variables, use either multiple **c_with** in sequence, or declare variable outside
+scope and use **c_scope**. For convenience, **c_auto** support up to 4 variables.
 ```c
-c_autovar (uint8_t* buf = malloc(BUF_SIZE), free(buf))
-c_autovar (FILE* f = fopen(fname, "rb"), fclose(f))
+// `c_with` is similar to python `with`: it declares and can drop a variable after going out of scope.
+c_with (uint8_t* buf = malloc(BUF_SIZE), free(buf))
+c_with (FILE* fp = fopen(fname, "rb"), fclose(fp))
 {
     int n = 0;
-    if (f && buf) {
-        n = fread(buf, 1, BUF_SIZE, f);
+    if (fp && buf) {
+        n = fread(buf, 1, BUF_SIZE, fp);
         doSomething(buf, n);
     }
 }
 
-c_autovar (cstr s = cstr_new("Hello"), cstr_drop(&s))
+c_with (cstr str = cstr_new("Hello"), cstr_drop(&str))
 {
-    cstr_append(&s, " world");
-    printf("%s\n", cstr_str(&s));
+    cstr_append(&str, " world");
+    printf("%s\n", cstr_str(&str));
 }
 
+// `c_auto` automatically initialize and destruct up to 4 variables, like `c_with`.
 c_auto (cstr, s1, s2)
 {
     cstr_append(&s1, "Hello");
@@ -45,14 +48,16 @@ c_auto (cstr, s1, s2)
     printf("%s %s\n", cstr_str(&s1), cstr_str(&s2));
 }
 
-MyData data;
-c_autoscope (mydata_init(&data), mydata_destroy(&data))
+// `c_scope` is like `c_with` but works with an already declared variable.
+static pthread_mutex_t mut;
+c_scope (pthread_mutex_lock(&mut), pthread_mutex_unlock(&mut))
 {
-    printf("%s\n", cstr_str(&mydata.name));
+    /* Do syncronized work. */
 }
 
+// `c_defer` executes the expressions when leaving scope.
 cstr s1 = cstr_new("Hello"), s2 = cstr_new("world");
-c_autodefer (cstr_drop(&s1), cstr_drop(&s2))
+c_defer (cstr_drop(&s1), cstr_drop(&s2))
 {
     printf("%s %s\n", cstr_str(&s1), cstr_str(&s2));
 }
@@ -70,16 +75,16 @@ cvec_str readFile(const char* name)
 {
     cvec_str vec = cvec_str_init(); // returned
 
-    c_autovar (FILE* fp = fopen(name, "r"), fclose(fp))
-    c_autovar (cstr line = cstr_null, cstr_drop(&line))
-        while (cstr_getline(&line, fp))
-            cvec_str_emplace_back(&vec, cstr_str(&line));
+    c_with (FILE* fp = fopen(name, "r"), fclose(fp))
+        c_with (cstr line = cstr_null, cstr_drop(&line))
+            while (cstr_getline(&line, fp))
+                cvec_str_emplace_back(&vec, cstr_str(&line));
     return vec;
 }
 
 int main()
 {
-    c_autovar (cvec_str x = readFile(__FILE__), cvec_str_drop(&x))
+    c_with (cvec_str x = readFile(__FILE__), cvec_str_drop(&x))
         c_foreach (i, cvec_str, x)
             printf("%s\n", cstr_str(i.ref));
 }
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 91c36def..792d6c8c 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -211,7 +211,7 @@ typedef struct { int x, y, z; } Vec3i;
 int main()
 {
     // Define map with defered destruct
-    c_autovar (cmap_vi vecs = cmap_vi_init(), cmap_vi_drop(&vecs))
+    c_with (cmap_vi vecs = cmap_vi_init(), cmap_vi_drop(&vecs))
     {
         cmap_vi_insert(&vecs, (Vec3i){100,   0,   0}, 1);
         cmap_vi_insert(&vecs, (Vec3i){  0, 100,   0}, 2);
@@ -244,7 +244,7 @@ typedef struct { int x, y, z; } Vec3i;
 
 int main()
 {
-    c_auto (cmap_iv, vecs) // shorthand for c_autovar with _init(), _drop().
+    c_auto (cmap_iv, vecs) // shorthand for c_with with _init(), _drop().
     {
         cmap_iv_insert(&vecs, 1, (Vec3i){100,   0,   0});
         cmap_iv_insert(&vecs, 2, (Vec3i){  0, 100,   0});
diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 3a1a5aa6..91abaae3 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -157,7 +157,7 @@ int main()
 {
     uint32_t col = 0xcc7744ff;
     csmap_id idnames = csmap_id_init();
-    c_autodefer (csmap_id_drop(&idnames)) 
+    c_defer (csmap_id_drop(&idnames)) 
     {
         c_forarray (csmap_id_raw, v, { {100, "Red"}, {110, "Blue"} })
             csmap_id_emplace(&idnames, v->first, v->second);
@@ -238,7 +238,7 @@ typedef struct { int x, y, z; } Vec3i;
 int main()
 {
     // equivalent to: c_auto (csmap_iv, vecs)
-    c_autovar (csmap_iv vecs = csmap_iv_init(), csmap_iv_drop(&vecs))
+    c_with (csmap_iv vecs = csmap_iv_init(), csmap_iv_drop(&vecs))
     {
         csmap_iv_insert(&vecs, 1, (Vec3i){100, 0, 0});
         csmap_iv_insert(&vecs, 2, (Vec3i){0, 100, 0});
diff --git a/docs/csview_api.md b/docs/csview_api.md
index 79d108a3..d6bb4baf 100644
--- a/docs/csview_api.md
+++ b/docs/csview_api.md
@@ -199,7 +199,7 @@ int main()
     print_split(c_sv("This has no matching separator"), c_sv("xx"));
     puts("");
 
-    c_autovar (cstack_str s = string_split(c_sv("Split,this,,string,now,"), c_sv(",")), cstack_str_drop(&s))
+    c_with (cstack_str s = string_split(c_sv("Split,this,,string,now,"), c_sv(",")), cstack_str_drop(&s))
         c_foreach (i, cstack_str, s)
             printf("[%s]\n", cstr_str(i.ref));
 }