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/formats

The std/formats module adds from and to commands for three line-based formats, in which each line of the text is one value:

FormatCommandsEach line holdsContent type
JSONLfrom jsonl, to jsonlone JSON valueapplication/jsonl
NDJSONfrom ndjson, to ndjsonone JSON valueapplication/x-ndjson
NDNUONfrom ndnuon, to ndnuonone NUON valueapplication/x-ndnuon

JSON Lines and NDJSON describe the same format, and their commands behave the same. Only the content type that to sets in the pipeline metadata differs.

Import the module with a glob:

use std/formats *

The glob matters. open parses a file by calling the from command named after its extension, and save calls the matching to command. After use std/formats *, from jsonl and the others are in scope under those names, so open and save handle .jsonl, .ndjson and .ndnuon files:

[{name: a, size: 1} {name: b, size: 2}] | save data.jsonl
open data.jsonl
# => ╭───┬──────┬──────╮
# => │ # │ name │ size │
# => ├───┼──────┼──────┤
# => │ 0 │ a    │    1 │
# => │ 1 │ b    │    2 │
# => ╰───┴──────┴──────╯
open --raw data.jsonl
# => {"name":"a","size":1}
# => {"name":"b","size":2}

After use std/formats without the glob, the commands are named formats from jsonl and so on, and open data.jsonl returns the file's contents unparsed. Without either import, save data.jsonl fails, because no to jsonl command exists.

JSON Lines and NDJSON

from jsonl and from ndjson are the same as from json --objects. They parse each line as a JSON value and return a list of the values, skipping blank lines. A line that isn't valid JSON, such as {bad, makes the whole conversion fail with Error while parsing JSON text. The parser is lenient about bare words, though, so a line such as not json comes back as the string not json.

to jsonl and to ndjson write each item of a list as compact JSON on its own line, with a newline after every line, including the last. A single record or other value that isn't a list becomes one line, with no newline after it.

NDNUON

from ndnuon and to ndnuon do the same with NUON, so values keep Nushell types that JSON doesn't have, such as file sizes, durations and dates. to nuon writes a string that contains a newline with a real line break in it, which would split the value across two lines. to ndnuon replaces each line break inside a value with the two characters \n, which NUON reads back as a newline:

[{name: "two\nlines"}, [1 2]] | to ndnuon
# => {name: "two\nlines"}
# => [1, 2]
[{name: "two\nlines"}, [1 2]] | to ndnuon | from ndnuon | get 0.name
# => two
# => lines

from ndnuon skips blank lines too.

Edit this page on GitHub
Contributors: fdncred
Prev
std/dt
Next
std/help