Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
  • Introduction
  • Installation
    • Default Shell
  • Getting Started
    • Quick Tour
    • Moving Around the System
    • Thinking in Nu
    • Nushell Cheat Sheet
  • Nu Fundamentals
    • Types of Data
    • Loading Data
    • Data Formats
    • Working with SQLite
    • Pipelines
    • Working with Strings
    • Regular Expressions
    • Working with Binary Data
    • Working with Lists
    • Working with Records
    • Working with Numbers
    • Working with Tables
    • Working with Paths
    • Navigating and Accessing Structured Data
    • Special Variables
  • Programming in Nu
    • Custom Commands
    • Aliases
    • Operators
    • Variables
    • Control Flow
    • Scripts
    • Modules
      • Using Modules
      • Creating Modules
    • Overlays
    • Sorting
    • Testing your Nushell Code
    • Debugging Scripts
    • Language Server
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Configuration Reference
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Working with the Terminal
    • Running System (External) Commands
    • How to Configure 3rd Party Prompts
    • Directory Stack
    • Reedline, Nu's Line Editor
    • Custom Completions
    • Externs
    • Coloring and Theming in Nu
    • Hooks
    • Background Jobs
  • Coming to Nu
    • Coming from Bash
    • Coming from CMD.EXE
    • Coming from PowerShell
    • Nu map from other shells and domain specific languages
    • Nu Map from Imperative Languages
    • Nu Map from Functional Languages
    • Nushell operator map
  • Design Notes
    • How Nushell Code Gets Run
  • (Not So) Advanced
    • Standard Library
      • std/assert
      • std/bench
      • std/clip
      • std/config
      • std/dt
      • std/formats
      • std/help
      • std/input
      • std/iter
      • std/log
      • std/math
      • std/random
      • std/util
      • std/xml
      • std-rfc
    • Dataframes
      • Dataframe Operations
      • Column Selectors
      • Math Expressions
      • String Expressions
      • Dates and Times in Dataframes
      • Masks and Conditionals
      • Aggregations and Window Functions
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore
    • Building TUIs with tui
    • MCP Server

std/xml

The std/xml module reads and changes XML data in the form that from xml produces and to xml accepts. In that form, every entry is a record with tag, attributes and content fields. A tag's content is a list of entries, and a text entry has a null tag and its text as content. Import the commands without a prefix:

use std/xml *

The examples on this page use a file books.xml with this content:

<library>
  <book lang="en"><title>Dune</title><year>1965</year></book>
  <book lang="fr"><title>Vendredi</title><year>1967</year></book>
</library>
  • Paths
  • xaccess
  • xupdate
  • xinsert
  • xtype

Paths

xaccess, xupdate and xinsert find entries with a path, a list of steps loosely modeled on XPath. The first step applies to the root element itself, and each later step works on the entries that the step before it selected. There are four kinds of step:

StepSelects
A tag namethe children with that tag, like child::name in XPath
'*'all children, whatever their tag, including text entries
An integerthe entry at that position among the current selection, counting from 0
A closurethe entries of the current selection for which the closure returns true

* selects only the direct children, not their descendants. A closure receives each entry as its parameter.

xaccess

xaccess returns the entries that a path selects:

open books.xml | xaccess [library book title *] | get content
# => ╭───┬──────────╮
# => │ 0 │ Dune     │
# => │ 1 │ Vendredi │
# => ╰───┴──────────╯

library selects the root, book its two book children, title their titles, and * the text inside each title. An integer step picks one entry, and a closure filters the selection:

open books.xml | xaccess [library book 1 title *] | get content
# => ╭───┬──────────╮
# => │ 0 │ Vendredi │
# => ╰───┴──────────╯
open books.xml | xaccess [library book {|b| $b.attributes.lang == "fr" } year *] | get content
# => ╭───┬──────╮
# => │ 0 │ 1967 │
# => ╰───┴──────╯

When a step selects nothing, xaccess returns an empty list. A first step that doesn't match the root's tag selects nothing, so xaccess [book] returns []. An integer past the end of the selection is an error, Row number too large. A step of any other type, such as a float, fails with Incorrect path step type. The path can't be empty:

open books.xml | xaccess []
# => Error: nu::shell::error
# =>
# =>   × Empty path provided
# =>    ╭─[repl_entry #1:1:26]
# =>  1 │ open books.xml | xaccess []
# =>    ·                          ─┬
# =>    ·                           ╰── Use a non-empty  list of path steps
# =>    ╰────

xupdate

xupdate takes a path and a closure. It calls the closure once for each entry that the path selects, puts whatever the closure returns in that entry's place, and returns the whole document:

open books.xml | xupdate [library book year *] {|t| $t | update content { into int | $in + 1 | into string } } | to xml
# => <library><book lang="en"><title>Dune</title><year>1966</year></book><book lang="fr"><title>Vendredi</title><year>1968</year></book></library>

The closure gets the entry as its parameter and must return an entry, a record that to xml accepts.

xinsert

xinsert adds a new entry to the content of each tag that a path selects. It takes the path, the new entry and an optional position. Without a position, the entry goes at the end of the content. With one, it goes at that index, counting from 0, and a position past the end means the end:

open books.xml | xinsert [library book 0] {tag: author, attributes: {}, content: ["Frank Herbert"]} 1 | to xml
# => <library><book lang="en"><title>Dune</title><author>Frank Herbert</author><year>1965</year></book><book lang="fr"><title>Vendredi</title><year>1967</year></book></library>

Only tags have content to insert into. If the path selects a text entry, a comment or a processing instruction, xinsert fails with Can insert entry only into content of a tag node.

xtype

xtype returns the kind of the entry it receives: tag, text, comment, or pi for a processing instruction. A plain string also counts as text. Comments and processing instructions appear only when from xml keeps them with --keep-comments and --keep-pi:

"<r><?target data?><!-- note --><a>text</a>tail</r>" | from xml --keep-comments --keep-pi | get content | each { xtype } | to nuon
# => [pi, comment, tag, text]

Input that isn't an XML entry, such as {a: 1}, is an error, Not an xml emtry.

The std-rfc/xml module has a different xaccess, with another path syntax.

Edit this page on GitHub
Contributors: fdncred
Prev
std/util
Next
std-rfc