mirror of
https://github.com/nushell/nushell.git
synced 2025-05-29 06:17:54 +02:00
docs(std-rfc): use actual examples rather than doc comments (#15097)
# Description Update examples with attributes. # User-Facing Changes `std-rfc` commands now have examples. # Tests + Formatting N/A # After Submitting N/A
This commit is contained in:
Bahex
GitHub
parent
0430167f1c
commit
f7d5162582
@ -4,11 +4,9 @@
|
||||
# > Terminal multiplexers such as screen, tmux, zellij etc may interfere with this command
|
||||
|
||||
# Copy input to system clipboard
|
||||
#
|
||||
# # Example
|
||||
# ```nushell
|
||||
# >_ "Hello" | clip copy
|
||||
# ```
|
||||
@example "Copy a string to the clipboard" {
|
||||
"Hello" | clip copy
|
||||
}
|
||||
export def copy [
|
||||
--ansi (-a) # Copy ansi formatting
|
||||
]: any -> nothing {
|
||||
@ -35,12 +33,9 @@ export def copy [
|
||||
}
|
||||
|
||||
# Paste contents of system clipboard
|
||||
#
|
||||
# # Example
|
||||
# ```nushell
|
||||
# >_ clip paste
|
||||
# "Hello"
|
||||
# ```
|
||||
@example "Paste a string from the clipboard" {
|
||||
clip paste
|
||||
} --result "Hello"
|
||||
export def paste []: [nothing -> string] {
|
||||
try {
|
||||
term query $'(ansi osc)52;c;?(ansi st)' -p $'(ansi osc)52;c;' -t (ansi st)
|
||||
@ -56,9 +51,17 @@ export def paste []: [nothing -> string] {
|
||||
}
|
||||
|
||||
# Add a prefix to each line of the content to be copied
|
||||
#
|
||||
# # Example: Format output for Nushell doc
|
||||
# ls | clip prefix '# => ' | clip copy
|
||||
@example "Format output for Nushell doc" {
|
||||
[1 2 3] | clip prefix '# => '
|
||||
} --result "# => ╭───┬───╮
|
||||
# => │ 0 │ 1 │
|
||||
# => │ 1 │ 2 │
|
||||
# => │ 2 │ 3 │
|
||||
# => ╰───┴───╯
|
||||
# => "
|
||||
@example "Format output for Nushell doc and copy it" {
|
||||
ls | clip prefix '# => ' | clip copy
|
||||
}
|
||||
export def prefix [prefix: string]: any -> string {
|
||||
let input = $in | collect
|
||||
match ($input | describe -d | get type) {
|
||||
|
||||
@ -1,10 +1,9 @@
|
||||
# Convert a Nushell value to a list
|
||||
#
|
||||
# Primary useful for range-to-list, but other types are accepted as well.
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
# 1..10 | into list
|
||||
@example "Convert a range to a list" {
|
||||
1..10 | into list
|
||||
} --result [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
|
||||
export def "into list" []: any -> list {
|
||||
let input = $in
|
||||
let type = ($input | describe --detailed | get type)
|
||||
@ -17,104 +16,53 @@ export def "into list" []: any -> list {
|
||||
}
|
||||
|
||||
# Convert a list of columns into a table
|
||||
#
|
||||
# Examples:
|
||||
#
|
||||
# [
|
||||
# ([ 1 2 3 ] | wrap a)
|
||||
# ([ 4 5 6 ] | wrap b)
|
||||
# ([ 7 8 9 ] | wrap c)
|
||||
# ] | columns-into-table
|
||||
# => ╭───┬───┬───┬───╮
|
||||
# => │ # │ a │ b │ c │
|
||||
# => ├───┼───┼───┼───┤
|
||||
# => │ 0 │ 1 │ 4 │ 7 │
|
||||
# => │ 1 │ 2 │ 5 │ 8 │
|
||||
# => │ 2 │ 3 │ 6 │ 9 │
|
||||
# => ╰───┴───┴───┴───╯
|
||||
#
|
||||
# Can roundtrip with `table-into-columns`
|
||||
#
|
||||
# ls | table-into-columns | columns-into-table
|
||||
# => ╭───┬────────────────────────┬──────┬────────┬────────────────╮
|
||||
# => │ # │ name │ type │ size │ modified │
|
||||
# => ├───┼────────────────────────┼──────┼────────┼────────────────┤
|
||||
# => │ 0 │ into-list.nu │ file │ 378 B │ 40 minutes ago │
|
||||
# => │ 1 │ mod.nu │ file │ 28 B │ 41 minutes ago │
|
||||
# => │ 2 │ name-values.nu │ file │ 394 B │ 34 minutes ago │
|
||||
# => │ 3 │ record-into-columns.nu │ file │ 1.3 kB │ 27 minutes ago │
|
||||
# => ╰───┴────────────────────────┴──────┴────────┴────────────────╯
|
||||
@example "Construct a columns" {
|
||||
[
|
||||
([1, 2, 3] | wrap a)
|
||||
([4, 5, 6] | wrap b)
|
||||
([7, 8, 9] | wrap c)
|
||||
] | columns-into-table
|
||||
} --result [[a b c]; [1 4 7] [2 5 8] [3 6 9]]
|
||||
@example "Can roundtrip with `table-into-columns`" {
|
||||
ls | table-into-columns | columns-into-table
|
||||
}
|
||||
export def columns-into-table []: [list<table> -> table] {
|
||||
reduce {|it| merge $it}
|
||||
}
|
||||
|
||||
# Convert a record, where each value is a list, into a list of columns.
|
||||
# { a: [ 1 2 3 ], b: [ 4 5 6 ] } | record-into-columns
|
||||
# => ╭───┬───────────╮
|
||||
# => │ 0 │ ╭───┬───╮ │
|
||||
# => │ │ │ # │ a │ │
|
||||
# => │ │ ├───┼───┤ │
|
||||
# => │ │ │ 0 │ 1 │ │
|
||||
# => │ │ │ 1 │ 2 │ │
|
||||
# => │ │ │ 2 │ 3 │ │
|
||||
# => │ │ ╰───┴───╯ │
|
||||
# => │ 1 │ ╭───┬───╮ │
|
||||
# => │ │ │ # │ b │ │
|
||||
# => │ │ ├───┼───┤ │
|
||||
# => │ │ │ 0 │ 4 │ │
|
||||
# => │ │ │ 1 │ 5 │ │
|
||||
# => │ │ │ 2 │ 6 │ │
|
||||
# => │ │ ╰───┴───╯ │
|
||||
# => ╰───┴───────────╯
|
||||
# =>
|
||||
# This can be especially useful when combined with `columns-into-table`, as in:
|
||||
#
|
||||
# { a: [ 1 2 3 ], b: [ 4 5 6 ] } | record-into-columns
|
||||
# | columns-into-table
|
||||
# => ╭───┬───┬───╮
|
||||
# => │ # │ a │ b │
|
||||
# => ├───┼───┼───┤
|
||||
# => │ 0 │ 1 │ 4 │
|
||||
# => │ 1 │ 2 │ 5 │
|
||||
# => │ 2 │ 3 │ 6 │
|
||||
# => ╰───┴───┴───╯
|
||||
# =>
|
||||
@example "Convert record of lists into list of columns" {
|
||||
{ a: [1, 2, 3], b: [4, 5, 6] } | record-into-columns
|
||||
} --result [[[a]; [1], [2], [3]], [[b]; [4], [5], [6]]]
|
||||
@example "This can be especially useful when combined with `columns-into-table`" {
|
||||
{ a: [1, 2, 3], b: [4, 5, 6] } | record-into-columns | columns-into-table
|
||||
} --result [[a, b]; [1, 4], [2, 5], [3, 6]]
|
||||
export def record-into-columns []: [record -> list] {
|
||||
items {|key, val| $val | wrap $key}
|
||||
}
|
||||
|
||||
# Convert/split a table into a list of columns
|
||||
#
|
||||
# Examples:
|
||||
# ls | table-into-columns
|
||||
# => Returns a list of 4 tables, one for each of the `ls` columns
|
||||
#
|
||||
# Can be roundtripped with `columns-into-table`
|
||||
#
|
||||
# ls | table-into-columns | columns-into-table
|
||||
# => ╭───┬────────────────────────┬──────┬────────┬────────────────╮
|
||||
# => │ # │ name │ type │ size │ modified │
|
||||
# => ├───┼────────────────────────┼──────┼────────┼────────────────┤
|
||||
# => │ 0 │ into-list.nu │ file │ 378 B │ 40 minutes ago │
|
||||
# => │ 1 │ mod.nu │ file │ 28 B │ 41 minutes ago │
|
||||
# => │ 2 │ name-values.nu │ file │ 394 B │ 34 minutes ago │
|
||||
# => │ 3 │ record-into-columns.nu │ file │ 1.3 kB │ 27 minutes ago │
|
||||
# => ╰───┴────────────────────────┴──────┴────────┴────────────────╯
|
||||
@example "Return a list of 4 tables, one for each of the `ls` columns" {
|
||||
ls | table-into-columns
|
||||
}
|
||||
@example "Can be roundtripped with `columns-into-table`" {
|
||||
ls | table-into-columns | columns-into-table
|
||||
} --result [
|
||||
[name, type, size, modified];
|
||||
["into-list.nu", file, "378 B", 2025-02-09T20:52:38+03:00],
|
||||
["mod.nu", file, "28 B", 2025-02-09T20:51:38+03:00],
|
||||
["name-values.nu", file, "394 B", 2025-02-09T20:58:38+03:00],
|
||||
["record-into-columns.nu", file, "1.3 kB", 2025-02-09T21:05:38+03:00]
|
||||
]
|
||||
export def table-into-columns []: [table -> list<table>] {
|
||||
let IN = $in
|
||||
$IN | columns | each {|col| $IN | select $col}
|
||||
}
|
||||
|
||||
# Assign keynames to a list of values, effectively converting the list to a record.
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
# [ 1 2 3 ] | name-values a b c
|
||||
# => ╭───┬───╮
|
||||
# => │ a │ 1 │
|
||||
# => │ b │ 2 │
|
||||
# => │ c │ 3 │
|
||||
# => ╰───┴───╯
|
||||
@example "Name the items in a list" {
|
||||
[1, 2, 3] | name-values a b c
|
||||
} --result {a: 1, b: 2, c: 3}
|
||||
export def name-values [...names: string]: [list -> record] {
|
||||
let IN = $in
|
||||
0.. | zip $IN | into record | rename ...$names
|
||||
|
||||
@ -16,13 +16,15 @@
|
||||
#
|
||||
# If the key already exists, it is updated
|
||||
# to the new value provided.
|
||||
#
|
||||
# Usage:
|
||||
# <input> | kv set <key> <value?>
|
||||
#
|
||||
# Example:
|
||||
# ls ~ | kv set "home snapshot"
|
||||
# kv set foo 5
|
||||
@example "Store the list of files in the home directory" {
|
||||
ls ~ | kv set "home snapshot"
|
||||
}
|
||||
@example "Store a number" {
|
||||
kv set foo 5
|
||||
}
|
||||
@example "Update a number" {
|
||||
kv set foo { $in + 1 }
|
||||
}
|
||||
export def "kv set" [
|
||||
key: string
|
||||
value_or_closure?: any
|
||||
@ -97,9 +99,9 @@ export def "kv set" [
|
||||
#
|
||||
# Counterpart of "kv set". Returns null
|
||||
# if the key is not found.
|
||||
#
|
||||
# Usage:
|
||||
# kv get <key> | <pipeline>
|
||||
@example "Retrieve a stored value" {
|
||||
kv get foo
|
||||
}
|
||||
export def "kv get" [
|
||||
key: string # Key of the kv-pair to retrieve
|
||||
--universal (-u)
|
||||
|
||||
@ -5,25 +5,20 @@ def with-field [field: string, value: string] {
|
||||
| path join
|
||||
}
|
||||
|
||||
alias "path with-extension" = with-extension
|
||||
|
||||
# Replace extension of input file paths.
|
||||
#
|
||||
# Note that it doesn't change the file name locally.
|
||||
#
|
||||
# # Example
|
||||
# - setting path ext to `rs`
|
||||
# ```nushell
|
||||
# > "ab.txt" | path with-extension "rs"
|
||||
# ab.rs
|
||||
# > "ab.txt" | path with-extension ".rs"
|
||||
# ab.rs
|
||||
#
|
||||
# - setting a list of input path ext to `rs`
|
||||
# > ["ab.txt", "cd.exe"] | path with-extension "rs"
|
||||
# ╭───┬──────────╮
|
||||
# │ 0 │ ab.rs │
|
||||
# │ 1 │ cd.rs │
|
||||
# ╰───┴──────────╯
|
||||
# ```
|
||||
@example "setting path ext to `rs`" {
|
||||
"ab.txt" | path with-extension "rs"
|
||||
} --result ab.rs
|
||||
@example "leading dot can be included" {
|
||||
"ab.txt" | path with-extension ".rs"
|
||||
} --result ab.rs
|
||||
@example "setting a list of input path ext to `rs`" {
|
||||
["ab.txt", "cd.exe"] | path with-extension "rs"
|
||||
} --result [ab.rs, cd.rs]
|
||||
export def with-extension [ext: string] {
|
||||
let path = $in
|
||||
let ext_trim = if $ext starts-with "." {
|
||||
@ -34,38 +29,26 @@ export def with-extension [ext: string] {
|
||||
$path | with-field extension $ext_trim
|
||||
}
|
||||
|
||||
alias "path with-stem" = with-stem
|
||||
|
||||
# Replace stem of input file paths.
|
||||
#
|
||||
# Note that it doesn't change the file name locally.
|
||||
#
|
||||
# # Example
|
||||
# - replace stem with "share"
|
||||
# ```nushell
|
||||
# > "/usr/bin" | path with-stem "share"
|
||||
# /usr/share
|
||||
#
|
||||
# - replace stem with "nushell"
|
||||
# > ["/home/alice/", "/home/bob/secret.txt"] | path with-stem "nushell"
|
||||
# ╭───┬───────────────────────╮
|
||||
# │ 0 │ /home/nushell │
|
||||
# │ 1 │ /home/bob/nushell.txt │
|
||||
# ╰───┴───────────────────────╯
|
||||
# ```
|
||||
@example "replace stem with 'share'" {
|
||||
"/usr/bin" | path with-stem "share"
|
||||
} --result /usr/share
|
||||
@example "replace stem with 'nushell'" {
|
||||
["/home/alice/", "/home/bob/secret.txt"] | path with-stem "nushell"
|
||||
} --result [/home/nushell, /home/bob/nushell.txt]
|
||||
export def with-stem [stem: string] { with-field stem $stem }
|
||||
|
||||
alias "path with-parent" = with-parent
|
||||
|
||||
# Replace parent field of input file paths.
|
||||
#
|
||||
# # Example
|
||||
# - replace parent path with `/usr/share`
|
||||
# ```nushell
|
||||
# > "/etc/foobar" | path with-parent "/usr/share/"
|
||||
# /usr/share/foobar
|
||||
#
|
||||
# - replace parent path with `/root/` for all filenames in list
|
||||
# > ["/home/rose/meow", "/home/fdncred/"] | path with-parent "/root/"
|
||||
# ╭───┬───────────────╮
|
||||
# │ 0 │ /root/meow │
|
||||
# │ 1 │ /root/fdncred │
|
||||
# ╰───┴───────────────╯
|
||||
# ```
|
||||
@example "replace parent path with `/usr/share`" {
|
||||
"/etc/foobar" | path with-parent "/usr/share/"
|
||||
} --result "/usr/share/foobar"
|
||||
@example "replace parent path with `/root/` for all filenames in list" {
|
||||
["/home/rose/meow", "/home/fdncred/"] | path with-parent "/root/"
|
||||
} --result [/root/meow, /root/fdncred]
|
||||
export def with-parent [parent: string] { with-field parent $parent }
|
||||
|
||||
@ -1,21 +1,19 @@
|
||||
alias "str dedent" = dedent
|
||||
|
||||
# Removes common indent from a multi-line string based on the number of spaces on the last line.
|
||||
#
|
||||
# Example - Two leading spaces are removed from all lines:
|
||||
#
|
||||
# > let s = "
|
||||
# Heading
|
||||
# Indented Line
|
||||
# Another Indented Line
|
||||
#
|
||||
# Another Heading
|
||||
# "
|
||||
# > $a | str dedent
|
||||
#
|
||||
# # => Heading
|
||||
# # => Indented Line
|
||||
# # => Another Indented Line
|
||||
# # =>
|
||||
# # => Another Heading
|
||||
@example "Two leading spaces are removed from all lines" {
|
||||
"
|
||||
Heading
|
||||
Indented Line
|
||||
Another Indented Line
|
||||
|
||||
Another Heading
|
||||
" | str dedent
|
||||
} --result "Heading
|
||||
Indented Line
|
||||
Another Indented Line
|
||||
|
||||
Another Heading"
|
||||
export def dedent [
|
||||
--tabs (-t)
|
||||
]: string -> string {
|
||||
@ -76,25 +74,22 @@ export def dedent [
|
||||
| str join (char line_sep)
|
||||
}
|
||||
|
||||
alias "str unindent" = unindent
|
||||
|
||||
# Remove common indent from a multi-line string based on the line with the smallest indent
|
||||
#
|
||||
# Example - Two leading spaces are removed from all lines:
|
||||
#
|
||||
# > let s = "
|
||||
# Heading
|
||||
# Indented Line
|
||||
# Another Indented Line
|
||||
#
|
||||
# Another Heading
|
||||
# "
|
||||
# > $a | str dedent
|
||||
#
|
||||
# # => Heading
|
||||
# # => Indented Line
|
||||
# # => Another Indented Line
|
||||
# # =>
|
||||
# # => Another Heading
|
||||
#
|
||||
@example "Two leading spaces are removed from all lines" {
|
||||
"
|
||||
Heading
|
||||
Indented Line
|
||||
Another Indented Line
|
||||
|
||||
Another Heading
|
||||
" | str unindent
|
||||
} --result "Heading
|
||||
Indented Line
|
||||
Another Indented Line
|
||||
|
||||
Another Heading"
|
||||
export def unindent [
|
||||
--tabs (-t) # String uses tabs instead of spaces for indentation
|
||||
]: string -> string {
|
||||
|
||||
@ -1,23 +1,15 @@
|
||||
# Run aggregate operations on output of `group-by --to-table`.
|
||||
#
|
||||
# # Example
|
||||
#
|
||||
# - group files by type and extension, and get stats about their sizes
|
||||
# ```nushell
|
||||
# >_ ls | group-by type { get name | path parse | get extension } --to-table | aggregate size
|
||||
# ```
|
||||
#
|
||||
# - group data by multiple columns, and run custom aggregate operations
|
||||
# ```nushell
|
||||
# >_ open movies.csv
|
||||
# | group-by Lead_Studio Genre --to-table
|
||||
# | aggregate Worldwide_Gross Profitability --ops {avg: {math avg}, std: {math stddev}}
|
||||
# ```
|
||||
#
|
||||
# - run aggregate operations without grouping the input
|
||||
# ```nushell
|
||||
# >_ open movies.csv | aggregate Year
|
||||
# ```
|
||||
@example "group files by type and extension, and get stats about their sizes" {
|
||||
ls | group-by type { get name | path parse | get extension } --to-table | aggregate size
|
||||
}
|
||||
@example "group data by multiple columns, and run custom aggregate operations" {
|
||||
open movies.csv
|
||||
| group-by Lead_Studio Genre --to-table
|
||||
| aggregate Worldwide_Gross Profitability --ops {avg: {math avg}, std: {math stddev}}
|
||||
}
|
||||
@example "run aggregate operations without grouping the input" {
|
||||
open movies.csv | aggregate Year
|
||||
}
|
||||
export def aggregate [
|
||||
--ops: record, # default = {min: {math min}, avg: {math avg}, max: {math max}, sum: {math sum}}
|
||||
...columns: cell-path, # columns to perform aggregations on
|
||||
@ -161,16 +153,12 @@ def row-indices [ ...slices ] {
|
||||
}
|
||||
|
||||
# Selects one or more rows while keeping the original indices.
|
||||
#
|
||||
# Example - Selects the first, fifth, and sixth rows from the table:
|
||||
#
|
||||
# ls / | select slices 0 4..5
|
||||
#
|
||||
# Example - Select the 4th row.
|
||||
#
|
||||
# Note that the difference between this and `select 3` is that the index (#) column shows the *original* (pre-select) position in the table.
|
||||
#
|
||||
# ls | select slices 3
|
||||
@example "Selects the first, fifth, and sixth rows from the table" {
|
||||
ls / | select slices 0 4..5
|
||||
}
|
||||
@example "Select the 4th row (difference to `select 3` is that the index (#) column shows the *original* (pre-select) position in the table)" {
|
||||
ls | select slices 3
|
||||
}
|
||||
export def "select slices" [ ...slices ] {
|
||||
enumerate
|
||||
| flatten
|
||||
@ -178,10 +166,9 @@ export def "select slices" [ ...slices ] {
|
||||
}
|
||||
|
||||
# Rejects one or more rows while keeping the original indices.
|
||||
#
|
||||
# Example - Rejects the first, fifth, and sixth rows from the table:
|
||||
#
|
||||
# ls / | reject slices 0 4..5
|
||||
@example "Rejects the first, fifth, and sixth rows from the table" {
|
||||
ls / | reject slices 0 4..5
|
||||
}
|
||||
export def "reject slices" [ ...slices ] {
|
||||
enumerate
|
||||
| flatten
|
||||
@ -190,17 +177,14 @@ export def "reject slices" [ ...slices ] {
|
||||
}
|
||||
|
||||
# Select one or more columns by their indices
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
# ls -l | select column-slices 0 10..12 | first 3
|
||||
# # => ╭───┬────────────────────┬──────────────┬─────────────┬──────────────╮
|
||||
# # => │ # │ name │ created │ accessed │ modified │
|
||||
# # => ├───┼────────────────────┼──────────────┼─────────────┼──────────────┤
|
||||
# # => │ 0 │ CITATION.cff │ 3 months ago │ 4 hours ago │ 3 months ago │
|
||||
# # => │ 1 │ CODE_OF_CONDUCT.md │ 7 months ago │ 4 hours ago │ 7 months ago │
|
||||
# # => │ 2 │ CONTRIBUTING.md │ 3 months ago │ 4 hours ago │ 3 months ago │
|
||||
# # => ╰───┴────────────────────┴──────────────┴─────────────┴──────────────╯
|
||||
@example "Select column [0, 10, 11, 12]" {
|
||||
ls -l | select column-slices 0 10..12 | first 3
|
||||
} --result [
|
||||
[name, created, accessed, modified];
|
||||
["CITATION.cff", 2024-11-09T21:58:12+03:00, 2025-02-09T17:58:12+03:00, 2024-11-09T21:58:12+03:00],
|
||||
["CODE_OF_CONDUCT.md", 2024-07-09T21:58:12+03:00, 2025-02-09T17:58:12+03:00, 2024-07-09T21:58:12+03:00],
|
||||
["CONTRIBUTING.md", 2024-11-09T21:58:12+03:00, 2025-02-09T17:58:12+03:00, 2024-11-09T21:58:12+03:00]
|
||||
]
|
||||
export def "select column-slices" [
|
||||
...slices
|
||||
] {
|
||||
@ -209,10 +193,9 @@ export def "select column-slices" [
|
||||
}
|
||||
|
||||
# Reject one or more columns by their indices
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
# ls | reject column-slices 0 4 5 | first 3
|
||||
@example "Reject columns [0, 4, 5]" {
|
||||
ls | reject column-slices 0 4 5 | first 3
|
||||
}
|
||||
export def "reject column-slices" [
|
||||
...slices
|
||||
] {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user