ino

Version: 0.4.0, API: 0.0.0.

About

ino is a minimalist C API to execute JavaScript code and to expose native methods to JavaScript execution contexts.

The code is released under an ISC-style license (see the COPYING file).

API conventions

  • It is not thread-safe to concurrently operate on the same ino_context, unless otherwise specified;
  • All strings are null-terminated, UTF-8 or UTF-16 encoded according to the Unicode 6.0 standard and without BOM (byte-order-mark) characters, unless otherwise specified;
  • ino_variant objects are automatically garbage collected or otherwise destroyed when ino_context_free() is called for the execution context they belong to;
  • No function does input validation, hence, in case the API is misused in this sense, the results are undefined.

Build-time dependencies

  • An environment capable of running Autotools-based build systems;
  • (optional) GNU Autoconf >= 2.68 and GNU Automake to regenerate the build system;
  • (optional) Natural Docs >= 1.5 to regenerate the build system and/or the documentation.

Usage

Both ino implementations and applications/libraries using them are meant to be including <ino/lib.h> in their source files.

Furthermore, ino implementations also need to #define the INO_IMPLEMENTATION flag before such inclusion and should provide suitable pkg-config files for the build systems of applications/libraries to retrieve compiler and linker flags.

This package itself supplies a pkg-config file (package name: ino-headers-0) specifying compiler flags for the inclusion of headers.

Summary
inoVersion: 0.4.0, API: 0.0.0.
Global Declaration MacrosThese macros are meant to be used to delimit declarations in public header files.
INO_BEGIN_C_DECLSDelimits the beginning of public declarations.
INO_END_C_DECLSDelimits the end of public declarations.
Symbol Declaration MacrosThese macros are meant to be used for SINGLE symbol declarations (variables or functions) by prepending them to such declarations.
INO_IMPORTSpecifies that a symbol is imported from a library.
INO_EXPORTSpecifies that a symbol is to be exported.
INO_PUBLICSpecifies that a symbol is publicly visible.
INO_PRIVATESpecifies that a symbol has hidden visibility.
INO_DEFEquivalent to a combination of INO_PUBLIC and INO_EXPORT if the INO_IMPLEMENTATION flag is defined or to a combination of INO_PRIVATE and INO_IMPORT otherwise.
Enumerations
ino_variant_typeVariant type.
Types
ino_contextExecution context.
ino_variantVariant.
ino_method_cbNative method callback.
Functions
ino_context_new()Creates a new execution context.
ino_context_free()Destroys an execution context.
ino_context_get_global_object()Gets the global object in ctx.
ino_variant_new_undefined()Creates a new variant holding undefined.
ino_variant_new_null()Creates a new variant holding null.
ino_variant_new_boolean()Creates a new variant holding the specified boolean value.
ino_variant_new_string()Creates a new variant holding the specified string.
ino_variant_new_string_utf8()Creates a new variant holding the specified string.
ino_variant_new_number()Creates a new variant holding the specified numeric value.
ino_variant_new_object()Creates a new variant holding a new object.
ino_variant_get_type()Gets the type of value held by a variant.
ino_variant_to_boolean()Converts a variant to boolean and returns its value.
ino_variant_to_string()Converts a variant to string and returns a UTF-16 encoding malloc()-allocated copy.
ino_variant_to_string_utf8()Converts a variant to string and returns a UTF-8 encoding malloc()-allocated copy.
ino_variant_to_number()Converts a variant to number and returns its value.
ino_variant_object_get_property()Gets a property from an object.
ino_variant_object_get_property_utf8()Gets a property from an object.
ino_variant_object_set_property()Sets a property on an object.
ino_variant_object_set_property_utf8()Sets a property on an object.
ino_variant_object_add_method()Adds a natively implemented method to an object.
ino_variant_object_add_method_utf8()Adds a natively implemented method to an object.
ino_variant_object_call()Call an object as a function.
ino_variant_protect()Protects a variant from garbage collection.
ino_variant_unprotect()Unprotects a variant from garbage collection.
ino_eval()Evaluates a string of JavaScript code.
ino_eval_utf8()Evaluates a string of JavaScript code.

Global Declaration Macros

These macros are meant to be used to delimit declarations in public header files.

Example

myheader.h

#ifndef MY_HEADER_H
#define MY_HEADER_H

INO_BEGIN_C_DECLS

... blah blah blah ...

INO_END_C_DECLS

#endif

INO_BEGIN_C_DECLS

Delimits the beginning of public declarations.

So that C++ compilers don’t mangle their names.

INO_END_C_DECLS

Delimits the end of public declarations.

So that C++ compilers don’t mangle their names.

Symbol Declaration Macros

These macros are meant to be used for SINGLE symbol declarations (variables or functions) by prepending them to such declarations.

They can be combined together, unless otherwise told.

Example

myfunc.h

INO_PUBLIC void myfunc();

myfunc.c

INO_PUBLIC void
myfunc()
{
        ... blah blah blah ...
}

INO_IMPORT

Specifies that a symbol is imported from a library.

Cannot be combined with INO_EXPORT.

INO_EXPORT

Specifies that a symbol is to be exported.

Cannot be combined with INO_IMPORT.

INO_PUBLIC

Specifies that a symbol is publicly visible.

Cannot be combined with INO_PRIVATE.

INO_PRIVATE

Specifies that a symbol has hidden visibility.

Cannot be combined with INO_PUBLIC.

INO_DEF

Equivalent to a combination of INO_PUBLIC and INO_EXPORT if the INO_IMPLEMENTATION flag is defined or to a combination of INO_PRIVATE and INO_IMPORT otherwise.

Enumerations

ino_variant_type

Variant type.

INO_VARINAT_TYPE_UNDEFINEDundefined value.
INO_VARIANT_TYPE_NULLnull value.
INO_VARIANT_TYPE_BOOLEANBoolean value.
INO_VARIANT_TYPE_STRINGString.
INO_VARIANT_TYPE_NUMBERNumeric value.
INO_VARIANT_TYPE_OBJECTObject.

Types

ino_context

typedef void* ino_context

Execution context.

ino_variant

typedef void* ino_variant

Variant.

ino_method_cb

typedef ino_variant (
   *ino_method_cb
)(ino_context ctx, const ino_variant *args, size_t n_args)

Native method callback.

Parameters

ctxExecution context.
argsArray of arguments passed to the method.
n_argsNumber of elements in args.

Returns

New variant holding the result value.

Functions

ino_context_new()

INO_DEF ino_context ino_context_new()

Creates a new execution context.

Returns

New execution context.

ino_context_free()

INO_DEF void ino_context_free(ino_context ctx)

Destroys an execution context.

ino_context_get_global_object()

INO_DEF ino_variant ino_context_get_global_object(ino_context ctx)

Gets the global object in ctx.

Parameters

ctxExecution context.

Returns

Global object in ctx.

ino_variant_new_undefined()

INO_DEF ino_variant ino_variant_new_undefined(ino_context ctx)

Creates a new variant holding undefined.

Paramters

ctxExecution context.

Returns

Variant holding undefined.

ino_variant_new_null()

INO_DEF ino_variant ino_variant_new_null(ino_context ctx)

Creates a new variant holding null.

Paramters

ctxExecution context.

Returns

Variant holding null.

ino_variant_new_boolean()

INO_DEF ino_variant ino_variant_new_boolean(ino_context ctx,
bool value)

Creates a new variant holding the specified boolean value.

Paramters

ctxExecution context.
valueThe value.

Returns

Variant holding the specified boolean value.

ino_variant_new_string()

INO_DEF ino_variant ino_variant_new_string(ino_context ctx,
const uint16_t *value)

Creates a new variant holding the specified string.

Paramters

ctxExecution context.
valueUTF-16 encoded string.

Returns

Variant holding the specified string.

ino_variant_new_string_utf8()

INO_DEF ino_variant ino_variant_new_string_utf8(ino_context ctx,
const char *value)

Creates a new variant holding the specified string.

Paramters

ctxExecution context.
valueUTF-8 encoded string.

Returns

Variant holding the specified string.

ino_variant_new_number()

INO_DEF ino_variant ino_variant_new_number(ino_context ctx,
double value)

Creates a new variant holding the specified numeric value.

Paramters

ctxExecution context.
valueThe numeric value.

Returns

Variant holding the specified numeric value.

ino_variant_new_object()

INO_DEF ino_variant ino_variant_new_object(ino_context ctx)

Creates a new variant holding a new object.

Paramters

ctxExecution context.

Returns

Variant holding a new object.

ino_variant_get_type()

INO_DEF ino_variant_type ino_variant_get_type(ino_context ctx,
ino_variant variant)

Gets the type of value held by a variant.

Parameters

ctxExecution context.
variantVariant.

Returns

Variant type.

ino_variant_to_boolean()

INO_DEF bool ino_variant_to_boolean(ino_context ctx,
ino_variant variant)

Converts a variant to boolean and returns its value.

Parameters

ctxExecution context.
variantVariant.

Returns

Boolean value.

ino_variant_to_string()

INO_DEF uint16_t * ino_variant_to_string(ino_context ctx,
ino_variant variant)

Converts a variant to string and returns a UTF-16 encoding malloc()-allocated copy.

The returned value should be free()d whe it is no longer needed.

Parameters

ctxExecution context.
variantVariant.

Returns

UTF-16 encoded malloc()-allocated string copy.

ino_variant_to_string_utf8()

INO_DEF char * ino_variant_to_string_utf8(ino_context ctx,
ino_variant variant)

Converts a variant to string and returns a UTF-8 encoding malloc()-allocated copy.

The returned value should be free()d whe it is no longer needed.

Parameters

ctxExecution context.
variantVariant.

Returns

UTF-8 encoded malloc()-allocated string copy.

ino_variant_to_number()

INO_DEF double ino_variant_to_number(ino_context ctx,
ino_variant variant)

Converts a variant to number and returns its value.

Parameters

ctxExecution context.
variantVariant.

Returns

Numeric value.

ino_variant_object_get_property()

INO_DEF ino_variant ino_variant_object_get_property(ino_context ctx,
ino_variant object,
const uint16_t *name)

Gets a property from an object.

Parameters

ctxExecution context.
objectObject variant.
nameUTF-16 encoded property name.

Returns

Variant containing the property value or the undefined value if the object does not have the specified property.

ino_variant_object_get_property_utf8()

INO_DEF ino_variant ino_variant_object_get_property_utf8(ino_context ctx,
ino_variant object,
const char *name)

Gets a property from an object.

Parameters

ctxExecution context.
objectObject variant.
nameUTF-8 encoded property name.

Returns

Variant containing the property value or the undefined value if the object does not have the specified property.

ino_variant_object_set_property()

INO_DEF void ino_variant_object_set_property(ino_context ctx,
ino_variant object,
const uint16_t *name,
ino_variant value)

Sets a property on an object.

Parameters

ctxExecution context.
objectObject variant.
nameUTF-16 encoded property name.
valueVariant containing the property value.

ino_variant_object_set_property_utf8()

INO_DEF void ino_variant_object_set_property_utf8(ino_context ctx,
ino_variant object,
const char *name,
ino_variant value)

Sets a property on an object.

Parameters

ctxExecution context.
objectObject variant.
nameUTF-8 encoded property name.
valueVariant containing the property value.

ino_variant_object_add_method()

INO_DEF ino_variant ino_variant_object_add_method(ino_context ctx,
ino_variant object,
const uint16_t *name,
ino_method_cb cb)

Adds a natively implemented method to an object.

Parameters

ctxExecution context.
objectObject variant.
nameUTF-16 encoded method name.
cbCallback implementing the method.

Returns

Object variant representing the method.

ino_variant_object_add_method_utf8()

INO_DEF ino_variant ino_variant_object_add_method_utf8(ino_context ctx,
ino_variant object,
const char *name,
ino_method_cb cb)

Adds a natively implemented method to an object.

Parameters

ctxExecution context.
objectObject variant.
nameUTF-8 encoded method name.
cbCallback implementing the method.

Returns

Object variant representing the method.

ino_variant_object_call()

INO_DEF ino_variant ino_variant_object_call(ino_context ctx,
ino_variant object,
const ino_variant *args,
size_t n_args)

Call an object as a function.

Parameters

ctxExecution context.
objectObject variant.
argsArray of arguments.
n_argsNumber of elements in args.

Returns

Variant holding the result value.

ino_variant_protect()

INO_DEF void ino_variant_protect(ino_context ctx,
ino_variant variant)

Protects a variant from garbage collection.

A variant may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.

Parameters

ctxExecution context.
variantVariant.

ino_variant_unprotect()

INO_DEF void ino_variant_unprotect(ino_context ctx,
ino_variant variant)

Unprotects a variant from garbage collection.

Parameters

ctxExecution context.
variantVariant.

ino_eval()

INO_DEF ino_variant ino_eval(ino_context ctx,
const uint16_t *script)

Evaluates a string of JavaScript code.

Parameters

ctxExecution context.
scriptUTF-16 encoded string of JavaScript code.

Returns

Variant holding the result value.

ino_eval_utf8()

INO_DEF ino_variant ino_eval_utf8(ino_context ctx,
const char *script)

Evaluates a string of JavaScript code.

Parameters

ctxExecution context.
scriptUTF-8 encoded string of JavaScript code.

Returns

Variant holding the result value.

Specifies that a symbol is publicly visible.
Specifies that a symbol is to be exported.
Specifies that a symbol has hidden visibility.
Specifies that a symbol is imported from a library.
typedef void* ino_context
Execution context.
typedef void* ino_variant
Variant.
typedef ino_variant (
   *ino_method_cb
)(ino_context ctx, const ino_variant *args, size_t n_args)
Native method callback.
INO_DEF ino_context ino_context_new()
Creates a new execution context.
INO_DEF void ino_context_free(ino_context ctx)
Destroys an execution context.
INO_DEF ino_variant ino_context_get_global_object(ino_context ctx)
Gets the global object in ctx.
INO_DEF ino_variant ino_variant_new_undefined(ino_context ctx)
Creates a new variant holding undefined.
INO_DEF ino_variant ino_variant_new_null(ino_context ctx)
Creates a new variant holding null.
INO_DEF ino_variant ino_variant_new_boolean(ino_context ctx,
bool value)
Creates a new variant holding the specified boolean value.
INO_DEF ino_variant ino_variant_new_string(ino_context ctx,
const uint16_t *value)
Creates a new variant holding the specified string.
INO_DEF ino_variant ino_variant_new_string_utf8(ino_context ctx,
const char *value)
Creates a new variant holding the specified string.
INO_DEF ino_variant ino_variant_new_number(ino_context ctx,
double value)
Creates a new variant holding the specified numeric value.
INO_DEF ino_variant ino_variant_new_object(ino_context ctx)
Creates a new variant holding a new object.
INO_DEF ino_variant_type ino_variant_get_type(ino_context ctx,
ino_variant variant)
Gets the type of value held by a variant.
INO_DEF bool ino_variant_to_boolean(ino_context ctx,
ino_variant variant)
Converts a variant to boolean and returns its value.
INO_DEF uint16_t * ino_variant_to_string(ino_context ctx,
ino_variant variant)
Converts a variant to string and returns a UTF-16 encoding malloc()-allocated copy.
INO_DEF char * ino_variant_to_string_utf8(ino_context ctx,
ino_variant variant)
Converts a variant to string and returns a UTF-8 encoding malloc()-allocated copy.
INO_DEF double ino_variant_to_number(ino_context ctx,
ino_variant variant)
Converts a variant to number and returns its value.
INO_DEF ino_variant ino_variant_object_get_property(ino_context ctx,
ino_variant object,
const uint16_t *name)
Gets a property from an object.
INO_DEF ino_variant ino_variant_object_get_property_utf8(ino_context ctx,
ino_variant object,
const char *name)
Gets a property from an object.
INO_DEF void ino_variant_object_set_property(ino_context ctx,
ino_variant object,
const uint16_t *name,
ino_variant value)
Sets a property on an object.
INO_DEF void ino_variant_object_set_property_utf8(ino_context ctx,
ino_variant object,
const char *name,
ino_variant value)
Sets a property on an object.
INO_DEF ino_variant ino_variant_object_add_method(ino_context ctx,
ino_variant object,
const uint16_t *name,
ino_method_cb cb)
Adds a natively implemented method to an object.
INO_DEF ino_variant ino_variant_object_add_method_utf8(ino_context ctx,
ino_variant object,
const char *name,
ino_method_cb cb)
Adds a natively implemented method to an object.
INO_DEF ino_variant ino_variant_object_call(ino_context ctx,
ino_variant object,
const ino_variant *args,
size_t n_args)
Call an object as a function.
INO_DEF void ino_variant_protect(ino_context ctx,
ino_variant variant)
Protects a variant from garbage collection.
INO_DEF void ino_variant_unprotect(ino_context ctx,
ino_variant variant)
Unprotects a variant from garbage collection.
INO_DEF ino_variant ino_eval(ino_context ctx,
const uint16_t *script)
Evaluates a string of JavaScript code.
INO_DEF ino_variant ino_eval_utf8(ino_context ctx,
const char *script)
Evaluates a string of JavaScript code.
Close