add command signature section (nushell#671)

* add command signature section * update doc * Update book/command_signature.md Co-authored-by: Stefan Holderbach <[email protected]> * Update book/command_signature.md Co-authored-by: Stefan Holderbach <[email protected]> * Update book/programming_in_nu.md Co-authored-by: Stefan Holderbach <[email protected]>
webwurst · Dec 2, 2022 · dca2e83 · dca2e83
1 parent 2898aa2
commit dca2e83
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 0 deletions.
diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts
@@ -44,6 +44,7 @@ export const sidebarEn: SidebarConfig = {
  '/book/scripts.md',
  '/book/modules.md',
  '/book/overlays.md',
+ '/book/command_signature.md'
  ],
  },
  {

diff --git a/book/command_signature.md b/book/command_signature.md
@@ -0,0 +1,24 @@
+# Command signature
+
+nu commands contains a signature section, take `str distance` as example, the signature is like this:
+
+```
+Signatures(Cell paths are supported):
+ <string> | str distance <string> -> <int>
+```
+
+The first type name before `|` describes the type of input pipeline. The command name is followed by the required argument type(s) for the command. The output type is `int` and given after `->`.
+
+`(Cell paths are supported)` indicates that you can provide cell paths for `str distance` to apply an operation at the given cell path(s) in a nested structure or table, and replace the column or field with the result, like: `ls | str distance 'nushell' 'name'`
+
+Here is another one example, `str join`:
+
+```
+Signatures:
+ list<string> | str join <string?> -> <string>
+```
+
+It says that `str join` command expect input pipeline is a list of string, and take optional `string` type argument, finally the output type is `string`.
+
+Some commands don't accept or require data through the input pipeline, thus the input type will be `<nothing>`.
+The same is true for the output type if the command returns `null` (e.g. `rm`).
diff --git a/book/programming_in_nu.md b/book/programming_in_nu.md
@@ -24,3 +24,5 @@ Modules let you define a public interface vs. private commands and you can impor
 [Overlays](overlays.md) build on top of modules.
 By defining an overlay, you bring in module's definitions into its own swappable "layer" that gets applied on top of other overlays.
 This enables features like activating virtual environments or overriding sets of default commands with custom variants.
+
+The help message of some built-in commands shows a [signature](command_signature.md). You can take a look at it to get general rules how the command can be used.