From bb2e7f3438e20cc588c79c28c795f3e6e9e0040d Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Astor?= Date: Thu, 29 Apr 2021 21:46:53 +0200 Subject: [PATCH] integrate euppal's changes --- .gitignore | 3 +- docs/Contributing/Plugins/README.md | 1 - .../README.mdr} | 0 docs/Contributing/Plugins/advanced.mdr | 0 docs/Contributing/Plugins/credits.mdr | 3 ++ docs/Contributing/Plugins/list | 2 + docs/Contributing/Plugins/reference.mdr | 50 +++++++++++++++++++ docs/Contributing/list | 3 -- 8 files changed, 56 insertions(+), 6 deletions(-) delete mode 100644 docs/Contributing/Plugins/README.md rename docs/Contributing/{ContributingPlugins.mdr => Plugins/README.mdr} (100%) create mode 100644 docs/Contributing/Plugins/advanced.mdr create mode 100644 docs/Contributing/Plugins/credits.mdr create mode 100644 docs/Contributing/Plugins/reference.mdr diff --git a/.gitignore b/.gitignore index a34cbd92..ecbc9158 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,5 @@ -#src +src book log *.gw ansi2html* -.replit \ No newline at end of file diff --git a/docs/Contributing/Plugins/README.md b/docs/Contributing/Plugins/README.md deleted file mode 100644 index 779d515c..00000000 --- a/docs/Contributing/Plugins/README.md +++ /dev/null @@ -1 +0,0 @@ -# Plugins diff --git a/docs/Contributing/ContributingPlugins.mdr b/docs/Contributing/Plugins/README.mdr similarity index 100% rename from docs/Contributing/ContributingPlugins.mdr rename to docs/Contributing/Plugins/README.mdr diff --git a/docs/Contributing/Plugins/advanced.mdr b/docs/Contributing/Plugins/advanced.mdr new file mode 100644 index 00000000..e69de29b diff --git a/docs/Contributing/Plugins/credits.mdr b/docs/Contributing/Plugins/credits.mdr new file mode 100644 index 00000000..7f7105d7 --- /dev/null +++ b/docs/Contributing/Plugins/credits.mdr @@ -0,0 +1,3 @@ +# Credits + +fennecdjay was of immeasurable help when I was writing these docs. Thank you to them for sitting down and working me through Gwion plugins from the basics. diff --git a/docs/Contributing/Plugins/list b/docs/Contributing/Plugins/list index 9d7dc46a..adaddb7e 100644 --- a/docs/Contributing/Plugins/list +++ b/docs/Contributing/Plugins/list @@ -1,2 +1,4 @@ README.md introduction.md +reference.md +credits.md diff --git a/docs/Contributing/Plugins/reference.mdr b/docs/Contributing/Plugins/reference.mdr new file mode 100644 index 00000000..3d95064d --- /dev/null +++ b/docs/Contributing/Plugins/reference.mdr @@ -0,0 +1,50 @@ +# Plugin Reference + +There are some general macros essential to interfacing with Gwion in general. + +The return codes of functions are of type `m_bool` and consist of the following values: + +Name | Value | Description +---- | ----- | ----------- +`GW_OK` | 1 | Success +`GW_PASS` | 0 | Ignore the result and continue +`GW_ERROR` | -1 | An error occured + +The following macros are sugar for handling error codes. They can exit the scope of the function. It si recommended to use these rather than writing: +```c +if (!a) return NULL; +``` +and co. + +Name | Value | Description +---- | ----- | ----------- +`CHECK_BB` | `if (f < 0) return GW_ERROR;` | Takes an expression that evaluates to `m_bool`. Potentially exits function returning `GW_ERROR`. +`CHECK_BO` | `if (f < 0) return NULL;` | Takes an expression that evaluates to `m_bool`. Potentially exits function returning `NULL`. +`CHECK_OB` | `if (!f) return GW_ERROR;` | Takes an expression that evaluates to a pointer. Potentially exits function returning `GW_ERROR`. +`CHECK_OO` | `if (!f) return NULL;` | Takes an expression that evaluates to a pointer. Potentially exits function returning `NULL`. + +Likewise there are the `DECL_XX` macros which specialize to failing if a declaration fails. Their general syntax is as follows: +```c +DECL_XX(type, var_name, = value); +``` + +These macros are specific to creating plugins. + +`MFUN(name)` signature for a member function +`SFUN(name)` signature for a static function +`CTOR(name)` signature for a constructor +`DTOR(name)` signature for a destructor +`GACK(name)` signature for a pretty print function +`TICK(name)` signature for a UGen *tick* function +`GWION_IMPORT(name)` *main* function of a plugin/library + +in said *main function*, one should use GWI_XX instead of CHECK_XX +since it takes care of position and might optimize some checks away (in gwion's internals) + +`OP_CHECK(name)` define a type checking function. should return + correct type in success + error type on failure + NULL to continue type checking + + +`OP_EMIT(name)` define an emitter function. returns an `m_bool` diff --git a/docs/Contributing/list b/docs/Contributing/list index 67c0d72e..e3828f64 100644 --- a/docs/Contributing/list +++ b/docs/Contributing/list @@ -2,8 +2,5 @@ README.md ContributingCode.md ContributingDocumentation.md ContributingTranslation.md - -ContributingPlugins.md Plugins - Contributors.md -- 2.43.0