From 48894db4a66dbd9ffa6dcb9c47a2acaa4ef470a0 Mon Sep 17 00:00:00 2001
From: Gabe Venberg <gabevenberg@gmail.com>
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.
+{{<highlight sh>}}
+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
+    )
+}
+{{</highlight>}}
+
+You can optionally give the arguments a type
+
+{{<highlight sh>}}
+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
+    )
+}
+{{</highlight>}}
+
+You can give the arguments a default value, making it optional, (can be combined
+with a type specification)
+
+{{<highlight sh>}}
+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
+    )
+}
+{{</highlight>}}
+
+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)
+
+{{<highlight sh>}}
+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
+        )
+    }
+}
+{{</highlight>}}
+
+And finally, you can add a rest command at the end, allowing you to take a variable number of
+arguments.
+{{<highlight sh>}}
+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
+        )
+    }
+}
+{{</highlight>}}
+
+All of the specified parameters are automatically added to a generated `--help`
+page, along with a documentation comments, so that the following code block:
+
+{{<highlight sh>}}
+# 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
+        )
+    }
+}
+{{</highlight>}}
+
+Results in a help page that looks like this.
+
+```
+> recently-modified --help
+display recently modified files
+
+Usage:
+  > recently-modified {flags} ...(paths) 
+
+Flags:
+  --cutoff <String> - cutoff to be considered 'recently modified' (default: '1 week ago')
+  -h, --help - Display the help message for this command
+
+Parameters:
+  ...paths <any>: 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.