add C API documentation

docs/capi.rst

@@ -0,0 +1,96 @@
+C API
+=====
+
+You can write Picrin's extension by yourself from both sides of C and Scheme. This page describes the way to control the interpreter from the C world.
+
+Extension Library
+-----------------
+
+If you want to create a contribution library with C, the only thing you need to do is make a directory under contrib/. Below is a sample code of extension library.
+
+* contrib/add/CMakeLists.txt::
+
+  list(APPEND PICRIN_CONTRIB_INITS "void pic_init_add(pic_state *)\; pic_init_add(pic)\;")
+  list(APPEND PICRIN_CONTRIB_SOURCES ${PROJECT_SOURCE_DIR}/contrib/add/add.c)
+
+* contrib/add/add.c::
+
+  #include "picrin.h"
+
+  static pic_value
+  pic_add(pic_state *pic)
+  {
+    double a, b;
+
+    pic_get_args(pic, "ff", &a, &b);
+
+    return pic_float_value(a + b);
+  }
+
+  void
+  pic_init_add(pic_state *pic)
+  {
+    pic_deflibrary ("(picrin add)") {
+      pic_defun(pic, "add", pic_add);
+    }
+  }
+
+After recompiling the interpreter, the library "(picrin add)" is available in the REPL, which library provides a funciton "add".
+
+User-data vs GC
+^^^^^^^^^^^^^^^
+
+When you use dynamic memory allocation inside C APIs, you must be caseful about Picrin's GC. Fortunately, we provides a set of wrapper functions for complete abstraction of GC. In the case below, the memory (de)allocators *create_foo* and *finalize_foo* are wrapped in pic_data object, so that when an instance of foo losts all references from others to it picrin can automatically finalize the orphan object::
+
+  /** foo.c **/
+  #include <stdlib.h>
+  #include "picrin.h"
+  #include "picrin/data.h"
+
+  /*
+   * C-side API
+   */
+
+  struct foo {
+    // blah blah blah
+  };
+
+  struct foo *
+  create_foo ()
+  {
+    return malloc(sizeof(struct foo));
+  }
+
+  void
+  finalize_foo (void *foo) {
+    struct foo *f = foo;
+    free(f);
+  }
+
+
+  /*
+   * picrin-side FFI interface
+   */
+
+  static const pic_data_type foo_type = { "foo", finalize_foo };
+
+  static pic_value
+  pic_create_foo(pic_state *pic)
+  {
+    struct foo *f;
+    struct pic_data *dat;
+
+    pic_get_args(pic, ""); // no args here
+
+    f = create_foo();
+
+    data = pic_data_alloc(pic, &f, md);
+
+    return pic_obj_value(data);
+  }
+
+  void
+  pic_init_my_data(pic_state *pic)
+  {
+    pic_defun(pic, "create-my-data", pic_create_foo); // (create-foo)
+  }

docs/index.rst

@@ -15,6 +15,7 @@ Contents:
    deploy.rst
    lang.rst
    libs.rst
+   capi.rst
 
 Indices and tables
 ==================