From f7d5162582314a6d8a10eff978fdb2c9f59a6af6 Mon Sep 17 00:00:00 2001 From: Bahex Date: Wed, 12 Feb 2025 01:33:27 +0300 Subject: [PATCH] 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 --- crates/nu-std/std-rfc/clip/mod.nu | 31 +++--- crates/nu-std/std-rfc/conversions/mod.nu | 120 +++++++---------------- crates/nu-std/std-rfc/kv/mod.nu | 22 +++-- crates/nu-std/std-rfc/path/mod.nu | 71 +++++--------- crates/nu-std/std-rfc/str/mod.nu | 65 ++++++------ crates/nu-std/std-rfc/tables/mod.nu | 79 ++++++--------- 6 files changed, 151 insertions(+), 237 deletions(-) diff --git a/crates/nu-std/std-rfc/clip/mod.nu b/crates/nu-std/std-rfc/clip/mod.nu index 2c48562783..60e8d0fefe 100644 --- a/crates/nu-std/std-rfc/clip/mod.nu +++ b/crates/nu-std/std-rfc/clip/mod.nu @@ -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) { diff --git a/crates/nu-std/std-rfc/conversions/mod.nu b/crates/nu-std/std-rfc/conversions/mod.nu index 2d18699164..586597276f 100644 --- a/crates/nu-std/std-rfc/conversions/mod.nu +++ b/crates/nu-std/std-rfc/conversions/mod.nu @@ -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] { 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
] { 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 diff --git a/crates/nu-std/std-rfc/kv/mod.nu b/crates/nu-std/std-rfc/kv/mod.nu index d01f2f6238..30088dba4d 100644 --- a/crates/nu-std/std-rfc/kv/mod.nu +++ b/crates/nu-std/std-rfc/kv/mod.nu @@ -16,13 +16,15 @@ # # If the key already exists, it is updated # to the new value provided. -# -# Usage: -# | kv set -# -# 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 | +@example "Retrieve a stored value" { + kv get foo +} export def "kv get" [ key: string # Key of the kv-pair to retrieve --universal (-u) diff --git a/crates/nu-std/std-rfc/path/mod.nu b/crates/nu-std/std-rfc/path/mod.nu index 791e83a395..2cc1458016 100644 --- a/crates/nu-std/std-rfc/path/mod.nu +++ b/crates/nu-std/std-rfc/path/mod.nu @@ -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 } diff --git a/crates/nu-std/std-rfc/str/mod.nu b/crates/nu-std/std-rfc/str/mod.nu index 49dc1abc6a..4c9995594f 100644 --- a/crates/nu-std/std-rfc/str/mod.nu +++ b/crates/nu-std/std-rfc/str/mod.nu @@ -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 { diff --git a/crates/nu-std/std-rfc/tables/mod.nu b/crates/nu-std/std-rfc/tables/mod.nu index 6ec8f4010d..96a5e11845 100644 --- a/crates/nu-std/std-rfc/tables/mod.nu +++ b/crates/nu-std/std-rfc/tables/mod.nu @@ -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 ] {