Keywords, variable naming rules, error/warning handling, exception structures, and interactive discovery (help, what). More...

Files
file	lang.hpp
	Language keywords, variable name validation, process environment, and diagnostics.
file	diagnostics.hpp
file	help.hpp
file	standard_library.hpp

Classes
struct	nk::runtime::LastWarn
	Snapshot of the most-recent warning. More...
class	nk::bundle::HelpLibrary
	Installs MATLAB-compatible help and documentation commands into the script Engine. More...
class	nk::StandardLibrary

Functions
void	nk::builtin::setenv (const std::string &name, const std::string &value="")
	Sets or clears an operating system environment variable (setenv(name, value)).
std::string	nk::builtin::getenv (const std::string &name)
	Reads an operating system environment variable as a C++ string (getenv(name)).
Value	nk::builtin::getenv (const Value &name, std::pmr::memory_resource *mr=nullptr)
	Reads an environment variable returning a character row Value (val = getenv(name)).
bool	nk::builtin::iskeyword (const std::string &name)
	Tests whether a string is a reserved MATLAB language keyword (iskeyword(s)).
const std::vector< std::string > &	nk::builtin::keywords ()
	Lists all reserved MATLAB keywords as a C++ vector.
Value	nk::builtin::iskeyword (Span< const Value > args, std::pmr::memory_resource *mr=nullptr)
	MATLAB-compatible overload for iskeyword.
bool	nk::builtin::isvarname (const std::string &name)
	Tests whether a string is a valid MATLAB variable name (isvarname(s)).
Value	nk::builtin::isvarname (const Value &name, std::pmr::memory_resource *mr=nullptr)
	MATLAB-compatible overload for isvarname.
Value	nk::builtin::isvarname (Span< const Value > args, std::pmr::memory_resource *mr=nullptr)
	Span-based MATLAB-compatible overload for isvarname.
void	nk::runtime::registerDiagnosticsRuntime (Engine &engine)
void	nk::runtime::error (Span< const Value > args)
	Throw an Error (error(...)).
void	nk::runtime::warning (Engine &engine, Span< const Value > args)
	Engine-stateful warning (warning(...)).
LastWarn	nk::runtime::lastwarnGet ()
	Read most-recent warning state ([msg, id] = lastwarn()).
void	nk::runtime::lastwarnSet (const std::string &msg, const std::string &id)
	Overwrite the most-recent warning state.
Value	nk::runtime::mexception (Span< const Value > args, std::pmr::memory_resource *mr=nullptr)
	Build an MException-like struct (me = MException(id, msg, args...)).
void	nk::runtime::rethrowStruct (const Value &me)
	Rethrow from an MException struct (rethrow(me) / throw(me)).
void	nk::runtime::assertCond (Span< const Value > args)
	Throw on a false condition (assert(...)).
void	nk::bundle::registerHelpLibrary (Engine &engine)
	Convenience alias to install help system into an engine.
std::string	nk::bundle::help (const std::string &query="")
	Formats help text or catalog index for given function or topic name (help query).
Value	nk::bundle::help (Span< const Value > args, std::pmr::memory_resource *mr=nullptr)
	MATLAB script engine wrapper for help.
std::vector< std::string >	nk::bundle::what (const std::string &category="elmat")
	Lists all functions in specified category (what category).
Value	nk::bundle::what (Span< const Value > args, std::pmr::memory_resource *mr=nullptr)
	MATLAB script engine wrapper for what.
std::vector< std::string >	nk::bundle::builtins (const std::string &category="")
	Lists all built-in functions registered in the system or specified category (builtins).
Value	nk::bundle::builtins (Span< const Value > args, std::pmr::memory_resource *mr=nullptr)
	MATLAB script engine wrapper for builtins.
std::vector< std::string >	nk::bundle::categories ()
	Lists all registered documentation categories (categories).
Value	nk::bundle::categories (std::pmr::memory_resource *mr)
	Returns all registered categories as a cell array of strings.
void	nk::installStandardLibrary (Engine &engine)
	Forwarder for backward compatibility.
std::unique_ptr< Engine >	nk::makeStandardEngine (std::pmr::memory_resource *mr=nullptr)

Detailed Description

Keywords, variable naming rules, error/warning handling, exception structures, and interactive discovery (help, what).

Function Documentation

◆ assertCond()

void nk::runtime::assertCond ( Span< const Value > args )

Throw on a false condition (assert(...)).

Forms:

assert(cond) → generic message on failure
assert(cond, msg, arg1, ...) → sprintf-formatted message
assert(cond, id, msg, arg1, ...) → identifier + formatted message (id must contain :)
assert(cond, MException-struct) → use struct fields

Returns normally if cond is non-zero.

Parameters

args	Arguments per the forms above.

Exceptions

Error Condition is false (form-dependent identifier / message).

◆ builtins() [1/2]

std::vector< std::string > nk::bundle::builtins ( const std::string & category = "" )

Lists all built-in functions registered in the system or specified category (builtins).

Parameters

category Category name (or empty string for all built-ins).

Returns: Vector of registered builtin function names.

See also: help, what, categories

◆ builtins() [2/2]

Value nk::bundle::builtins	(	Span< const Value >	args,
		std::pmr::memory_resource *	mr = nullptr )

MATLAB script engine wrapper for builtins.

Parameters

args	Category argument.
mr	Memory resource for output allocation.

Returns: Cell array of strings.

◆ categories() [1/2]

std::vector< std::string > nk::bundle::categories ( )

Lists all registered documentation categories (categories).

Returns: Vector of category identifiers (e.g. "elmat", "elfun", "signal", ...).

See also: help, what, builtins

◆ categories() [2/2]

Value nk::bundle::categories ( std::pmr::memory_resource * mr )

Returns all registered categories as a cell array of strings.

Parameters

mr	Memory resource for output allocation.

Returns: Cell array of category name strings.

◆ error()

void nk::runtime::error ( Span< const Value > args )

Throw an Error (error(...)).

Accepts any of:

error() → generic "Error"
error(msg) → msg literal
error(msg, arg1, ...) → sprintf-formatted message
error(id, msg, ...) → identifier + formatted message (id must contain :)
error(MException-struct) → rethrow identifier / message fields from the struct

Parameters

args	Arguments per the forms above.

Exceptions

Error Always (never returns).

◆ getenv() [1/2]

std::string nk::builtin::getenv ( const std::string & name )

Reads an operating system environment variable as a C++ string (getenv(name)).

Parameters

name	Environment variable name.

Returns: Variable value, or empty string "" if unset.

See also: setenv

◆ getenv() [2/2]

Value nk::builtin::getenv	(	const Value &	name,
		std::pmr::memory_resource *	mr = nullptr )

Reads an environment variable returning a character row Value (val = getenv(name)).

Parameters

name	Variable name as Value (character array or string scalar).
mr	Memory resource for allocations (nullptr for default).

Returns: Character array Value containing the variable value, or empty '' if unset.

See also: setenv

◆ help() [1/2]

std::string nk::bundle::help ( const std::string & query = "" )

Formats help text or catalog index for given function or topic name (help query).

Parameters

query Function, category, or empty string to display root catalog index.

Returns: Formatted help string.

See also: what, builtins, categories

◆ help() [2/2]

Value nk::bundle::help	(	Span< const Value >	args,
		std::pmr::memory_resource *	mr = nullptr )

MATLAB script engine wrapper for help.

Parameters

args	Command-line arguments.
mr	Memory resource for output allocation.

Returns: Help string value.

◆ installStandardLibrary()

void nk::installStandardLibrary ( Engine & engine )

inline

Forwarder for backward compatibility.

Definition at line 26 of file standard_library.hpp.

◆ iskeyword() [1/2]

bool nk::builtin::iskeyword ( const std::string & name )

Tests whether a string is a reserved MATLAB language keyword (iskeyword(s)).

Reserved keywords: break, case, catch, classdef, continue, else, elseif, end, for, function, global, if, otherwise, parfor, persistent, return, spmd, switch, try, while.

Parameters

name	String identifier to test.

Returns: true if name is a reserved keyword, false otherwise.

See also: isvarname, keywords

◆ iskeyword() [2/2]

Value nk::builtin::iskeyword	(	Span< const Value >	args,
		std::pmr::memory_resource *	mr = nullptr )

MATLAB-compatible overload for iskeyword.

If args is empty, returns a cell array of all keywords. If args has 1 argument, tests whether that name is a keyword.

Parameters

args	Optional (name) argument.
mr	Memory resource for allocations (nullptr for default).

Returns: LOGICAL scalar if query provided, or cell array of strings if called with no arguments.

See also: isvarname, keywords

◆ isvarname() [1/3]

bool nk::builtin::isvarname ( const std::string & name )

Tests whether a string is a valid MATLAB variable name (isvarname(s)).

A valid variable name begins with a letter, contains only alphanumeric characters and underscores, and is not a reserved keyword.

Parameters

name	String to validate.

Returns: true if name is a valid variable name, false otherwise.

See also: iskeyword

◆ isvarname() [2/3]

Value nk::builtin::isvarname	(	const Value &	name,
		std::pmr::memory_resource *	mr = nullptr )

MATLAB-compatible overload for isvarname.

Tests whether name (character array or string scalar) is a valid variable name. Non-text inputs safely return false.

Parameters

name	Target Value to test.
mr	Memory resource for allocations (nullptr for default).

Returns: LOGICAL scalar true if valid, false otherwise.

See also: iskeyword

◆ isvarname() [3/3]

Value nk::builtin::isvarname	(	Span< const Value >	args,
		std::pmr::memory_resource *	mr = nullptr )

Span-based MATLAB-compatible overload for isvarname.

Parameters

args	Span containing (name).
mr	Memory resource for allocations.

Returns: LOGICAL scalar Value.

Exceptions

std::runtime_error If args is empty.

◆ keywords()

const std::vector< std::string > & nk::builtin::keywords ( )

Lists all reserved MATLAB keywords as a C++ vector.

Returns: Vector of keyword strings.

See also: iskeyword

◆ lastwarnGet()

LastWarn nk::runtime::lastwarnGet ( )

Read most-recent warning state ([msg, id] = lastwarn()).

Storage is thread_local in the implementation TU, so concurrent engines on different threads each see their own last-warning.

Returns: Snapshot of the last warning(...) call.

See also: warning, lastwarnSet

◆ lastwarnSet()

void nk::runtime::lastwarnSet	(	const std::string &	msg,
		const std::string &	id )

Overwrite the most-recent warning state.

Used internally by warning; also exposed as the lastwarn(MSG, ID) setter form.

Parameters

msg	New message.
id	New identifier.

See also: lastwarnGet

◆ mexception()

Value nk::runtime::mexception	(	Span< const Value >	args,
		std::pmr::memory_resource *	mr = nullptr )

Build an MException-like struct (me = MException(id, msg, args...)).

Returns a struct with identifier and message fields. The message is formatted via sprintf-style argument substitution.

Parameters

args	(id, msg, arg1, ...). Throws on fewer than 2 args.
mr	Memory resource (nullptr → process default).

Returns: Struct with {identifier, message} fields.

Exceptions

Error Bad argument count (m:MException:nargin).

◆ registerHelpLibrary()

void nk::bundle::registerHelpLibrary ( Engine & engine )

inline

Convenience alias to install help system into an engine.

Parameters

engine Engine instance.

Definition at line 32 of file help.hpp.

◆ rethrowStruct()

void nk::runtime::rethrowStruct ( const Value & me )

Rethrow from an MException struct (rethrow(me) / throw(me)).

Extracts message + identifier from the struct and throws Error. Used by both rethrow() and throw() (they are aliases).

Parameters

me	MException-like struct.

Exceptions

Error Always; reconstructed from me.identifier / me.message.

◆ setenv()

void nk::builtin::setenv	(	const std::string &	name,
		const std::string &	value = "" )

Sets or clears an operating system environment variable (setenv(name, value)).

Sets the process environment variable name to value. If value is empty, the variable is removed from the process environment.

Parameters

name	Environment variable name (must not be empty or contain '=').
value	Target string value.

Exceptions

std::runtime_error If name is empty or contains '='.

See also: getenv

◆ warning()

void nk::runtime::warning	(	Engine &	engine,
		Span< const Value >	args )

Engine-stateful warning (warning(...)).

Same form-dispatch as error but does not throw — writes "Warning: ...\n" via engine.outputText() and updates the most-recent-warning state (see lastwarnGet).

Parameters

engine	Engine whose output stream receives the message.
args	Form-dispatched as for error.

◆ what() [1/2]

std::vector< std::string > nk::bundle::what ( const std::string & category = "elmat" )

Lists all functions in specified category (what category).

Parameters

category Category name (e.g. "elmat", "signal", "stats").

Returns: Vector of function names in category.

See also: help, builtins, categories

◆ what() [2/2]

Value nk::bundle::what	(	Span< const Value >	args,
		std::pmr::memory_resource *	mr = nullptr )

MATLAB script engine wrapper for what.

Parameters

args	Category argument.
mr	Memory resource for output allocation.

Returns: Cell array of strings.

Files

Classes

Functions

Detailed Description

Function Documentation

◆ assertCond()

◆ builtins() [1/2]

◆ builtins() [2/2]

◆ categories() [1/2]

◆ categories() [2/2]

◆ error()

◆ getenv() [1/2]

◆ getenv() [2/2]

◆ help() [1/2]

◆ help() [2/2]

◆ installStandardLibrary()

◆ iskeyword() [1/2]

◆ iskeyword() [2/2]

◆ isvarname() [1/3]

◆ isvarname() [2/3]

◆ isvarname() [3/3]

◆ keywords()

◆ lastwarnGet()

◆ lastwarnSet()

◆ mexception()

◆ registerHelpLibrary()

◆ rethrowStruct()

◆ setenv()

◆ warning()

◆ what() [1/2]

◆ what() [2/2]