Nushell
安装 Nu !
快速开始
  • Nushell 之书
  • 命令参考列表
  • 实战指南
  • 语言参考指南
  • 贡献指南
博客
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
安装 Nu !
快速开始
  • Nushell 之书
  • 命令参考列表
  • 实战指南
  • 语言参考指南
  • 贡献指南
博客
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
  • 简介
  • 安装
    • 默认 Shell
  • 快速入门
    • 快速入门
    • 在系统中四处移动
    • 用 Nu 的方式思考
    • Nushell 速查表
  • Nu 基础篇
    • 数据类型
    • 加载数据
    • 管道
    • 处理字符串
    • 处理列表
    • 处理记录
    • 处理表格
    • 导航和访问结构化数据
    • 特殊变量
  • Nushell 编程
    • 自定义命令
    • 别名
    • 运算符
    • 变量
    • 控制流
    • 脚本
    • 模块
      • 使用模块
      • 创建模块
    • 覆层
    • 排序
    • 测试你的 Nushell 代码
    • 脚本调试
    • 最佳实践
  • Nu 作为 Shell 使用
    • 配置
    • 环境
    • 标准输出、标准错误和退出码
    • 运行系统(外部)命令
    • 如何配置第三方提示
    • 目录栈
    • Reedline,Nu 的行编辑器
    • 自定义补全
    • 外部命令
    • Nu 的配色和主题
    • 钩子
    • 后台任务
  • 迁移到 Nu
    • 从 Bash 到 Nu
    • 从 CMD.EXE 到 Nu
    • 从 PowerShell 到 Nu
    • 从其他 Shell 或 DSL 到 Nu
    • 从命令式语言到 Nu
    • 从函数式语言到 Nu
    • Nushell 运算符对照
  • 设计说明
    • Nushell代码执行原理
  • (不怎么)高级篇
    • 标准库
    • Dataframes
    • 元数据
    • 创建你自己的错误
    • 并行
    • 插件
    • explore
    • 使用 tui 构建终端用户界面
    • MCP 服务器

元数据

在使用 Nu 的过程中,你可能遇到过这样的情况:你觉得有一些额外的事情在幕后进行。例如,假设你试图打开一个 Nu 支持的文件,却忘记了这一点并试图再次转换:

open Cargo.toml | from toml
# => Error: nu::shell::only_supports_this_input_type
# =>
# =>   × Input type not supported.
# =>    ╭─[repl_entry #1:1:1]
# =>  1 │ open Cargo.toml | from toml
# =>    · ──┬─              ────┬────
# =>    ·   │                   ╰── only string input data is supported
# =>    ·   ╰── input type: record<package: record<name: string, version: string, edition: string>>
# =>    ╰────

这个错误信息不仅告诉我们,我们给 from toml 的不是一个字符串,还告诉我们这个值最初来自哪里。那么它是如何知道的呢?

在 Nu 中流经管道的值通常带有一些额外信息,或者说元数据。它们被称为标签,就像商店里商品上的标签一样。这些标签并不影响数据,但它们给了 Nu 一种改善数据处理体验的方式。

让我们再次运行 open 命令,但这一次,我们将看一下它所反馈的标签:

metadata (open Cargo.toml)
# => ╭──────┬────────────────────╮
# => │      │ ╭───────┬────────╮ │
# => │ span │ │ start │ 169459 │ │
# => │      │ │ end   │ 169463 │ │
# => │      │ ╰───────┴────────╯ │
# => ╰──────┴────────────────────╯

每个值都带有一个跨度,它记录了这个值在源代码中的来源位置。让我们仔细看一下:

metadata (open Cargo.toml) | get span
# => ╭───────┬────────╮
# => │ start │ 169485 │
# => │ end   │ 169489 │
# => ╰───────┴────────╯

跨度的“start”和“end”是 Nushell 在当前会话中读取过的所有代码(标准库、你的配置文件,以及你输入的每条命令行)中的字节偏移量,所以这些数字才会这么大。view span 命令可以显示某个跨度所指向的代码:

let span = (metadata (open Cargo.toml)).span
view span $span.start $span.end
# => open

这个跨度指向产生该值的 open 命令。这就是我们前面看到的错误知道该在哪里画下划线的原因。

当你把一个命令的输出通过管道传给 metadata、而不是作为参数传入时,你还可以看到该命令附加在其输出上的元数据。例如,open 会记录数据来自哪个文件:

open Cargo.toml | metadata
# => ╭────────┬───────────────────────────────╮
# => │        │ ╭───────┬────────╮            │
# => │ span   │ │ start │ 169587 │            │
# => │        │ │ end   │ 169591 │            │
# => │        │ ╰───────┴────────╯            │
# => │ source │ /home/user/project/Cargo.toml │
# => ╰────────┴───────────────────────────────╯

其它命令会附加其它元数据。例如,to json 以及其它 to 命令会设置 content_type(如 application/json),ls 会把它的 name 列标记为包含路径,而 HTTP 命令会附加 HTTP 响应。

这两种形式不能混用。当给 metadata 传入一个参数时,它只返回该参数的 span,并忽略任何管道输入。这使得它在闭包或块中可以安全使用,因为其中的第一条命令会接收该块的输入:

[1 2] | each {|x| (metadata $x).span } | to nuon
# => [[start, end]; [170379, 170380], [170381, 170382]]

这也意味着 metadata $in 只会报告一个跨度。要查看随管道输入而来的元数据,例如 source 或 content_type,请使用不带参数的 metadata。

自定义元数据

你可以使用 metadata set 命令及其可选的闭包参数,把任意元数据附加到管道数据上:

"data" | metadata set { merge {custom_key: "custom_value"} } | metadata
# => ╭────────────┬────────────────────╮
# => │            │ ╭───────┬────────╮ │
# => │ span       │ │ start │ 169613 │ │
# => │            │ │ end   │ 169619 │ │
# => │            │ ╰───────┴────────╯ │
# => │ custom_key │ custom_value       │
# => ╰────────────┴────────────────────╯

路径列

列出文件的命令,例如 ls,会标记出包含路径的列:

ls | metadata
# => ╭──────────────────────────────┬────────────────────╮
# => │                              │ ╭───────┬────────╮ │
# => │ span                         │ │ start │ 169684 │ │
# => │                              │ │ end   │ 169686 │ │
# => │                              │ ╰───────┴────────╯ │
# => │                              │ ╭───┬──────╮       │
# => │ path_columns                 │ │ 0 │ name │       │
# => │                              │ ╰───┴──────╯       │
# => │                              │ ╭───┬──────╮       │
# => │ table_width_priority_columns │ │ 0 │ name │       │
# => │                              │ ╰───┴──────╯       │
# => ╰──────────────────────────────┴────────────────────╯

当 table 显示 path_columns 中列出的某一列时,它会根据 $env.LS_COLORS 为路径着色,而 table --icons 还会为每种文件类型添加一个图标。table_width_priority_columns 列表告诉 table,当表格对于终端来说过宽时,应该优先把空间分给哪些列。

你也可以用 metadata set 在自己的数据上设置这两项:

[[name size]; [Cargo.toml 1.2kB]]
| metadata set --path-columns [name] --table-width-priority-columns [name]
| metadata
| reject span
# => ╭──────────────────────────────┬──────────────╮
# => │                              │ ╭───┬──────╮ │
# => │ path_columns                 │ │ 0 │ name │ │
# => │                              │ ╰───┴──────╯ │
# => │                              │ ╭───┬──────╮ │
# => │ table_width_priority_columns │ │ 0 │ name │ │
# => │                              │ ╰───┴──────╯ │
# => ╰──────────────────────────────┴──────────────╯

在管道中使用元数据

metadata access 会用其输入的元数据运行一个闭包,而数据本身仍可通过 $in 获得:

{foo: bar} | to json --raw | metadata access {|meta| {in: $in, content: $meta.content_type}}
# => ╭─────────┬──────────────────╮
# => │ in      │ {"foo":"bar"}    │
# => │ content │ application/json │
# => ╰─────────┴──────────────────╯

窥探流

peek 会把流的前几个元素存进它的元数据里,这样你无需收集整个流就能查看它们:

seq 1 5 | peek 2 | metadata | get peek
# => ╭────────┬───────────╮
# => │ type   │ list      │
# => │ stream │ true      │
# => │        │ ╭───┬───╮ │
# => │ value  │ │ 0 │ 1 │ │
# => │        │ │ 1 │ 2 │ │
# => │        │ ╰───┴───╯ │
# => ╰────────┴───────────╯

HTTP 响应元数据

所有 HTTP 命令都会附加响应元数据:

http get https://example.com | metadata | get http_response.status
# => 200

关于在流式传输响应体时处理元数据,请参阅 HTTP 实用手册。

在GitHub上编辑此页面
Contributors: Ibraheem Ahmed, Justin Ma, Hofer-Julian, amtoine, 0x4D5352, Jan Klass, voyage200🍬, Jianjun Wang, passionworkeer
Prev
Dataframes
Next
创建你自己的错误