hvml-spec-predefined-variables-v1.0-zh.md

# HVML 预定义变量

Subject: HVML Predefined Variables  
Version: 1.0-RC4  
Author: Vincent Wei  
Category: Language Specification  
Creation Date: Nov. 1, 2021  
Last Modified Date: July 1, 2022  
Status: Release Candidate  
Release Name: 硕鼠  
Language: Chinese

*Copyright Notice*

版权所有 © 2021, 2022 魏永明  
版权所有 © 2021, 2022 北京飞漫软件技术有限公司  
保留所有权利

此文档不受 HVML 相关软件开源许可证的管辖。

版权所有人公开此文档的目标，用于向开发者解释 HVML 相关设计原理或者相关规范。在未获得版权所有人书面许可之前，任何人不得复制或者分发本文档的全部或部分内容，或利用本文档描绘的技术思路申请专利、撰写学术论文等。

本文提及的版权所有人相关注册商标或商标之详细列表，请查阅文档末尾。

**目录**

[//]:# (START OF TOC)

- [1) 介绍](#1-介绍)
   + [1.1) 规范及术语](#11-规范及术语)
   + [1.2) 二进制格式表示法](#12-二进制格式表示法)
   + [1.3) 格式化修饰符](#13-格式化修饰符)
   + [1.4) 撰写要求](#14-撰写要求)
- [2) 非动态变量](#2-非动态变量)
   + [2.1) `TIMERS`](#21-timers)
      * [2.1.1) 批量新增定时器](#211-批量新增定时器)
      * [2.1.2) 新增一个定时器](#212-新增一个定时器)
      * [2.1.3) 移除一个定时器](#213-移除一个定时器)
      * [2.1.4) 修改特定定时器的属性](#214-修改特定定时器的属性)
   + [2.2) `REQUEST`](#22-request)
- [3) 必要动态变量](#3-必要动态变量)
   + [3.1) `SYSTEM`](#31-system)
      * [3.1.1) `const` 方法](#311-const-方法)
      * [3.1.2) `uname` 方法](#312-uname-方法)
      * [3.1.3) `uname_prt` 方法](#313-uname_prt-方法)
      * [3.1.4) `locale` 方法](#314-locale-方法)
      * [3.1.5) `time` 方法](#315-time-方法)
      * [3.1.6) `time_us` 方法](#316-time_us-方法)
      * [3.1.7) `sleep` 方法](#317-sleep-方法)
      * [3.1.8) `timezone` 方法](#318-timezone-方法)
      * [3.1.9) `cwd` 方法](#319-cwd-方法)
      * [3.1.10) `env` 方法](#3110-env-方法)
      * [3.1.11) `random_sequence` 方法](#3111-random_sequence-方法)
      * [3.1.12) `random` 方法](#3112-random-方法)
   + [3.2) `SESSION`](#32-session)
      * [3.2.1) `app` 方法](#321-app-方法)
      * [3.2.2) `runner` 方法](#322-runner-方法)
      * [3.2.3) `myObj` 静态属性](#323-myobj-静态属性)
      * [3.2.4) `user` 方法](#324-user-方法)
   + [3.3) `DATETIME`](#33-datetime)
      * [3.3.1) `time_prt` 方法](#331-time_prt-方法)
      * [3.3.2) `utctime` 方法](#332-utctime-方法)
      * [3.3.3) `localtime` 方法](#333-localtime-方法)
      * [3.3.4) `mktime` 方法](#334-mktime-方法)
      * [3.3.5) `fmttime` 方法](#335-fmttime-方法)
      * [3.3.6) `fmtbdtime` 方法](#336-fmtbdtime-方法)
   + [3.4) `HVML`](#34-hvml)
      * [3.4.1) `target` 方法](#341-target-方法)
      * [3.4.2) `base` 方法](#342-base-方法)
      * [3.4.3) `max_iteration_count` 方法](#343-max_iteration_count-方法)
      * [3.4.4) `max_recursion_depth` 方法](#344-max_recursion_depth-方法)
      * [3.4.5) `max_embedded_levels` 方法](#345-max_embedded_levels-方法)
      * [3.4.6) `timeout` 方法](#346-timeout-方法)
      * [3.4.7) `cid` 方法](#347-cid-方法)
   + [3.5) `DOC`](#35-doc)
      * [3.5.1) `doctype` 方法](#351-doctype-方法)
      * [3.5.2) `query` 方法](#352-query-方法)
   + [3.6) `EJSON`](#36-ejson)
      * [3.6.1) `type` 方法](#361-type-方法)
      * [3.6.2) `count` 方法](#362-count-方法)
      * [3.6.3) `numberify` 方法](#363-numberify-方法)
      * [3.6.4) `booleanize` 方法](#364-booleanize-方法)
      * [3.6.5) `stringify` 方法](#365-stringify-方法)
      * [3.6.6) `serialize` 方法](#366-serialize-方法)
      * [3.6.7) `sort` 方法](#367-sort-方法)
      * [3.6.8) `shuffle` 方法](#368-shuffle-方法)
      * [3.6.9) `compare` 方法](#369-compare-方法)
      * [3.6.10) `parse` 方法](#3610-parse-方法)
      * [3.6.11) `isequal` 方法](#3611-isequal-方法)
      * [3.6.12) `fetchstr` 方法](#3612-fetchstr-方法)
      * [3.6.13) `fetchreal` 方法](#3613-fetchreal-方法)
      * [3.6.14) `crc32` 方法](#3614-crc32-方法)
      * [3.6.15) `md5` 方法](#3615-md5-方法)
      * [3.6.16) `sha1` 方法](#3616-sha1-方法)
      * [3.6.17) `pack` 方法](#3617-pack-方法)
      * [3.6.18) `unpack` 方法](#3618-unpack-方法)
      * [3.6.19) `bin2hex` 方法](#3619-bin2hex-方法)
      * [3.6.20) `hex2bin` 方法](#3620-hex2bin-方法)
      * [3.6.21) `base64_encode` 方法](#3621-base64_encode-方法)
      * [3.6.22) `base64_decode` 方法](#3622-base64_decode-方法)
   + [3.7) `L`](#37-l)
      * [3.7.1) `not` 方法](#371-not-方法)
      * [3.7.2) `and` 方法](#372-and-方法)
      * [3.7.3) `or` 方法](#373-or-方法)
      * [3.7.4) `xor` 方法](#374-xor-方法)
      * [3.7.5) `eq` 方法](#375-eq-方法)
      * [3.7.6) `ne` 方法](#376-ne-方法)
      * [3.7.7) `gt` 方法](#377-gt-方法)
      * [3.7.8) `ge` 方法](#378-ge-方法)
      * [3.7.9) `lt` 方法](#379-lt-方法)
      * [3.7.10) `le` 方法](#3710-le-方法)
      * [3.7.11) `streq` 方法](#3711-streq-方法)
      * [3.7.12) `strne` 方法](#3712-strne-方法)
      * [3.7.13) `strgt` 方法](#3713-strgt-方法)
      * [3.7.14) `strge` 方法](#3714-strge-方法)
      * [3.7.15) `strlt` 方法](#3715-strlt-方法)
      * [3.7.16) `strle` 方法](#3716-strle-方法)
      * [3.7.17) `eval` 方法](#3717-eval-方法)
   + [3.8) `T`](#38-t)
      * [3.8.1) `map` 静态属性](#381-map-静态属性)
      * [3.8.2) `get` 方法](#382-get-方法)
   + [3.9) `STR`](#39-str)
      * [3.9.1) `contains` 方法](#391-contains-方法)
      * [3.9.2) `starts_with` 方法](#392-starts_with-方法)
      * [3.9.3) `ends_with` 方法](#393-ends_with-方法)
      * [3.9.4) `explode` 方法](#394-explode-方法)
      * [3.9.5) `implode` 方法](#395-implode-方法)
      * [3.9.6) `shuffle` 方法](#396-shuffle-方法)
      * [3.9.7) `replace` 方法](#397-replace-方法)
      * [3.9.8) `format_c` 方法](#398-format_c-方法)
      * [3.9.9) `scan_c` 方法](#399-scan_c-方法)
      * [3.9.10) `format_p` 方法](#3910-format_p-方法)
      * [3.9.11) `scan_p` 方法](#3911-scan_p-方法)
      * [3.9.12) `join` 方法](#3912-join-方法)
      * [3.9.13) `nr_chars` 方法](#3913-nr_chars-方法)
      * [3.9.14) `tolower` 方法](#3914-tolower-方法)
      * [3.9.15) `toupper` 方法](#3915-toupper-方法)
      * [3.9.16) `substr` 方法](#3916-substr-方法)
      * [3.9.17) `substr_compare` 方法](#3917-substr_compare-方法)
      * [3.9.18) `substr_count` 方法](#3918-substr_count-方法)
      * [3.9.19) `substr_replace` 方法](#3919-substr_replace-方法)
      * [3.9.20) `strstr` 方法](#3920-strstr-方法)
      * [3.9.21) `strpos` 方法](#3921-strpos-方法)
      * [3.9.22) `strpbrk` 方法](#3922-strpbrk-方法)
      * [3.9.23) `split` 方法](#3923-split-方法)
      * [3.9.24) `chunk_split` 方法](#3924-chunk_split-方法)
      * [3.9.25) `trim` 方法](#3925-trim-方法)
      * [3.9.26) `pad` 方法](#3926-pad-方法)
      * [3.9.27) `repeat` 方法](#3927-repeat-方法)
      * [3.9.28) `reverse` 方法](#3928-reverse-方法)
      * [3.9.29) `tokenize` 方法](#3929-tokenize-方法)
      * [3.9.30) `translate` 方法](#3930-translate-方法)
      * [3.9.31) `htmlentities_encode` 方法](#3931-htmlentities_encode-方法)
      * [3.9.32) `htmlentities_decode` 方法](#3932-htmlentities_decode-方法)
      * [3.9.33) `nl2br` 方法](#3933-nl2br-方法)
      * [3.9.34) `rot13` 方法](#3934-rot13-方法)
      * [3.9.35) `count_chars` 方法](#3935-count_chars-方法)
      * [3.9.36) `count_bytes` 方法](#3936-count_bytes-方法)
   + [3.10) `URL`](#310-url)
      * [3.10.1) `encode` 方法](#3101-encode-方法)
      * [3.10.2) `decode` 方法](#3102-decode-方法)
      * [3.10.3) `build_query` 方法](#3103-build_query-方法)
      * [3.10.4) `parse_query` 方法](#3104-parse_query-方法)
      * [3.10.5) `parse` 方法](#3105-parse-方法)
      * [3.10.6) `assemble` 方法](#3106-assemble-方法)
   + [3.11) `STREAM`](#311-stream)
      * [3.11.1) `open` 方法](#3111-open-方法)
      * [3.11.2) `close` 方法](#3112-close-方法)
      * [3.11.3) `stdin` 静态属性](#3113-stdin-静态属性)
      * [3.11.4) `stdout` 静态属性](#3114-stdout-静态属性)
      * [3.11.5) `stderr` 静态属性](#3115-stderr-静态属性)
      * [3.11.6) 流实体的 `readstruct` 方法](#3116-流实体的-readstruct-方法)
      * [3.11.7) 流实体的 `writestruct` 方法](#3117-流实体的-writestruct-方法)
      * [3.11.8) 流实体的 `readlines` 方法](#3118-流实体的-readlines-方法)
      * [3.11.9) 流实体的 `writelines` 方法](#3119-流实体的-writelines-方法)
      * [3.11.10) 流实体的 `readbytes` 方法](#31110-流实体的-readbytes-方法)
      * [3.11.11) 流实体的 `writebytes` 方法](#31111-流实体的-writebytes-方法)
      * [3.11.12) 流实体的 `seek` 方法](#31112-流实体的-seek-方法)
      * [3.11.13) `pipe` 流实体](#31113-pipe-流实体)
- [4) 可选动态变量](#4-可选动态变量)
   + [4.1) `MATH`](#41-math)
      * [4.1.1) `pi` 方法](#411-pi-方法)
      * [4.1.2) `e` 方法](#412-e-方法)
      * [4.1.3) `const` 方法](#413-const-方法)
      * [4.1.4) `add` 方法](#414-add-方法)
      * [4.1.5) `sub` 方法](#415-sub-方法)
      * [4.1.6) `mul` 方法](#416-mul-方法)
      * [4.1.7) `div` 方法](#417-div-方法)
      * [4.1.8) `eval` 和 `eval_l` 方法](#418-eval-和-eval_l-方法)
      * [4.1.9) `sin` 和 `sin_l` 方法](#419-sin-和-sin_l-方法)
      * [4.1.10) `cos` 和 `cos_l` 方法](#4110-cos-和-cos_l-方法)
      * [4.1.11) `tan` 和 `tan_l` 方法](#4111-tan-和-tan_l-方法)
      * [4.1.12) `sinh` 和 `sinh_l` 方法](#4112-sinh-和-sinh_l-方法)
      * [4.1.13) `cosh` 和 `cosh_l` 方法](#4113-cosh-和-cosh_l-方法)
      * [4.1.14) `tanh` 和 `tanh_l` 方法](#4114-tanh-和-tanh_l-方法)
      * [4.1.15) `asin` 和 `asin_l` 方法](#4115-asin-和-asin_l-方法)
      * [4.1.16) `acos` 和 `acos_l` 方法](#4116-acos-和-acos_l-方法)
      * [4.1.17) `atan` 和 `atan_l` 方法](#4117-atan-和-atan_l-方法)
      * [4.1.18) `asinh` 和 `asinh_l` 方法](#4118-asinh-和-asinh_l-方法)
      * [4.1.19) `acosh` 和 `acosh_l` 方法](#4119-acosh-和-acosh_l-方法)
      * [4.1.20) `atanh` 和 `atanh_l` 方法](#4120-atanh-和-atanh_l-方法)
      * [4.1.21) `fmod` 和 `fmod_l` 方法](#4121-fmod-和-fmod_l-方法)
      * [4.1.22) `fabs` 方法](#4122-fabs-方法)
      * [4.1.23) `log` 和 `log_l` 方法](#4123-log-和-log_l-方法)
      * [4.1.24) `log10` 和 `log10_l` 方法](#4124-log10-和-log10_l-方法)
      * [4.1.25) `pow` 和 `pow_l` 方法](#4125-pow-和-pow_l-方法)
      * [4.1.26) `exp` 和 `exp_l` 方法](#4126-exp-和-exp_l-方法)
      * [4.1.27) `floor` 和 `floor_l` 方法](#4127-floor-和-floor_l-方法)
      * [4.1.28) `ceil` 和 `ceil_l` 方法](#4128-ceil-和-ceil_l-方法)
      * [4.1.29) `sqrt` 和 `sqrt_l` 方法](#4129-sqrt-和-sqrt_l-方法)
   + [4.2) `FS`](#42-fs)
      * [4.2.1) `list` 方法](#421-list-方法)
      * [4.2.2) `list_prt` 方法](#422-list_prt-方法)
      * [4.2.3) `basename` 方法](#423-basename-方法)
      * [4.2.4) `chgrp` 方法](#424-chgrp-方法)
      * [4.2.5) `chmod` 方法](#425-chmod-方法)
      * [4.2.6) `chown` 方法](#426-chown-方法)
      * [4.2.7) `copy` 方法](#427-copy-方法)
      * [4.2.8) `dirname` 方法](#428-dirname-方法)
      * [4.2.9) `disk_usage` 方法](#429-disk_usage-方法)
      * [4.2.10) `file_exists` 方法](#4210-file_exists-方法)
      * [4.2.11) `file_is` 方法](#4211-file_is-方法)
      * [4.2.12) `lchgrp` 方法](#4212-lchgrp-方法)
      * [4.2.13) `lchown` 方法](#4213-lchown-方法)
      * [4.2.14) `linkinfo` 方法](#4214-linkinfo-方法)
      * [4.2.15) `lstat` 方法](#4215-lstat-方法)
      * [4.2.16) `link` 方法](#4216-link-方法)
      * [4.2.17) `mkdir` 方法](#4217-mkdir-方法)
      * [4.2.18) `pathinfo` 方法](#4218-pathinfo-方法)
      * [4.2.19) `readlink` 方法](#4219-readlink-方法)
      * [4.2.20) `realpath` 方法](#4220-realpath-方法)
      * [4.2.21) `rename` 方法](#4221-rename-方法)
      * [4.2.22) `rmdir` 方法](#4222-rmdir-方法)
      * [4.2.23) `stat` 方法](#4223-stat-方法)
      * [4.2.24) `symlink` 方法](#4224-symlink-方法)
      * [4.2.25) `tempname` 方法](#4225-tempname-方法)
      * [4.2.26) `touch` 方法](#4226-touch-方法)
      * [4.2.27) `umask` 方法](#4227-umask-方法)
      * [4.2.28) `unlink` 方法](#4228-unlink-方法)
      * [4.2.29) `file_contents` 方法](#4229-file_contents-方法)
      * [4.2.30) `opendir` 方法](#4230-opendir-方法)
      * [4.2.31) `closedir` 方法](#4231-closedir-方法)
      * [4.2.32) 目录流实体的 `read` 方法](#4232-目录流实体的-read-方法)
      * [4.2.33) 目录流实体的 `rewind` 方法](#4233-目录流实体的-rewind-方法)
   + [4.3) `FILE`](#43-file)
      * [4.3.1) 文本文件](#431-文本文件)
         - [4.3.1.1) `txt.head` 方法](#4311-txthead-方法)
         - [4.3.1.2) `txt.tail` 方法](#4312-txttail-方法)
      * [4.3.2) 二进制文件](#432-二进制文件)
         - [4.3.2.1) `bin.head` 方法](#4321-binhead-方法)
         - [4.3.2.2) `bin.tail` 方法](#4322-bintail-方法)
- [附录](#附录)
   + [附.1) 修订记录](#附1-修订记录)
      * [RC4) 220701](#rc4-220701)
      * [RC3) 220601](#rc3-220601)
      * [RC2) 220501](#rc2-220501)
      * [RC1) 220401](#rc1-220401)
      * [BRC) 220201](#brc-220201)
   + [附.2) 贡献者榜单](#附2-贡献者榜单)
   + [附.3) 废弃的内容](#附3-废弃的内容)
      * [`const_obj` 静态属性](#const_obj-静态属性)
   + [附.3) 商标声明](#附3-商标声明)

[//]:# (END OF TOC)

## 1) 介绍

本文档是 HVML 规范的一部分，用于详细定义 HVML 解释器必须支持或者可选支持的预定义变量。

### 1.1) 规范及术语

本文档遵循的技术规范或术语如下所列：

- HVML（Hybrid Virtual Markup Language），是[魏永明](https://github.com/VincentWei)提出的一种数据驱动的可编程标记语言。[HVML 规范](hvml-spec-v1.0-zh.md) 的如下部分和本文档相关：
  1. 2.1) 术语及基本原理
  1. 2.2) 规则、表达式及方法的描述语法
- 解释器（interpreter），指解析并运行 HVML 程序的计算机软件。
- 渲染器（renderer），指渲染 HVML 协程生成的目标文档并和用户交互的计算机软件。
- 会话（session），指一个解释器实例的上下文信息；每个解释器实例对应一个 HVML 会话，每个 HVML 会话运行多个 HVML 协程，对应渲染器中的多个窗口。
- 静态属性（static property），指一个对象上键值为普通数据的属性，其键值不是动态值。我们通常使用小写开头的驼峰命名法命名这类属性，如 `myObj`。
- 方法（method），指一个对象上键值为动态值的属性。我们通常使用下划线连接的全小写命名法，如 `starts_with`。
- 获取器（getter），指一个方法的获取器。调用获取器返回该方法的动态属性值。
- 设置器（setter），指一个方法的设置器。调用特定方法的设置器，将完成对应属性的设置工作。

按是否含有动态对象划分，HVML 预定义变量可分为：

1. 非动态变量，即变量对应的数据不提供动态方法。所有本规范定义的非动态变量都是内置（built-in）且必要的（required）。
1. 动态变量，即变量对应的数据提供动态方法。动态变量又分为必要（required）动态变量及可选（optional）动态变量。通常，动态变量可设计为可加载的（loadable）共享库或者模块。解释器应根据本文档的要求将动态变量实现为内置的或可加载的；可选动态变量是否实现为可加载的，由解释器决定。

按变量对应数据的作用域，可分为：

1. 会话级变量。指该变量对应的数据对当前解释器实例中的所有 HVML 协程可见。也就是说，同一会话中的不同协程对应同一个数据副本。
1. 协程级变量。指该变量对应的数据仅对当前解释器实例中的单个 HVML 协程可见。也就是说，不同的 HVML 协程有一个自己的数据副本。

需要注意，会话级变量的实现应考虑多线程（当解释器以进程方式运行，每个解释器实例对应一个独立线程）情形下的线程安全和可重入性。

**约定**  
解释器可自行实现全局变量，作为约定，解释器自行实现的全局变量，其名称应以 ASCII U+005F LOW LINE（`_`）打头，使用全大写字母并添加解释器前缀。如 `_PURC_VAR`。而一般的变量，使用全小写字母。

### 1.2) 二进制格式表示法

为配合流实体要求的流式读写方法（`readstruct`、`writestruct`）以及字节序列的数值化，我们定义了一种二进制格式表示法。

我们用一个字符串表示一个二进制结构中的各个构成部分，多个构成部分之间使用空白字符（空格、制表符、换行符等）分隔，每个构成部分使用一个类型字符串表示其类型，如果是大于一个字节的整数或浮点数，其后紧跟可选的 `le` 或者 `be` 表示小头（little endian）或者大头（big endian）。

如，`i32le s128 f64`，表示一个结构，其中前 4 个字节是一个 32 位整数，小头存储，紧接着是一个 128 字节的字符串，最后 8 字节是一个 64 位浮点数。该结构一共 140 字节。

在对字节序列执行数值化操作时，我们通过单个关键词来指定字节序列的二进制格式，比如 `i32le` 表示小头存储的 32 位有符号整数。

下表给出了本表示法支持的各种结构构成部分之类型标记：

| 类型               |  表示方法                    | 对应的 HVML 数据类型         |
| ----------------   |  --------                    | ---------------------------- |
| 1 字节整数         |  `i8[:<QUANTITY>]`           | longint, longint 数组    |
| 2 字节整数         |  `i16[le/be][:<QUANTITY>]`   | longint, longint 数组    |
| 4 字节整数         |  `i32[le/be][:<QUANTITY>]`   | longint, longint 数组    |
| 8 字节整数         |  `i64[le/be][:<QUANTITY>]`   | longint, longint 数组    |
| 1 字节无符号整数   |  `u8[:<QUANTITY>]`           | ulongint, ulongint 数组  |
| 2 字节无符号整数   |  `u16[le/be][:<QUANTITY>]`   | ulongint, ulongint 数组  |
| 4 字节无符号整数   |  `u32[le/be][:<QUANTITY>]`   | ulongint, ulongint 数组  |
| 8 字节无符号整数   |  `u64[le/be][:<QUANTITY>]`   | ulongint, ulongint 数组  |
| 2 字节浮点型       |  `f16[le/be][:<QUANTITY>]`   | number, number 数组      |
| 4 字节浮点型       |  `f32[le/be][:<QUANTITY>]`   | number, number 数组      |
| 8 字节浮点型       |  `f64[le/be][:<QUANTITY>]`   | number, number 数组      |
| 12 字节浮点型      |  `f96[le/be][:<QUANTITY>]`   | longdouble, longdouble 数组 |
| 16 字节长双精度    |  `f128[le/be][:<QUANTITY>]`  | longdouble, longdouble 数组 |
| 字节序列           |  `bytes:<SIZE>`              | bsequence；SIZE 指定字节数量。 |
| UTF-8编码的字符串  |  `utf8[:<SIZE>]`             | string；SIZE 可选：指定字节数量，未指定时，到空字符（0x00）为止。|
| UTF-16编码的字符串 |  `utf16[le/be][:<SIZE>]`     | string；SIZE 可选：指定字节数量，未指定时，到空字符（连续两个 0x00 字节）为止。|
| UTF-32编码的字符串 |  `utf32[le/be][:<SIZE>]`     | string；SIZE 可选：指定字节数量，未指定时，到空字符（连续四个 0x00 字节）为止。|
| 填白               |  `padding:<SIZE>`            | 无，将跳过指定数量的字节；SIZE 指定字节数量。     |

对 8 位以上整数、浮点数以及 UTF-16、UTF-32 编码，使用如下可选后缀表示大小头：

| 类型 | 类型标志 |
| ---- | -------- |
| 小头 | le       |
| 大头 | be       |

未指定时，默认跟随当前架构。

不同类型的表示方法：

| 类型              | 表示方法              | 备注                                                                      | 举例                  |
| --------          | ------------------    | --------------------------------------------                              | -----------------     |
| 数值类型          | 类型 + 大/小头        | 如不标大、小头，则跟随当前架构                                            | u16、u32be、u64le     |
| 连续数值类型      | 类型 + 大/小头 + 个数 | 如不标大、小头，则跟随当前架构，个数指该类数值的数值，必须大于零          | u16:10、u32be:10      |
| 字节序列          | 类型 + 长度           |                                                                           | bytes:234             |
| UTF-8 编码字符串  | 类型 + 长度 / 类型    | 如不标长度，则自动计算字符串长度（数据需包含表示结尾的字节零）            | utf8、utf8:123        |
| UTF-16 编码字符串 | 类型 + 长度 / 类型    | 如不标长度，则自动计算字符串长度（数据需包含表示结尾的十六位零）          | utf16、utf16:120      |
| UTF-32 编码字符串 | 类型 + 长度 / 类型    | 如不标长度，则自动计算字符串长度（数据需包含表示结尾的三十二位零）        | utf32be、utf32be:120  |

注意：

- 二进制格式关键词区分大小写。
- 字节序列、填白以及字符串的长度均以字节为单位。
- 我们使用多个构成部分组成的字符串来表示一个结构，不同构成部分之间使用空白字符分隔。

如，`i32le utf8:128 f64`，表示一个结构的构成部分依次如下：

1. 其中前 4 个字节是一个 32 位整数，小头存储；
1. 紧接着是一个 128 字节的 UTF-8 编码字符串；
1. 最后 8 字节是一个 64 位浮点数。

该结构一共 140 字节。

### 1.3) 格式化修饰符

<https://www.php.net/manual/en/function.sprintf.php>

### 1.4) 撰写要求

对一个方法的描述应包含如下部分（section）：

- `描述`（Description；必需）：首先按 [HVML 规范 - 2.2.4) 动态对象方法的描述语法](/zh/hvml-spec-v1.0-zh.md#224-动态对象方法的描述语法) 定义的语法给出方法的原型，其中包括对参数（形参）和返回值的简短描述。然后给出对该方法用途的简短描述。
- `参数`（Parameters；可选）。必要时给出对该方法参数的完整描述。
- `返回值`（Return Value；可选）。必要时给出对该方法返回值的完整描述。
- `异常`（Exceptions；必需）。列出此方法可能抛出的异常。
- `示例`（Examples；必需）。
- `参见`（See Also；可选）。列出相关的外部链接。
- `备注`（Notes；可选）。

某些方法可返回 `false`、`undefined` 等值标记错误。此等情形仅出现在当前动作元素设置有 `silently` 副词属性，且仅遇到可忽略异常的情况下。当一个方法在设置有 `silently` 副词属性的元素中被调用时，我们称该方法被要求“静默求值（evaluate silently）”。对支持静默求值的方法，对其用途的描述参照如下形式：

> 该方法改变当前的工作路径。成功时返回 `true`；失败时抛出异常，或在静默求值时，对可忽略异常返回 `false`。

## 2) 非动态变量

### 2.1) `TIMERS`

`TIMERS` 是一个协程级内置变量。该变量是一个对象集合（对象的 `id` 属性做唯一性键值）。

用于描述一个定时器对象的属性如下：

```js
{
    'id': <string: `the timer identifier, the key with unique restriction`>,
    'interval': <string: `the interval of the timer in milliseconds`>,
    'active': <string: `activated or not`>
}
```

该变量用于定义定时器，其上不提供动态方法；程序通过 `update` 元素修改该变量对应的容器数据来操作定时器。

#### 2.1.1) 批量新增定时器

```html
    <update on="$TIMERS" to="unite">
        [
            { "id" : "foo", "interval" : 1000, "active" : "no" },
            { "id" : "bar", "interval" : 2000, "active" : "no" },
        ]
    </update>
```


#### 2.1.2) 新增一个定时器

```html
    <update on="$TIMERS" to="append">
        { "id" : "foobar", "interval" : 3000, "active" : "yes" }
    </update>
```

#### 2.1.3) 移除一个定时器

```html
    <update on="$TIMERS" to="subtract">
        { "id" : "foobar" }
    </update>
```

#### 2.1.4) 修改特定定时器的属性

```html
    <!-- activate the timer `foo` -->
    <choose on="$TIMERS" by="FILTER: AS 'foo'">
        <update on="$?" at=".active" with="yes" />
    </choose>
```

或，

```html
    <update on="$TIMERS" to="overwrite">
        { "id" : "foo", "interval": 1500, "active" : "yes" }
    </update>
```

### 2.2) `REQUEST`

`REQUEST` 是一个协程级内置变量。该变量用来保存装载一个 HVML 程序时传递给该程序的请求参数，以对象形式保存。

比如下面的 Python 脚本装载一个 HVML 程序，并传递了 `nrUsers` 参数：

```python
hvml.load ("a.hvml", { "nrUsers" : 10 })
```

在程序中，我们可使用 `$REQUEST.nrUsers` 或 `$REQUEST['nrUsers']` 来引用上述脚本代码传入的数值（`10`）。

## 3) 必要动态变量

### 3.1) `SYSTEM`

该变量是一个会话级内置变量，主要用于获得或设置系统信息。该内置变量的实现，需要考虑如下要求：

- 在某个协程中调用 `$SYSTEM` 的设置器方法，可能产生 `change` 事件，解释器应该将该事件广播到所有会话，并进一步转发给会话中的所有协程。

#### 3.1.1) `const` 方法

获取系统常量。

**描述**

```js
$SYSTEM.const(
        <string $name: `the constant name`>
) any : `the constant value`
```

该方法获取指定常量的值。成功时返回对应的数据；失败时将抛出 `NoSuchKey` 异常，或在静默求值时，返回 `undefined`。

注意，如下常量应由所有 HVML 解释器定义：

- `HVML_SPEC_RELEASE`: HVML 规范版本号，如 `硕鼠`。
- `HVML_SPEC_VERSION`: HVML 规范版本号，如 `1.0`。
- `HVML_PREDEF_VARS_SPEC_RELEASE`: HVML 预定义变量规范版本号，如 `硕鼠`。
- `HVML_PREDEF_VARS_SPEC_VERSION`: HVML 预定义变量规范版本号，如 `1.0`。
- `HVML_INTRPR_NAME`: HVML 解释器的名称，如 `PurC`。
- `HVML_INTRPR_RELEASE`: HVML 解释器的发布名称，如 `立春`。
- `HVML_INTRPR_VERSION`: HVML 解释器的版本名称，如 `0.5.0`。

**异常**

- `NoSuchKey`：可忽略异常。

**示例**

```js
// 获取常量 `HVML_SPEC_VER` 的值
$SYSTEM.const('HVML_SPEC_VERSION')
    // string: '1.0'
```

#### 3.1.2) `uname` 方法

获取系统信息。

**描述**

```js
$SYSTEM.uname object :
    `an object contains the following properties:`
        - 'kernel-name':        < string: `kernel name (e.g., 'Linux')` >
        - 'kernel-release':     < string: `kernel release (e.g., '2.6.28')` >
        - 'kernel-version':     < string: `kernel version` >
        - 'nodename':           < string: `the network node hostname` >
        - 'machine':            < string: `machine hardware name` >
        - 'processor':          < string: `the processor type` >
        - 'hardware-platform':  < string: `the hardware platform` >
        - 'operating-system':   < string: `the operating system (e.g., 'GNU/Linux')` >
```

该方法获取系统信息，返回包含有内核名称、版本号等键值对的对象。注意，对某些不支持的系统特征，将返回空字符串。

**异常**

（无）

**示例**

```js
$SYSTEM.uname
    /* object:
       {
            'kernel-name':      'Linux',
            'kernel-release':   '5.4.0-99-generic',
            'kernel-version':   '#112-Ubuntu SMP Thu Feb 3 13:50:55 UTC 2022',
            'nodename':         'magicBook',
            'machine':          'x86_64',
            'processor':        'x86_64',
            'hardware-platform':'x86_64',
            'operating-system': 'GNU/Linux'
       }
    */
```

#### 3.1.3) `uname_prt` 方法

获取可打印的系统信息。

**描述**

```js
$SYSTEM.uname_prt string: `the kernel name.`
```

该方法获取内核名称，返回字符串。

```js
$SYSTEM.uname_prt(
        <'[kernel-name || kernel-release || kernel-version || nodename || machine || processor || hardware-platform || operating-system] | all | default' $which = 'default':
            - 'kernel-name':        `includes kernel name (e.g., 'Linux')`
            - 'kernel-release':     `includes kernel release (e.g., '2.6.28')`
            - 'kernel-version':     `includes kernel version`
            - 'nodename':           `includes the network node hostname`
            - 'machine':            `includes machine hardware name`
            - 'processor':          `includes the processor type`
            - 'hardware-platform':  `includes the hardware platform`
            - 'operating-system':   `includes the operating system (e.g., 'GNU/Linux')`
            - 'all':                `includes all parts`
            - 'default':            `is equivalent to 'kernel-name'`
        >
) string: `the string concatenated the desired system information parts together.`
```

该方法返回多个指定特征的特征值，用空格分隔，串接为一个字符串返回。注意，对某些不支持的系统特征，按对应的特征值为空字符串处理。

**异常**

（无）

**示例**

```js
// 获取内核名称
$SYSTEM.uname_prt
    // string: 'Linux'

// 获取内核名称及版本号
$SYSTEM.uname_prt('kernel-name kernel-release kernel-version')
    // string: "Linux 5.4.0-80-generic #90-Ubuntu SMP Fri Jul 9 22:49:44 UTC 2021"
```

#### 3.1.4) `locale` 方法

获取或设置区域（locale）。

**描述**

```js
$SYSTEM.locale string : `the locale for the messages category.`
```

该方法获得消息分类（messages category）的区域，返回字符串。

```js
$SYSTEM.locale(
        < 'ctype | numeric | time | collate | monetary | messages | paper | name | address | telephone | measurement | identification' $category = 'messages':
            - 'ctype':          `Character classification`
            - 'numeric':        `Formatting of nonmonetary numeric values`
            - 'time':           `Formatting of date and time values`
            - 'collate':        `String collation`
            - 'monetary':       `Formatting of monetary values`
            - 'messsages':      `Localizable natural-language messages`
            - 'paper':          `Settings related to the standard paper size (*)`
            - 'name':           `Formatting of salutations for persons (*)`
            - 'address':        `Formatting of addresses and geography-related items (*)`
            - 'telephone':      `Formats to be used with telephone services (*)`
            - 'measurement':    `Settings related to measurements (metric versus US customary) (*)`
            - 'identification': `Metadata describing the locale (*)`
        >
) string | undefined : `the locale like 'zh_CN'.`
```

该方法获取指定分类的区域，返回字符串。某些平台可能不支持特定的区域分类，比如姓名（`name`）分类。对不支持的区域分类，该函数将抛出 `Unsupported` 异常，或静默求值时返回 `undefined`。

```js
$SYSTEM.locale(!
        < '[ctype || numeric || time || collate || monetary || messages || paper || name || address || telephone || measurement || identification] | all' $categories:
            - 'ctype':          `Character classification`
            - 'numeric':        `Formatting of nonmonetary numeric values`
            - 'time':           `Formatting of date and time values`
            - 'collate':        `String collation`
            - 'monetary':       `Formatting of monetary values`
            - 'messsages':      `Localizable natural-language messages`
            - 'paper':          `Settings related to the standard paper size (*)`
            - 'name':           `Formatting of salutations for persons (*)`
            - 'address':        `Formatting of addresses and geography-related items (*)`
            - 'telephone':      `Formats to be used with telephone services (*)`
            - 'measurement':    `Settings related to measurements (metric versus US customary) (*)`
            - 'identification': `Metadata describing the locale (*)`
            - 'all':            `All of the locale categories`
        >,
        <string $locale: `the locale for $categories`>
) true | false
```

该方法设置指定分类（单个或多个）的区域。成功时返回 `true`，失败时返回 `false`。某些平台可能不支持特定的区域分类，比如姓名（`name`）分类。对不支持的区域分类，该函数将抛出 `Unsupported` 异常，或在静默求值时返回 `false`。

**异常**

- `Unsupported`：不支持的区域分类。可忽略异常。

**备注**

1. 在 HVML 中，表示区域的字符串始终使用 `en_US`、`zh_CN` 这种形式。
1. 在 HVML 应用框架中，要求始终使用 UTF-8 编码。
1. 对特定区域的修改，将在 `$SYSTEM` 变量上产生 `change:locale/<category>` 事件。

**示例**

```js
$SYSTEM.locale
    // string: "en_US"

$SYSTEM.locale(! 'all', 'zh_CN')
    // boolean: true

$SYSTEM.locale
    // string: "zh_CN"
```

#### 3.1.5) `time` 方法

获取或设置日历时间（calendar time）。

**描述**

```js
$SYSTEM.time longint: `the calendar time (seconds since Epoch)`
```

该方法获取当前日历时间（自 Epoch 以来的秒数），返回值类型为 `longint`。

```js
$SYSTEM.time(!
        <real $seconds: `seconds since Epoch`>
) true | false
```

该方法设置系统时间，整数部分表示自 Epoch 以来的秒数，小数部分表示微秒数。成功时返回 `true`，失败时抛出 `AccessDenied` 异常，静默求值时返回 `false`。

**异常**

- `InvalidValue`：传入无效参数，如负值或者大于 100,000 或小于 0 的微秒值。
- `AccessDenied`：当前会话的所有者没有权限设置系统时间时，将抛出该异常。

**备注**

1. 对日历时间的修改，将在 `$SYSTEM` 变量上产生 `change:time` 事件。

**示例**

```js
$SYSTEM.time
    // longint: 123456789L
```

**参见**

- C 标准函数：`gettimeofday()`、`settimeofday()`
- PHP: <https://www.php.net/manual/en/ref.datetime.php>
- PHP: <https://www.php.net/manual/en/datetime.formats.php>
- PHP DateTime 类：<https://www.php.net/manual/en/class.datetime.php>

#### 3.1.6) `time_us` 方法

获取或设置具有微秒精度的系统时间。

**描述**

```js
$SYSTEM.time_us longdouble :
    `A long double number representing the number of seconds (integral part) and microseconds (fractional part) since Epoch.`
```

该方法获取当前系统时间，包括自 Epoch 以来的秒数以及微秒数，返回值 longdouble 数值，小数部分为微秒值。

```js
$SYSTEM.time_us(
        [
            < 'longdouble | object' $return_type = 'longdouble': `indicate the return type: a long double number or an object.`>
        ]
) longdouble | object : `A long double number or an object representing the number of seconds and microseconds since Epoch:`
        - 'sec': < longint: `seconds since Epoch` >
        - 'usec': < longint: `microseconds` >
```

该方法获取当前系统时间，包括自 Epoch 以来的秒数以及微秒数，返回值类型为 longdouble 数值或包含 `sec` 和 `usec` 两个属性的对象。

```js
$SYSTEM.time_us(!
        <real $sec_us: `seconds with microseconds since Epoch`>
) true | false
```

该方法用一个实数（整数部分表示自 Epoch 以来的秒数，小数部分表示微秒数）设置系统时间。成功时返回 `true`，失败时抛出异常，静默求值时返回 `false`。

```js
$SYSTEM.time_us(!
        <object $time_with_us: `An object representing the number of seconds and microseconds since Epoch`>
) true | false
```

该方法使用表示系统时间的对象设置系统时间。成功时返回 `true`，失败时抛出异常，静默求值时返回 `false`。

**异常**

- `InvalidValue`：获取器被调用时，传入错误参数时（如错误的返回类型），将抛出该异常；静默求值时，返回 `longdouble` 类型的当前事件。设置器被调用时，传入无效参数时（如负值或者大于 100,000 或小于 0 的微秒值）时，将抛出该异常。
- `AccessDenied`：设置器被调用时，当运行解释器的所有者没有权限设置系统时间时，将抛出该异常。

**备注**

1. 对系统时间的修改，将在 `$SYSTEM` 变量上产生 `change:time` 事件。

**示例**

```js
$SYSTEM.time_us
    // longdouble: 123456789.456789
```

**参见**

- C 标准函数：`gettimeofday()`、`settimeofday()`
- PHP: <https://www.php.net/manual/en/ref.datetime.php>
- PHP: <https://www.php.net/manual/en/datetime.formats.php>
- PHP DateTime 类：<https://www.php.net/manual/en/class.datetime.php>

#### 3.1.7) `sleep` 方法

暂停当前会话的执行。

**描述**

```js
$SYSTEM.sleep(
        real $delay_time: `the delay time in seconds; a double or long double number representing the number of seconds (integral part) and microseconds/nanoseconds (fractional part) to delay.`
) real | false
```

该方法暂停当前 HVML 会话的执行以指定的秒数。若使用浮点数指定秒数，则小数部分可指定要休眠的纳秒数。正常情况下，该方法返回 0；当休眠被信号打断时，则返回剩余的秒数（返回值的类型和参数类型一致）。

**异常**

- `ArgumentMissed`：未指定必要参数。可忽略异常；静默求值时返回 `false`。
- `WrongDataType`：非实数类参数类型。可忽略异常；静默求值时返回 `false`。
- `InvalidValue`：传入无效参数，如负值。可忽略异常；静默求值时返回 `false`。
- `SystemFault`：操作系统故障。不可忽略异常。

**示例**

```js
$SYSTEM.sleep(1UL)
    // ulongint: 0UL

$SYSTEM.sleep(0.3)
    // longdouble: 0.0FL
```

**参见**

- POSIX 函数：`sleep()`、`usleep()` 和 `nanosleep()`。

#### 3.1.8) `timezone` 方法

获取或设置时区。

**描述**

```js
$SYSTEM.timezone : string | false
```

该方法返回当前时区。

```js
$SYSTEM.timezone(!
        <string $timezone: `new timezone`>
        [,
            < 'local | global' $permanently = 'local': `change timezone permanently/globally or temporarily/locally.`>
        ]
) true | false
```

该方法设置当前时区。成功时返回 `true`，失败时抛出异常，静默求值时返回 `false`。

HVML 推荐使用类似 `Asia/Shanghai` 这样的字符串来表示时区。实质上，这个字符串是 POSIX 系统保存时区信息的文件路径，比如对 `Asia/Shanghai`，其时区信息通常保存在 `/usr/share/zoneinfo/Asia/Shanghai` 文件或 `/var/db/timezone/zoneinfo/Asia/Shanghai` 中。也支持如下特别的时区名称：

- `PRC`：中国标准时间，即北京时间，同 `Asia/Shanghai`。
- `Hongkong`：香港时间，同 `Asia/Hong_Kong`。
- `UTC`：协调世界时，同 `Etc/UTC`。
- `UCT`：协调世界时的另一个名称，同 `Etc/UTC`。
- `Greenwich`：格林威治时间，同 `Etc/GM`。
- `GMT`：格林威治时间的简称，同 `Etc/GMT`。
- `posixrules`：POSIX 默认时区规则，同 `America/New_York`。

**异常**

- `InvalidValue`：无效的时区字符串。对无效的选项关键词，静默求值时，将被视作 `local`。
- `AccessDenied`：当前会话的所有者没有权限持久更改系统时区。

**备注**

1. 对系统时区的修改，将在 `$SYSTEM` 变量上产生 `change:timezone` 事件。
1. 系统时区的全局、持久修改，可能需要重新启动操作系统。

**示例**

```js
$SYSTEM.timezone
    // string: "Asia/Shanghai"

$SYSTEM.timezone(! 'America/New_York' )
    // true

$SYSTEM.timezone
    // string: "America/New_York"
```

**参见**

- C 标准函数：`tzset()`
- PHP: <https://www.php.net/manual/en/timezones.php>

#### 3.1.9) `cwd` 方法

获取或设置当前工作路径。

**描述**

```js
$SYSTEM.cwd string | false: `returns the current working directory on success, or @false on failure.`
```

该方法获取当前工作路径。成功时返回 `true`，失败时抛出异常；在静默求值时，对可忽略异常返回 `false`。

```js
$SYSTEM.cwd(!
        <string $dir: `the new path for the current working directory.`>
) boolean: `returns @true on success or @false on failure.`
```

该方法改变当前工作路径。成功时返回 `true`，失败时抛出异常；在静默求值时，对可忽略异常返回 `false`。

**异常**

该方法可能产生的异常，均为可忽略异常：

- `InvalidValue`：传入的目录字符串含有底层操作系统不支持的非法字符。
- `EntityNotFound`：指定的目录不存在。
- `AccessDenied`：无访问权限。
- `TooMany`：太长的符号链接跳转。
- `TooLong`：太长的目录名。
- `IOFailure`：输入输出错误。
- `OSFailure`：其他操作系统错误。

**备注**

1. 对当前工作路径的修改，将在 `$SYSTEM` 变量上产生 `change:cwd` 事件。

**参见**

- C 标准函数：`chdir()`, `getcwd()`

#### 3.1.10) `env` 方法

获取或设置系统环境变量。

**描述**

```js
$SYSTEM.env(
        <string: `the environment variable name`>
) string | undefined
```

该方法获取指定环境变量的值（字符串）；未设置时抛出 `NoSuchKey` 异常，静默求值时返回 `undefined`。

```js
$SYSTEM.env(!
        <string: `the environment variable name`>,
        <string | undefined: `the value`>
) true | false: `returns @true on success, otherwise @false if evaluated silently.`
```

该方法设置指定的环境变量，返回布尔数据，指明是否覆盖了已有环境变量。

**异常**

该方法可能产生的异常，均为可忽略异常：

- `InvalidValue`：非法的环境变量名称。
- `NoSuchKey`：不存在指定的环境变量。

**备注**

1. 新增特定的环境变量，将在 `$SYSTEM` 变量上产生 `change:env/grown` 事件，事件参数为一个对象，包含以新增环境变量名称为键，对应值为键值的键值对。
1. 对特定环境变量的修改，将在 `$SYSTEM` 变量上产生 `change:env` 事件，事件参数为一个对象，包含以修改的环境变量名称为键，对应值为键值的键值对。
1. 删除特定的环境变量，将在 `$SYSTEM` 变量上产生 `change:env/shrunk` 事件，事件参数为被移除的环境变量名称。

**示例**

```js
// 设置环境变量 `LOGNAME` 的值
$SYSTEM.env(! 'LOGNAME', 'tom' )
    // boolean: true
```

#### 3.1.11) `random_sequence` 方法

从内核获取指定的随机数据，可用于随机数发生器的种子或加密用途。

**描述**

```js
$SYSTEM.random_sequence(
        <number $length: `the length of the random byte sequence`>
) bsequence | false
```

该方法从内核获取指定长度的随机数据，可用于随机数发生器的种子或加密用途。该方法返回指定长度的字节序列或抛出异常；静默求值时，返回 `false`。

**异常**

- `InvalidValue`：`$length` 无效的长度；长度需大于 0 小于等于 256。
- `NotSupported`：不支持。

**示例**

```js
// 从内核获得随机数据用于当前会话的随机数发生器种子。
$SYSTEM.random(! $EJSON.fetchreal($SYSTEM.random_sequence(4), 'u32') )
    // boolean: true
```

**参见**

- Linux 特有接口：`getrandom()`

#### 3.1.12) `random` 方法

获取随机值。

**描述**

```js
$SYSTEM.random longint: `a random between 0 and RAND_MAX.`
```

该方法获取 0 到 C 标准函数库定义的 `RAND_MAX`（至少 `32767`）之间的一个随机值（`longint`）。

```js
$SYSTEM.random(
        <real $max: `the max value`>
) real | false: `A random real number between 0 and $max. The type of return value will be same as the type of $max.`
```

该方法获取 0 到指定的最大值之间的一个随机值。返回值的类型同参数 `$max` 的类型。

```js
$SYSTEM.random(!
        <real $seed: `the random seed`>
        [, <number $complexity: `a number equal or greater than 8 to indicates how sophisticated the random number generator it should use - the larger, the better the random numbers will be.>
        ]
) boolean: `@true for success, @false otherwise.`
```

该方法设置随机数发生器的种子（`$seed`）和/或复杂度（`$complexity`）。该方法在成功时返回 `true`；失败时抛出异常，或在静默求值时，对可忽略异常返回 `false`。

**异常**

`InvalidValue`：传入了无效参数，比如过小的 `$complexity` 值。

**示例**

```js
// 使用当前系统日历时间设置随机数种子。
$SYSTEM.random(! $SYSTEM.time )
    // true

// 使用当前系统日历时间设置随机数种子，并设置随机数发生器的复杂度为最高。
$SYSTEM.random(! $SYSTEM.time, 256 )
    // true

$SYSTEM.random
    // longint: 8899L

$SYSTEM.random(1)
    // number: 0.789

$SYSTEM.random(1000L)
    // longint: 492L

$SYSTEM.random(-10FL)
    // longdouble: -8.96987678FL
```

**参见**

- C 标准函数：`random_r()`
- C 标准函数：`srandom_r()`
- C 标准函数：`initstate_r()`

### 3.2) `SESSION`

该变量是一个会话级内置变量，解释器在创建一个新的会话时，会自动创建并绑定。该变量主要用于会话相关的信息，并提供给用户在当前会话的不同 HVML 协程之间共享数据的机制。

#### 3.2.1) `app` 方法

获取当前会话的应用名称。

**描述**

```js
$SESSION.app
    string : `the app name of current session.`
```

该方法获取当前会话的应用名称。

**异常**

该方法不产生异常。

**示例**

```js
$SESSION.app
    // string: 'cn.fmsoft.hvml.sample'
```

#### 3.2.2) `runner` 方法

获取当前会话的行者名称。

**描述**

```js
$SESSION.runner
    string : `the runner name of current session.`
```

该方法获取当前会话的应用名称。

**异常**

该方法不产生异常。

**示例**

```js
$SESSION.runner
    // string: 'hello'
```

#### 3.2.3) `myObj` 静态属性

`myObj` 是 `SESSION` 的一个静态属性，用来定义用户自定义键值对，初始为一个空对象。程序可使用 `update` 元素设置其内容：

```html
<!DOCTYPE hvml>
<hvml target="html">
    <head>
        <update on="$SESSION.myObj" to="displace">
            {
                "AUTHOR": "Vincent Wei",
            }
        </update>
    </head>

    <body>
        ...
    </body>
</hvml>
```

由于 `$SESSION` 是会话级变量，故而可以在当前会话的另一个 HVML 协程中观察该数据上的变化：

```html
    <observe on="$SESSION.myObj" for="change:AUTHOR" in="#theStatusBar">
        ...
    </observe>
```

#### 3.2.4) `user` 方法

获取或设置用户键值对。

**描述**

```js