filled out custom command section of nushell post.

This commit is contained in:
Gabe Venberg 2024-03-10 18:40:13 -05:00
parent e763ca78ed
commit 48894db4a6

View file

@ -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. line, its still quite easy and straightforward to write.
Most log formats and command outputs are similarly straightforward. 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 ## Error messages
Nushell brings with it great, self explanatory error messages.
For example, if we do this:
## Whats not there yet ## Whats not there yet
Now, nushell is not finished yet. Now, nushell is not finished yet.