Hetu Script Language
Guide
Grammar
  • Dart APIs
  • Hetu APIs
  • VS Code extension
Github
  • English
  • 简体中文
  • English
Guide
Grammar
  • Dart APIs
  • Hetu APIs
  • VS Code extension
Github
  • English
  • 简体中文
  • English
  • Dart APIs
  • Hetu APIs

API for use in Hetu script

The preincluded value types are backed by real Dart objects, and most of their Dart SDK methods are bound in the script: Number, Integer, Float, Bool, String, List, Set, Map, Iterable, BigInt.

For instance, we can use the map API just like in Dart on an Iterable:

final result = range(10).map((value) => 'row: ${value}')

Many of these APIs also have JavaScript-style aliases (push, filter, padStart, Math.PI, Promise.resolve, ...). See the JavaScript Developers guide for the full alias table and the semantic differences to watch out for.

Type names use capitalized class names (Number, Integer, Float, Bool, String), with lowercase aliases kept for Dart-style code: number, integer, float, bool, string, plus num (= Number), int (= Integer), double (= Float), str (= String), Array (= List) and Promise (= Future).

Global functions and values

external function print(... args: any)
external function range(startOrStop: number, [stop: number, step: number]) -> Iterable
external function eval(code: string)
external function require(path: string)
external function help(id: string)
external function parseInt(source: string, [radix: integer?]) -> number
external function parseFloat(source: string) -> number
  • print: stringify and print one or several objects to standard output.
  • range: create an iterable of numbers, with an optional step.
  • eval: dynamically evaluate a string of Hetu source code.
  • require: dynamically import a source on the current source context, returns its namespace.
  • help: print the documentation of an identifier, e.g. help(require).
  • parseInt / parseFloat: parse numbers from strings (Dart tryParse semantics).

Also available in the global scope:

  • global / globalThis: the global namespace object.
  • NaN, Infinity: aliases of float.nan and float.infinity.
  • isNaN(x), isFinite(x): wrappers of the corresponding instance getters, without implicit conversion.
  • kHetuVersion: the language version string.

eval()

You can use eval within the script itself to evaluate a string, just like in JavaScript:

import 'package:hetu_script/hetu_script.dart';

void main() {
  final hetu = Hetu();
  hetu.init();
  final result = hetu.eval(r'''
      final meaning = eval("6 * 7")
      meaning
    ''');

  print(result);
}

struct Object

Hetu has a prototype-based struct object with literal syntax similar to JavaScript objects. All structs share the root prototype Object, which provides the following members:

struct Object {
  /// Create a struct from a Dart JSON map.
  external static function fromJSON(data) -> {}

  /// Assign source object's members to target.
  external static function assign(target, source)

  /// Assign source object's members to target only when the key is absent.
  external static function merge(target, source)

  /// Check membership, including prototypes.
  external function contains(key: string) -> bool

  /// Check membership of the struct's own fields only.
  external function containsKey(key: string) -> bool

  external get keys -> Iterable
  external get values -> Iterable
  external get isEmpty -> bool
  external get isNotEmpty -> bool
  external get length -> integer

  /// Remove a field by key.
  external function remove(key: string) -> any

  /// Deep copy this struct.
  external function clone() -> {}

  function hasOwnProperty(key: string) => this.containsKey(key)
  static function hasOwn(object, key: string) => object.containsKey(key)

  /// A list of MapEntry for the struct's own fields.
  static function entries(object)

  /// Create a struct from MapEntry items or [key, value] pairs.
  static function fromEntries(entries)

  function toJSON() -> Map => JSON.jsonify(this)
  function toString() -> string => JSON.stringify(this)

  /// Deep-copy or convert the argument into a struct.
  /// (Different from JavaScript's prototype-based Object.create.)
  function create(data)
}

Instance members can be called on any struct directly:

final obj = { a: 42 }
obj.contains('a') // true

Static methods are called through the prototype name:

final book = Object.fromJSON(data);

Math

The Math static class combines Dart's dart:math library, JavaScript-style aliases, and some Hetu-specific helpers.

Constants: e, pi, ln2, ln10, log2e, log10e, sqrt2, sqrt1_2, and the uppercase aliases E, PI, LN2, LN10, LOG2E, LOG10E, SQRT2, SQRT1_2.

abstract class Math {
  external static function random()
  external static function min(... values: number) -> number
  external static function max(... values: number) -> number
  external static function pow(x: number, exponent: number) -> number
  external static function sin(x: number) -> number
  external static function cos(x: number) -> number
  external static function tan(x: number) -> number
  external static function asin(x: number) -> number
  external static function acos(x: number) -> number
  external static function atan(x: number) -> number
  external static function atan2(y: number, x: number) -> number
  external static function sqrt(x: number) -> number
  external static function exp(x: number) -> number
  external static function log(x: number) -> number

  // Static wrappers of the number instance methods.
  static function abs(x: number)
  static function floor(x: number)
  static function ceil(x: number)
  static function round(x: number)
  static function trunc(x: number)
  static function sign(x: number)

  /// Convert [radians] to degrees, and back.
  external static function degrees(radians)
  external static function radians(degrees)

  // Hetu-specific helpers:
  external static function radiusToSigma(radius: float) -> float

  /// Box–Muller transform for normally distributed random numbers.
  external static function gaussianNoise(mean: float, standardDeviation: float, {min: float, max: float, randomGenerator}) -> float

  /// Noise generation provided by the fast_noise package.
  /// Noise types: perlin, perlinFractal, cubic, cubicFractal
  external static function noise2d(width, height, {seed, noiseType = 'cubic', frequency = 0.01})

  /// Angle from start to end, in degrees / radians.
  external static function angle(startx, starty, endx, endy)
  external static function aangle(startx, starty, endx, endy)

  /// Map input to an output between 0.0 and 1.0 around a target value.
  external static function gradualValue(input, target, { power = 0.5 })
}

min / max accept any number of arguments (variadic): null values are ignored, an empty call returns Infinity / -Infinity, and NaN propagates.

Random

The binding of Dart's Random object, with some extra helpers such as random colors:

external class Random {
  constructor ([seed: integer])

  function nextBool() -> bool

  /// Biased bool: the closer input is to target, the more likely true.
  function nextBoolBiased(input: float, target: float) -> bool

  /// Random integer with a higher / lower probability near the target.
  function nearInt(max: integer, {bias: float = 1.0}) -> integer
  function distantInt(max: integer, {bias: float = 1.0}) -> integer

  function nextInt(max: integer) -> integer
  function nextDouble() -> float

  function nextColorHex({hasAlpha: bool = false}) -> string
  function nextBrightColorHex({hasAlpha: bool = false}) -> string

  function nextIterable(list: Iterable) -> any
  function shuffle(list: Iterable) -> Iterable
}

JSON

external abstract class JSON {
  /// Parse a JSON string into Dart data (Map / List / primitives).
  static function parse(object)

  /// Convert a value (including structs) into JSON-ready data.
  static function jsonify(object)

  /// Serialize a value into a JSON string.
  static function stringify(object)

  /// Deep copy a value.
  static function deepcopy(object)
}

stringify does not support JavaScript's replacer / space parameters. jsonify and deepcopy are Hetu extensions.

console

external abstract class console {
  static function log(... args: any)
  static function debug(... args: any)
  static function info(... args: any)
  static function warn(... args: any)
  static function warning(... args: any) // alias of warn
  static function error(... args: any)

  static function time([label: string])
  static function timeLog([label: string])
  static function timeEnd([label: string])
}

time starts a stopwatch with an optional label, timeLog prints the elapsed milliseconds, and timeEnd prints and stops it.

Future / Promise

Promise is a type alias of Future. JavaScript-style names are provided alongside the Dart names:

external class Future {
  constructor (func: function)

  static function wait(futures: List) -> Future
  static function all(futures: List) -> Future      // alias of wait
  static function value(possibleFuture) -> Future
  static function resolve(possibleFuture) -> Future // alias of value
  static function error(error) -> Future
  static function reject(error) -> Future           // alias of error
  static function delayed(seconds: float, [computation: function]) -> Future

  function then(func: (value) -> any) -> Future
  function catchError(func: (error) -> any) -> Future
  function catch(func: (error) -> any) -> Future    // alias of catchError
  function whenComplete(func: () -> any) -> Future
  function finally(func: () -> any) -> Future       // alias of whenComplete
}

crypto

Utility methods for ids and checksums:

external abstract class crypto {
  /// A random UUID string.
  static function randomUUID() -> string

  /// A random id with optional time component.
  static function randomUID({length = 4, withTime = false}) -> string

  /// A random numeric id with optional time component.
  static function randomNID({length = 8, withTime = false}) -> string

  static function crcString(data: string, [crc: string = 0]) -> string
  static function crcInt(data: string, [crc: string = 0]) -> integer
}
Last Updated: 11/4/26, 11:28 AM
Contributors: hythloday@live.com, 邵燃, unknown, Ran Shao, chengfubeiming
Prev
Dart APIs