You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucy.apache.org by nw...@apache.org on 2017/02/02 14:12:31 UTC
lucy-clownfish git commit: Make more functions public and document
useful macros
Repository: lucy-clownfish
Updated Branches:
refs/heads/master 1b52cc3d6 -> cf8727895
Make more functions public and document useful macros
Fixes CLOWNFISH-114.
Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/cf872789
Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/cf872789
Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/cf872789
Branch: refs/heads/master
Commit: cf8727895be7ca42e3c470db8b2c08e2ab98d9bc
Parents: 1b52cc3
Author: Nick Wellnhofer <we...@aevum.de>
Authored: Thu Feb 2 15:10:57 2017 +0100
Committer: Nick Wellnhofer <we...@aevum.de>
Committed: Thu Feb 2 15:10:57 2017 +0100
----------------------------------------------------------------------
runtime/core/Clownfish/Err.cfh | 46 ++++++++++++++++++++++++++--------
runtime/core/Clownfish/String.cfh | 40 +++++++++++++++++++++++++++--
2 files changed, 73 insertions(+), 13 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/cf872789/runtime/core/Clownfish/Err.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Err.cfh b/runtime/core/Clownfish/Err.cfh
index d825fcf..a4014c5 100644
--- a/runtime/core/Clownfish/Err.cfh
+++ b/runtime/core/Clownfish/Err.cfh
@@ -84,31 +84,47 @@ public class Clownfish::Err inherits Clownfish::Obj {
/** Run `routine` within the host's exception handling
* environment, catching and returning any errors that occur.
- *
- * If an unrecognized host exception is trapped, it will be wrapped in an
+ * `CFISH_Err_Attempt_t` is defined as:
+ *
+ * typedef void (*CFISH_Err_Attempt_t)(void *context);
+ *
+ * `routine` is invoked with the `context` argument. If an
+ * unrecognized host exception is trapped, it will be wrapped in an
* Err so that it can be handled by Clownfish code.
*
+ * @param routine A function pointer.
+ * @param context A void pointer passed to `routine`.
* @return an Err, or NULL if no exception occurs.
*/
public inert incremented nullable Err*
trap(CFISH_Err_Attempt_t routine, void *context);
/** Print an error message to stderr with some C contextual information.
- * Usually invoked via the WARN(pattern, ...) macro.
+ * Usually invoked via the WARN(pattern, ...) macro which
+ * fills `file`, `line`, and `func` with the current code location.
+ *
+ * CFISH_WARN(pattern, ...)
*/
- inert void
+ public inert void
warn_at(const char *file, int line, const char *func,
const char *pattern, ...);
- /** Raise an exception. Usually invoked via the THROW macro.
+ /** Raise an exception. Usually invoked via the THROW macro which
+ * fills `file`, `line`, and `func` with the current code location.
+ *
+ * CFISH_THROW(klass, pattern, ...)
*/
- inert void
+ public inert void
throw_at(Class *klass, const char *file, int line, const char *func,
const char *pattern, ...);
/** Throw an existing exception after tacking on additional context data.
+ * The following convenience macro fills `file`, `line`, and `func`
+ * with the current code location:
+ *
+ * CFISH_RETHROW(error)
*/
- inert void
+ public inert void
rethrow(Err *error, const char *file, int line, const char *func);
/** Raise an exception. Clean up the supplied message by decrementing its
@@ -141,20 +157,28 @@ public class Clownfish::Err inherits Clownfish::Obj {
const char *pattern, ...);
/** Verify that `obj` is either NULL or inherits from
- * `klass`.
+ * `klass`. Throws an exception if the test fails. The following
+ * convenience macro fills `file`, `line`, and `func` with the
+ * current code location:
+ *
+ * CFISH_DOWNCAST(obj, klass)
*
* @return the object.
*/
- inert nullable Obj*
+ public inert nullable Obj*
downcast(Obj *obj, Class *klass, const char *file, int line,
const char *func);
/** Verify that `obj` is not NULL and inherits from
- * `klass`.
+ * `klass`. Throws an exception if the test fails. The following
+ * convenience macro fills `file`, `line`, and `func` with the
+ * current code location:
+ *
+ * CFISH_CERTIFY(obj, klass)
*
* @return the object.
*/
- inert Obj*
+ public inert Obj*
certify(Obj *obj, Class *klass, const char *file, int line,
const char *func);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/cf872789/runtime/core/Clownfish/String.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/String.cfh b/runtime/core/Clownfish/String.cfh
index 6b3323e..20841b2 100644
--- a/runtime/core/Clownfish/String.cfh
+++ b/runtime/core/Clownfish/String.cfh
@@ -45,7 +45,11 @@ public final class Clownfish::String nickname Str
public inert bool
utf8_valid(const char *ptr, size_t len);
- /** Throws an error if the string isn't valid UTF-8.
+ /** Throws an error if the string isn't valid UTF-8. The following
+ * convenience macro fills `file`, `line`, and `func` with the current
+ * code location:
+ *
+ * CFISH_VALIDATE_UTF8(text, size)
*/
public inert void
validate_utf8(const char *text, size_t size, const char *file, int line,
@@ -139,7 +143,39 @@ public final class Clownfish::String nickname Str
public inert incremented String*
new_wrap_trusted_utf8(const char *utf8, size_t size);
- inert incremented String*
+ /** Initialize a String allocated on the stack. This function should
+ * be called via the following macros:
+ *
+ * CFISH_SSTR_WRAP_C(ptr)
+ *
+ * Returns a stack string containing the UTF-8 C string
+ * `const char *ptr`.
+ *
+ * CFISH_SSTR_WRAP_UTF8(ptr, size)
+ *
+ * Returns a stack string containing `size_t size` bytes of UTF-8 data
+ * in `const char *ptr`.
+ *
+ * The UTF-8 data is not checked for validity. The memory pointed to
+ * by `ptr` must stay unchanged for the lifetime of the stack string,
+ * especially when passed as `decremented` argument. It's not required
+ * to release stack strings with `DECREF`, making them practical to be
+ * used with string literals:
+ *
+ * Vec_Push(vec, SSTR_WRAP_C("element"));
+ *
+ * Calling `INCREF` on a stack string returns a heap-allocated copy of
+ * the string as a separate object, making it crucial to always store
+ * the return value:
+ *
+ * String *dest = INCREF(source);
+ *
+ * @param allocation A stack memory region allocated with `alloca` by
+ * the SSTR_WRAP macros.
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
+ */
+ public inert incremented String*
init_stack_string(void *allocation, const char *utf8, size_t size);
/** Initialize a String which wraps an external buffer containing UTF-8