std/internals

NAME

std/internals - Runtime internals helpers for advanced modules.

SYNOPSIS

  from std/internals import class_name, classof, object_slots, ansi_esc,
    ref_id, to_String, to_Number, to_Boolean, to_Regexp,
    to_Regexp_with_flags,
    make_instance, setprop, getprop, load_module;

  let obj_class := class_name(some_object);
  let obj_class_value := classof(some_object);
  let slots := object_slots(some_object);
  let id := ref_id(some_object);

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

This module provides low-level reflection helpers used by advanced pure-Zuzu modules (for example std/dump). These functions are not intended for general application code.

Special properties are lexical metadata, not symbol bindings. Calling setprop("paths", SomeClass) does not create an identifier named paths.

EXPORTS

Functions

class_name(value)
Parameters: value is any value. Returns: String or null. Returns the class name for object instances.
classof(value)
Parameters: value is any value. Returns: class value or null. Returns the class value for object and collection values.
object_slots(value)
Parameters: value is any value. Returns: Dict or null. Returns a dictionary of object slots, excluding private underscore-prefixed slots.
ansi_esc()
Parameters: none. Returns: String. Returns a one-character ANSI escape string.
ref_id(value)
Parameters: value is any value. Returns: String or null. Returns a stable reference id for reference-like values to support cycle detection.
to_String(value)
Parameters: value is any value. Returns: String. Coerces value using the same rules as string operators.
to_Number(value)
Parameters: value is any value. Returns: Number. Coerces value using the same rules as numeric operators.
to_Boolean(value)
Parameters: value is any value. Returns: Boolean. Coerces value using the same rules as logical operators and conditions.
to_Regexp(value)
Parameters: value is a regexp or pattern-like value. Returns: Regexp. Returns value unchanged when it is a regexp, otherwise coerces it to a string and compiles it as a regexp.
to_Regexp_with_flags(value, flags)
Parameters: value is a regexp or pattern-like value and flags is a string of regexp flags. Returns: Regexp. Coerces value to a pattern and compiles it using flags.
make_instance(klass, dict := null)
Parameters: klass is a class value and dict is an optional slot dictionary. Returns: object. Creates an instance without calling __build__.
load_module(module, symbol := null)
Parameters: module is a module name and symbol is an optional export name. Returns: Dict or value. Loads a module and returns all exports, or one named export.
setprop(key, value)
Parameters: key is a string and value is any value. Returns: null. Sets a lexically scoped runtime special property on the current frame.
getprop(key)
Parameters: key is a string. Returns: value or null. Returns a lexically scoped runtime special property via outward lexical lookup.

EXAMPLES

  from std/internals import setprop, getprop;
  from std/path/z import ZPath;

  setprop( "paths", ZPath );
  say( getprop( "paths" ) );   // Class object

  do {
    setprop( "paths", null );
    say( getprop( "paths" ) ); // null (shadowed in this block)
  };

  say( getprop( "paths" ) );   // ZPath (outer lexical value)

COPYRIGHT AND LICENCE

std/internals is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.

Module