From 48894db4a66dbd9ffa6dcb9c47a2acaa4ef470a0 Mon Sep 17 00:00:00 2001 From: Gabe Venberg Date: Sun, 10 Mar 2024 18:40:13 -0500 Subject: [PATCH] filled out custom command section of nushell post. --- content/posts/nushell.md | 136 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 132 insertions(+), 4 deletions(-) diff --git a/content/posts/nushell.md b/content/posts/nushell.md index 40db913..7522a65 100644 --- a/content/posts/nushell.md +++ b/content/posts/nushell.md @@ -136,16 +136,144 @@ While it would be a pretty long one liner if we decided to put it in a single line, its still quite easy and straightforward to write. Most log formats and command outputs are similarly straightforward. -## Defining custom commands +## Defining custom commands, with built in arg parsing -// show the basic syntax for custom commands +Nushell has a feature called Custom Commands, which fill the same purpose as +functions in other shells/programming languages, but are a bit more featurefull +than traditional POSIX shell functions. -### Built in arg parsing? +First of all, nushell custom commands specify the number of positional arguments +they take. -// show syntax for custom args, and how it leads to auto completion and help generation. +{{}} +def recently-modified [cutoff] { +# show all files recurisively that were modified after a specified cutoff + # show all files recurisively that were modified after a specified cutoff + ls **/* | where modified > ( + # create timestamp from input + $cutoff | into datetime + ) +} +{{}} + +You can optionally give the arguments a type + +{{}} +def recently-modified [cutoff: string] { +# show all files recurisively that were modified after a specified cutoff + # show all files recurisively that were modified after a specified cutoff + ls **/* | where modified > ( + # create timestamp from input + $cutoff | into datetime + ) +} +{{}} + +You can give the arguments a default value, making it optional, (can be combined +with a type specification) + +{{}} +def recently-modified [cutoff = '1 week ago'] { + # show all files recurisively that were modified after a specified cutoff + ls **/* | where modified > ( + # create timestamp from input + $cutoff | into datetime + ) +} +{{}} + +You have flag parsing, complete with short flags, is included as well. (A +flag without a type will be taken as a boolean flag, set by its presence or +absence) + +{{}} +def recently-modified [cutoff: string = '1 week ago' --older-than (-o)] { + if $older_than { + # show all files recurisively that were modified after a specified cutoff + ls **/* | where modified > ( + # create timestamp from input + $cutoff | into datetime + ) + } else { + # show all files recurisively that were modified before a specified cutoff + ls **/* | where modified < ( + # create timestamp from input + $cutoff | into datetime + ) + } +} +{{}} + +And finally, you can add a rest command at the end, allowing you to take a variable number of +arguments. +{{}} +def recently-modified [--cutoff = '1 week ago' ...paths] { + for $path in $paths { + # show all files recurisively that were modified after a specified cutoff + ls $path | where modified > ( + # create timestamp from input + $cutoff | into datetime + ) + } +} +{{}} + +All of the specified parameters are automatically added to a generated `--help` +page, along with a documentation comments, so that the following code block: + +{{}} +# display recently modified files +def recently-modified [ + --cutoff = '1 week ago' # cutoff to be considered 'recently modified' + ...paths # paths to consider +] { + for $path in $paths { + # show all files recurisively that were modified after a specified cutoff + ls $path | where modified > ( + # create timestamp from input + $cutoff | into datetime + ) + } +} +{{}} + +Results in a help page that looks like this. + +``` +> recently-modified --help +display recently modified files + +Usage: + > recently-modified {flags} ...(paths) + +Flags: + --cutoff - cutoff to be considered 'recently modified' (default: '1 week ago') + -h, --help - Display the help message for this command + +Parameters: + ...paths : paths to consider + +Input/output types: + ╭───┬───────┬────────╮ + │ # │ input │ output │ + ├───┼───────┼────────┤ + │ 0 │ any │ any │ + ╰───┴───────┴────────╯ +``` + +(the input/output table at the bottom has to do with how the command is used in +a pipeline, and is covered in more detail in the +[book](https://www.nushell.sh/book/command_signature.html) + +This addition of easy argument parsing makes it incredibly convenient to add +command line arguments to your scripts and functions, something that is anything +but easy in POSIX shells. ## Error messages +Nushell brings with it great, self explanatory error messages. +For example, if we do this: + ## Whats not there yet Now, nushell is not finished yet.