CToon MATLAB Binding
v0.4.0 GitHub

API Reference

CToon MATLAB binding v0.4.0.

Package functions

Call these via the ctoon package namespace, e.g. ctoon.encode(v).

ctoon.decode

Decode a TOON-format string into a MATLAB value.

matlab
VALUE = DECODE(STR)

Parses the TOON character array STR and returns the corresponding
MATLAB representation.

Type mapping

matlab
null          -> []  (empty double)
bool          -> logical scalar
unsigned int  -> uint64 scalar
signed int    -> int64  scalar
real          -> double scalar
str           -> char array
array         -> cell array  (column, n×1)
object        -> struct      (scalar)

Example

matlab
v = ctoon.decode('{name:Alice,age:30,active:true}');
v.name    % -> 'Alice'
v.age     % -> uint64(30)
v.active  % -> true

v = ctoon.decode('[1,2,3]');
% -> {uint64(1); uint64(2); uint64(3)}

Errors

matlab
Throws ctoon:decodeError when STR is not valid TOON.

See also

:func:`ctoon.encode` :func:`ctoon.read` :func:`decode_json`

ctoon.dump

Encode a MATLAB value and write it to an open file (Python-style).

matlab
DUMP(VALUE, FID)

Serialises VALUE to TOON format and writes the result to the file
identified by FID.  FID must be a valid file identifier obtained from
FOPEN; the caller is responsible for opening and closing the file.

Example

matlab
fid = fopen('data.toon', 'w');
ctoon.dump(struct('x', 1.5), fid);
fclose(fid);

See also

:func:`ctoon.load` :func:`ctoon.dumps` :func:`ctoon.write`

ctoon.dumps

Encode a MATLAB value to a TOON-format string (alias for ENCODE).

matlab
STR = DUMPS(VALUE)

Serialises VALUE into the TOON format and returns the result as a
MATLAB character array.  This is a Python-style alias for ctoon.encode.

Example

matlab
s = ctoon.dumps(struct('x', 1.5));

See also

:func:`ctoon.encode` :func:`ctoon.loads` :func:`ctoon.dump`

ctoon.encode

Encode a MATLAB value to a TOON-format string.

matlab
STR = ENCODE(VALUE)

Serialises VALUE into the TOON binary-text format and returns the
result as a MATLAB character array.

Type mapping

matlab
[]            -> null
logical       -> bool
double scalar -> real
int64  scalar -> signed integer
uint64 scalar -> unsigned integer
char / string -> str
cell array    -> array
struct        -> object  (field names become keys)

Example

matlab
s = ctoon.encode(struct('name','Alice','age',30,'active',true));
% s ≈ '{name:Alice,age:30,active:true}'

s = ctoon.encode({1.0, 'hello', false});
% s ≈ '[1,hello,false]'

See also

:func:`ctoon.decode` :func:`ctoon.write` :func:`encode_json`

ctoon.load

Read TOON data from an open file and decode it (Python-style).

matlab
VALUE = LOAD(FID)

Reads all remaining content from the file identified by FID and
decodes it as a TOON-format document.  FID must be a valid file
identifier obtained from FOPEN; the caller is responsible for
opening and closing the file.

Example

matlab
fid = fopen('data.toon', 'r');
v = ctoon.load(fid);
fclose(fid);

See also

:func:`ctoon.dump` :func:`ctoon.loads` :func:`ctoon.read`

ctoon.loads

Decode a TOON-format string into a MATLAB value (alias for DECODE).

matlab
VALUE = LOADS(STR)

Parses the TOON character array STR and returns the corresponding
MATLAB representation.  This is a Python-style alias for ctoon.decode.

Example

matlab
v = ctoon.loads('{x:1.5}');

See also

:func:`ctoon.decode` :func:`ctoon.dumps` :func:`ctoon.load`

ctoon.read

Read and decode a TOON file into a MATLAB value.

matlab
VALUE = READ(FILEPATH)

Opens the file at FILEPATH, parses its TOON content, and returns the
decoded MATLAB value.  The file must be UTF-8 encoded.

FILEPATH may be an absolute path or a path relative to the current
working directory.

Type mapping: same as ctoon.decode.

Example

matlab
% Read a TOON config file
cfg = ctoon.read('config.toon');
cfg.host   % -> 'localhost'
cfg.port   % -> uint64(8080)

% Read from an absolute path
data = ctoon.read('/data/records.toon');

Errors

matlab
Throws ctoon:readError when the file cannot be opened or parsed.

See also

:func:`ctoon.write` :func:`ctoon.decode` :func:`ctoon.encode`

ctoon.version

Display or return CToon library version information.

See also

:func:`ctoon.encode` :func:`ctoon.decode` :func:`ctoon.read` :func:`ctoon.write`

ctoon.write

Encode a MATLAB value and write it to a TOON file.

matlab
WRITE(VALUE, FILEPATH)

Serialises VALUE to TOON format (see ctoon.encode) and writes the
result to the file at FILEPATH, creating or overwriting it.

FILEPATH may be an absolute path or a path relative to the current
working directory.  The file is written as UTF-8 text.

Type mapping: same as ctoon.encode.

Example

matlab
cfg.host    = 'localhost';
cfg.port    = uint64(8080);
cfg.debug   = false;
ctoon.write(cfg, 'config.toon');

% Round-trip check
v = ctoon.read('config.toon');
isequal(v.host, cfg.host)   % -> true

Errors

matlab
Throws ctoon:writeError when the file cannot be written.

See also

:func:`ctoon.read` :func:`ctoon.encode` :func:`ctoon.decode`

Helper scripts

Run these directly from the src/bindings/matlab directory.

ctoon_build

Compile MEX and export the CToon MATLAB package.

SYNTAX

matlab
ctoon_build(buildDir)
ctoon_build(buildDir, force)

DESCRIPTION

matlab
This script compiles the 'ctoon_mex.c' gateway (located in the root)
and bundles it with the MATLAB wrappers from the 'ctoon/' directory
into a functional '+ctoon' package inside the build directory.

INPUTS

matlab
buildDir - (string) Target directory for the build artifacts.
force    - (logical) If true, forces re-compilation of the MEX binary.

ctoon_clean

Remove build artifacts (package and MEX binaries).

SYNTAX

matlab
ctoon_clean()           % Cleans the current directory (+ctoon and MEX)
ctoon_clean(buildDir)   % Cleans a specific build directory

DESCRIPTION

matlab
- Clears MEX functions from memory.
- Removes the target directory from the MATLAB Path.
- Deletes the '+ctoon' package and MEX binaries.
- Does NOT modify configuration files (.buildtool/).

ctoon_install

Build and permanently install the CToon MEX binding.

matlab
ctoon_install()
ctoon_install(buildDir)
ctoon_install(buildDir, force)
ctoon_install(buildDir, force, verify)

Compiles ctoon_mex into buildDir (via ctoon_build) and permanently
adds that directory to the MATLAB search path (savepath).

Arguments

matlab
buildDir   directory for the MEX binary and .m wrappers.
If omitted, ctoon_build decides the default.
force      logical. true = recompile even if MEX already exists.
If omitted, ctoon_build decides the default.
verify     logical. true = quick smoke test after install.
Default: true.

Examples

matlab
ctoon_install                           % all defaults
ctoon_install('/opt/matlab/ctoon')      % custom dir
ctoon_install([], true)                 % force rebuild
ctoon_install([], [], false)            % skip verify

See also

:func:`ctoon_build` :func:`addpath` :func:`savepath`