common/print

Logging and pretty-print utilities for the Sigma RT script runtime.

This module provides lightweight console output helpers that integrate with the
Sigma RT Java bridge (com.sigma_rt.script.ScriptParameter). It offers plain
and color-capable printing, formatted error emission that aborts the running
script, indentation helpers for structured logs, and a recursive pretty-printer
for objects and arrays.

Core Features:

  • Thin wrappers around the engine's print for consistent spacing.
  • ANSI escape sequence awareness (prevents spurious spaces between color codes).
  • Indentation utility for building multi-line, hierarchical output.
  • printVar for readable, recursive object/array inspection.

Usage Overview:

  1. Import: var { print, printc, printErr, printVar } = require("sigma/common/print");
  2. Log plain messages with print("hello", "world") or colored segments with printc(...).
  3. Emit and abort on errors with printErr(msg, file) or printSysErr(msg).
  4. Build structured output using printIndent(level, text).
  5. Pretty-print objects with printVar(value) and send to the console with print(printVar(value)).

API Highlights:

  • print(...args): Space-joins arguments, aware of ANSI escape sequences.
  • printVar(value, level=0): Returns a formatted string representation of objects/arrays.

(inner) print(…args)

Output user-defined description information to the log console.
Inserts a single space between non-ANSI arguments to mimic typical console behavior.

Example
// Close an app and print the result
const device = Device.getMain();
if (device != null) {
  const ret = device.closeApp("com.tencent.qqmusic1");
  if (ret !== -1) {
    print("Congratulations, this API executes successfully.\nReturn value:", ret);
  } else {
    print("Sorry!", lastError(), "\nReturn value:", ret);
  }
} else {
  print("Failed to get the master device object");
}
Parameters:
* args <repeatable>

Values to print. Non-strings are stringified via String(arg).

(inner) printVar(message, levelopt) → {string}

Pretty-print (stringify) values for structured logging.

  • Strings are returned quoted.
  • Arrays and plain objects are expanded across multiple lines with indentation.
  • Non-objects are stringified via String(value).

Note: This function returns the formatted string; use print(printVar(obj))
to actually emit it to the console.

Example
// Fetch a contact and pretty-print it
const device = Device.getMain();
if (device != null) {
  const ret = device.contactGet(1);
  if (ret != null) {
    print("Congratulations, this API executes successfully.\nReturn value:");
    print(printVar(ret)); // Emit the pretty-printed object
  } else {
    print("Sorry!", lastError(), "\nReturn value:", ret);
  }
} else {
  print("Failed to get the master device object");
}
Parameters:
string | object | Array message

Value to format.
number level <optional>
 0

Current indentation level (for recursion).
Returns:
string

The formatted representation.

(inner) printf(format, …args) → {void}

Common Format Specifiers

Specifier Description Example Input Output
%s String "abc" abc
%c Character 'A' A
%b Boolean true true
%d Decimal integer 99 99
%x Hexadecimal integer 255 ff
%o Octal integer 63 77
%f Float 99.99 99.990000
%a Hex float 26.5 0x1.a00000p4
%e Scientific notation (float) 938000 9.380000e+05
%h Hash code β€” A05A5198
%% Literal percent sign β€” %
%n Line separator β€” (newline)
%tx Date/Time formatting new Date() (see table below)

%tx Date/Time Subformats:

Format Meaning Example Output
%tF ISO 8601 date 2024-01-01
%tD US date (MM/dd/yy) 01/01/24
%tT 24-hour time 15:04:05
%tr 12-hour time 03:04:05 PM
%tR 24-hour time (HH:mm) 15:04

πŸ“Œ Format Flags

Flag Description Example Result
+ Show sign for positive numbers %+d, 15 +15
- Left justify %-5d, 15 15
0 Zero-pad number %04d, 99 0099
space Pad with spaces % 4d, 99 99
, Thousands separator %,f, 9999.99 9,999.990000
( Wrap negative numbers in parentheses %(f, -99.99 (99.990000)
# Alternate formatting (e.g. 0x for hex) %#x, 99 0x63
< Reuse previous argument %f and %<.2f, 1.5 1.500000 and 1.50
$ Specify parameter position %2$s %1$d, 8, A A 8
See:
Example
// Boolean and integer formatting
printf("The result of 3>7 is: %b", 3 > 7);                   // Output: The result of 3>7 is: false
printf("Half of 100 is: %d", 100 / 2);                       // Output: Half of 100 is: 50

// Hexadecimal and octal formatting
printf("The hexadecimal number of 100 is: %x", 100);        // Output: The hexadecimal number of 100 is: 64
printf("The octal number of 100 is: %o", 100);              // Output: The octal number of 100 is: 144

// Multiple string arguments
printf("Fruits: %s, %s, %s", "Banana", "Orange", "Apple");  // Output: Fruits: Banana, Orange, Apple

// Argument index flag
printf("Use flag $: %1$d, %2$s", 99, "abc");                // Output: Use flag $: 99, abc

// Sign flags and new line
printf("Show the sign of positive and negative numbers: %+d and %d%n", 99, -99);
// Output:
// Show the sign of positive and negative numbers: +99 and -99
Parameters:
string format

Format string.
any args <repeatable>

Parameters referenced by the format specifier in the format string. The number of parameters is variable and can be 0.
Returns:
void