# 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

ino | Version: 0.4.0, API: 0.0.0.
Global Declaration Macros | These macros are meant to be used to delimit declarations in public header files.
INO_BEGIN_C_DECLS | Delimits the beginning of public declarations.
INO_END_C_DECLS | Delimits the end of public declarations.
Symbol Declaration Macros | These macros are meant to be used for SINGLE symbol declarations (variables or functions) by prepending them to such declarations.
INO_IMPORT | Specifies that a symbol is imported from a library.
INO_EXPORT | Specifies that a symbol is to be exported.
INO_PUBLIC | Specifies that a symbol is publicly visible.
INO_PRIVATE | Specifies that a symbol has hidden visibility.
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.
Types |
ino_context | Execution context.
ino_variant | Variant.
ino_method_cb | Native 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_UNDEFINED | undefined value.
INO_VARIANT_TYPE_NULL | null value.
INO_VARIANT_TYPE_BOOLEAN | Boolean value.
INO_VARIANT_TYPE_STRING | String.
INO_VARIANT_TYPE_NUMBER | Numeric value.
INO_VARIANT_TYPE_OBJECT | Object.

### 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

ctx | Execution context.
args | Array of arguments passed to the method.
n_args | Number 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

ctx | Execution 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

ctx | Execution 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

ctx | Execution 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

ctx | Execution context.
value | The 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

ctx | Execution context.
value | UTF-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

ctx | Execution context.
value | UTF-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

ctx | Execution context.
value | The 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

ctx | Execution 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

ctx | Execution context.
variant | Variant.

#### 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

ctx | Execution context.
variant | Variant.

#### 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

ctx | Execution context.
variant | Variant.

#### 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

ctx | Execution context.
variant | Variant.

#### 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

ctx | Execution context.
variant | Variant.

#### 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

ctx | Execution context.
object | Object variant.
name | UTF-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

ctx | Execution context.
object | Object variant.
name | UTF-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

ctx | Execution context.
object | Object variant.
name | UTF-16 encoded property name.
value | Variant 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

ctx | Execution context.
object | Object variant.
name | UTF-8 encoded property name.
value | Variant 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

ctx | Execution context.
object | Object variant.
name | UTF-16 encoded method name.
cb | Callback 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

ctx | Execution context.
object | Object variant.
name | UTF-8 encoded method name.
cb | Callback 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

ctx | Execution context.
object | Object variant.
args | Array of arguments.
n_args | Number 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

ctx | Execution context.
variant | Variant.

### ino_variant_unprotect()

> INO_DEF void ino_variant_unprotect( | ino_context | ctx,
> | ino_variant | variant | )

Unprotects a variant from garbage collection.

#### Parameters

ctx | Execution context.
variant | Variant.

### ino_eval()

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

Evaluates a string of JavaScript code.

#### Parameters

ctx | Execution context.
script | UTF-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

ctx | Execution context.
script | UTF-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