# levn 中文文档

规范地址：https://npmcn.com/package/levn/

版本：0\.4\.1
npm 元数据更新时间：2023-06-22T16:32:51.151Z
中文译文更新时间：2026-11-04T23:23:36.103Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/levn
原文对照：https://npmcn.com/package/levn/?lang=original
项目主页：https://github.com/gkz/levn
源码仓库：https://github.com/gkz/levn

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：24.9 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>= 0\.8\.0
- 运行依赖：2 个
- 首次发布：2013-10-04T20:10:33.861Z
- 最新版本发布：2020-04-04T02:05:31.527Z
- 近 30 天下载量：570465688（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

轻ECMAScript （JavaScript）值表示法-人类编写的，简洁的，类型的，灵活的

## 安装

```sh
npm install levn
```

也可以使用：`pnpm add levn`、`yarn add levn`、`bun add levn`

## README

# levn [![Build Status](https://travis-ci.org/gkz/levn.png)](https://travis-ci.org/gkz/levn)

**轻ECMAScript （JavaScript）值表示法** Levn是一个库，它允许您根据期望的类型将字符串解析为JavaScript值。它适用于少量的人工输入数据(例如。配置文件，命令行参数)。

Levn的目标是在文本中简洁地描述JavaScript值，并允许对这些值进行提取和验证。Levn使用 [类型检查](https://github.com/gkz/type-check) 获取其类型格式，并验证结果。麻省理工学院的许可。0.4.1版本。

**这与JSON有什么不同？** Levn只适合人类编写，（由于前面的一点）更简洁，可以根据提供的类型进行验证，具有正则表达式和日期文字，并且可以轻松地使用自定义类型进行扩展。另一方面，它可能更慢，因此在传输大量数据时效率更低，这没有关系，因为这不是它的目的。

```
npm install levn
```

有关levn的最新消息， [在twitter上关注我](https://twitter.com/gkzahariev)。

## 快速的例子

```js
var parse = require('levn').parse;
parse('Number', '2');      // 2
parse('String', '2');      // '2'
parse('String', 'levn');   // 'levn'
parse('String', 'a b');    // 'a b'
parse('Boolean', 'true');  // true

parse('Date', '#2011-11-11#'); // (Date object)
parse('Date', '2011-11-11');   // (Date object)
parse('RegExp', '/[a-z]/gi');  // /[a-z]/gi
parse('RegExp', 're');         // /re/
parse('Int', '2');             // 2

parse('Number | String', 'str'); // 'str'
parse('Number | String', '2');   // 2

parse('[Number]', '[1,2,3]');                      // [1,2,3]
parse('(String, Boolean)', '(hi, false)');         // ['hi', false]
parse('{a: String, b: Number}', '{a: str, b: 2}'); // {a: 'str', b: 2}

// at the top level, you can ommit surrounding delimiters
parse('[Number]', '1,2,3');                      // [1,2,3]
parse('(String, Boolean)', 'hi, false');         // ['hi', false]
parse('{a: String, b: Number}', 'a: str, b: 2'); // {a: 'str', b: 2}

// wildcard - auto choose type
parse('*', '[hi,(null,[42]),{k: true}]'); // ['hi', [null, [42]], {k: true}]
```

## 用法

`require('levn');` 返回一个公开三个属性的对象。 `VERSION` 以字符串形式表示库的当前版本。 `parse` 和 `parsedTypeParse` 是功能。

```js
// parse(type, input, options);
parse('[Number]', '1,2,3'); // [1, 2, 3]

// parsedTypeParse(parsedType, input, options);
var parsedType = require('type-check').parseType('[Number]');
parsedTypeParse(parsedType, '1,2,3'); // [1, 2, 3]
```

### 解析（类型，输入，选项）

`parse` 强制转换字符串 `input` 转换为一个JavaScript值 `type` 在 [类型格式](https://github.com/gkz/type-check#type-format) (并考虑到可选的 `options`)并返回结果的JavaScript值。

##### 参数

-   类型, `String` -写在 [类型格式](https://github.com/gkz/type-check#type-format) 要对照哪一个
-   输入- `String` 写入的值 [levn格式](https://npmcn.com/package/levn/#readme-levn-format)
-   选项- `Maybe Object` -可选参数，指定附加参数 [选项](https://npmcn.com/package/levn/#readme-options)

##### 返回

`*` -生成的JavaScript值

##### 例子

```js
parse('[Number]', '1,2,3'); // [1, 2, 3]
```

### parsedTypeParse（parsedType, input, options）

`parsedTypeParse` 强制转换字符串 `input` 转换为一个JavaScript值 `type` 哪些已经被解析过了(考虑到可选的 `options`)并返回结果的JavaScript值。方法解析类型 [类型检查](https://github.com/gkz/type-check) 图书馆的 `parseType` 函数。

##### 参数

-   类型, `Object` -要检查的已解析类型格式中的类型
-   输入- `String` 写入的值 [levn格式](https://npmcn.com/package/levn/#readme-levn-format)
-   选项- `Maybe Object` -可选参数，指定附加参数 [选项](https://npmcn.com/package/levn/#readme-options)

##### 返回

`*` -生成的JavaScript值

##### 例子

```js
var parsedType = require('type-check').parseType('[Number]');
parsedTypeParse(parsedType, '1,2,3'); // [1, 2, 3]
```

## Levn格式

Levn可以使用您提供的类型信息来选择要从输入中生成的适当值。对于相同的输入，它将根据所提供的类型选择不同的输出值。例如, `parse('Number', '2')` 会产生数字 `2`,但 `parse('String', '2')` 会产生字符串 `"2"`。

如果不提供类型信息，则直接使用 `*`， levn将根据明确的“显式”模式解析输入，我们现在将详细说明-您还可以设置 `explicit` 选项手动设置为true [选项](https://npmcn.com/package/levn/#readme-options)。

-   `"string"`， `'string'` 解析为字符串，例如： `"a msg"` 是 `"a msg"`
-   `#date#` 被解析为日期，例如。 `#2011-11-11#` 是 `new Date('2011-11-11')`
-   `/regexp/flags` 解析为RegExp，例如： `/re/gi` 是 `/re/gi`
-   `undefined`， `null`， `NaN`， `true`, `false` 它们都是JavaScript的等价物吗
-   `[element1, element2, etc]` 是Array，并且将强制转换过程递归地应用于每个元素。如。 `[1,2,3]` 是 `[1,2,3]`。
-   `(element1, element2, etc)` 是一个元组，并且将强制转换过程递归地应用于每个元素。如。 `(1, a)` 是 `(1, a)` (是 `[1, 'a']`）.
-   `{key1: val1, key2: val2, ...}` 是一个对象，并且转换过程递归地应用于每个属性。如。 `{a: 1, b: 2}` 是 `{a: 1, b: 2}`。
-   任何不属于上述范畴及不包含特殊字符(`[``]``(``)``{``}``:``,`)是字符串，例如。 `$12- blah` 是 `"$12- blah"`。

如果您确实提供了类型信息，您可以使您的输入更简洁，因为程序已经有了一些关于它所期望的信息。请参阅 [类型格式](https://github.com/gkz/type-check#type-format) 的部分 [类型检查](https://github.com/gkz/type-check) 有关如何指定类型的详细信息。关于莱文如何处理这些信息，有一些规则：

-   如果期望的是字符串，并且只是字符串，则输入的所有字符（包括任何特殊字符）都将成为输出的一部分。如。 `[({})]` 是 `"[({})]"`, `"hi"` 是 `'"hi"'`。
-   如果需要Date，则周围 `#` 可以从日期文字中省略。如。 `2011-11-11` 是 `new Date('2011-11-11')`。
-   如果期望使用RegExp，则不需要指定标志，并且regex不使用任何特殊字符（开始和结束） `/` 可以省略-这将影响将正则表达式的源设置为输入。如。 `regex` 是 `/regex/`。
-   如果期望有一个Array，并且它是根节点（在顶层），则打开 `[` 和关闭 `]` 可以省略。如。 `1,2,3` 是 `[1,2,3]`。
-   如果期望有一个元组，并且它是根节点（在顶层），则打开 `(` 和关闭 `)` 可以省略。如。 `1, a` 是 `(1, a)` (是 `[1, 'a']`）.
-   如果期望有一个Object，并且它是根节点（在顶层），则打开 `{` 和关闭 `}` 可以省略。如 `a: 1, b: 2` 是 `{a: 1, b: 2}`。

如果您列出多个类型(例如： `Number | String`)，它将首先尝试转换到第一个类型，然后进行验证——如果验证失败，它将转移到下一个类型，依此类推，从左到右。您必须小心，因为某些类型可以通过任何输入成功，例如String。因此，将String放在列表的末尾。在非显式模式下，Date和RegExp可以成功地处理大量的输入——也要小心，如果它们不在列表的最后，请将它们列在末尾。

特殊字符和元素之间的空白是无关紧要的。

## 选项

Options是一个对象。的可选参数 `parse` 和 `parsedTypeParse` 功能。

### 显式的

一个 `Boolean`． 默认情况下是 `false`。

**例子:**

```js
parse('RegExp', 're', {explicit: false});          // /re/
parse('RegExp', 're', {explicit: true});           // Error: ... does not type check...
parse('RegExp | String', 're', {explicit: true});  // 're'
```

`explicit` 设置是否处于显式模式。使用 `*` 自动激活显式模式。欲了解更多信息，请阅读 [levn格式](https://npmcn.com/package/levn/#readme-levn-format) 部分。

### customTypes

一个 `Object`． 空 `{}` 默认情况下。

**例子:**

```js
var options = {
  customTypes: {
    Even: {
      typeOf: 'Number',
      validate: function (x) {
        return x % 2 === 0;
      },
      cast: function (x) {
        return {type: 'Just', value: parseInt(x)};
      }
    }
  }
}
parse('Even', '2', options); // 2
parse('Even', '3', options); // Error: Value: "3" does not type check...
```

**另一个例子:**

```js
function Person(name, age){
  this.name = name;
  this.age = age;
}
var options = {
  customTypes: {
    Person: {
      typeOf: 'Object',
      validate: function (x) {
        x instanceof Person;
      },
      cast: function (value, options, typesCast) {
        var name, age;
        if ({}.toString.call(value).slice(8, -1) !== 'Object') {
          return {type: 'Nothing'};
        }
        name = typesCast(value.name, [{type: 'String'}], options);
        age = typesCast(value.age, [{type: 'Numger'}], options);
        return {type: 'Just', value: new Person(name, age)};
    }
  }
}
parse('Person', '{name: Laura, age: 25}', options); // Person {name: 'Laura', age: 25}
```

`customTypes` 是一个对象，其键是类型的名称，其值是一个具有三个属性的对象， `typeOf`， `validate`, `cast`． 欲了解更多有关 `typeOf` 和 `validate`，请参阅 [自定义类型](https://github.com/gkz/type-check#custom-types) 类型检查部分。

`cast` 是一个函数，它接受三个参数：问题的值、选项和typesCast函数。在 `cast`，尝试将值强制转换为指定的类型。如果成功，则返回格式的对象 `{type: 'Just', value: CAST-VALUE}`如果你知道行不通，那就回去 `{type: 'Nothing'}`。你可以使用 `typesCast` 函数强制转换任何子值。记得传递 `options` 到它。在你的函数中你也可以检查 `options.explicit` 并采取相应的行动。

## 技术对

`levn` 写在 [LiveScript](http://livescript.net/) -一种编译成JavaScript的语言。它使用 [类型检查](https://github.com/gkz/type-check) 解析类型和验证值。它还使用 [prelude.ls](http://preludels.com/) 图书馆。

## 常见问题

### levn 是什么？

轻ECMAScript （JavaScript）值表示法-人类编写的，简洁的，类型的，灵活的

### 如何安装 levn？

在项目目录运行 npm install levn，或使用 pnpm add / yarn add / bun add。

### levn 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/levn 是否存在。

### levn 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### levn 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 0\.8\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### levn 可以商用吗？

levn 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### levn 的下载量有多少？

根据 npm 官方下载统计，levn 在 2026/10/04 – 2026/11/02 这 30 天内被下载 570,465,688 次，日均约 19,015,523 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### levn 还在维护吗？

最新版本 0\.4\.1 发布于 2020/04/04（6 年前）；至今共发布 10 个版本，其中过去 12 个月发布了 0 个；首次发布于 2013/10/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。