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 <wellnho...@aevum.de> Authored: Thu Feb 2 15:10:57 2017 +0100 Committer: Nick Wellnhofer <wellnho...@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