From 8a3d8c344910d7ee26dae6b19885d1c80e277820 Mon Sep 17 00:00:00 2001 From: "Rico Sta. Cruz" Date: Thu, 23 Dec 2021 09:29:34 +1100 Subject: [PATCH] Update fish.md (formatted from #1758) (#1764) Co-authored-by: EmilySeville7cfg --- fish-shell.md | 308 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 199 insertions(+), 109 deletions(-) diff --git a/fish-shell.md b/fish-shell.md index ec4c8b90..fc48c79f 100644 --- a/fish-shell.md +++ b/fish-shell.md @@ -9,41 +9,81 @@ weight: -1 ### Keys -| Shortcut | Description | -| --- | --- | -| `^A ←` _/_ `^E →` | Move to line beginning/end | -| `Alt ←` _/_ `Alt →` | Move word | -| `^U` | Delete to beginning | -| `^W` | Delete to previous `/` | -| `^D` | Delete next character | -| `Alt D` | Delete next word | -| `^C` | Cancel line | -| `Alt P` | Page output | -| --- | --- | -| `Alt ↑` _/_ `Alt ↓` | Previous _/_ next arguments | -| `Alt E` _/_ `Alt V` | Open in external editor | -| `^L` | Repaint screen | -{: .-shortcuts} +| Shortcut | Description | +| --- | --- | +| `^A ←`/`^E →` | Move to the line beginning/end | +| `Alt ←`/`Alt →` | Jump to the previous/next word | +| `↑`/`↓` | Switch to the previous/next command | +| `Alt ↑`/`Alt ↓` | Switch to the previous/next arguments | +| --- | --- | +| `^U` | Delete to the beginning | +| `^C` | Cancel the line | +| --- | --- | +| `Alt H` | Show the command man page description | +| `Alt W` | Show the short command description | -### Help +### Sample program -| `Alt H` | Help on word (man) | -| `Alt W` | Help on word (short descriptions) | -| `Alt L` | List directory on cursor | -{: .-shortcuts} +```fish +#!/usr/bin/env fish + +echo 'Hello from Fish!' +``` + +### Comments + +```fish +# my comment +``` + +### Printing text + +```fish +echo 'Hello from Fish!' +# or +printf '%s\n' 'Hello from Fish!' +``` + +Print the string with a trailing `\n`. + +### Reading from stdin + +```fish +read my_variable +``` + +Reads the string to a variable `my_variable`. + +### Loops + +```fish +for i in (seq 1 10) + ... +end +``` ## Variables ### Defining and erasing ```fish -set my_variable "Hello from Fish!" -``` +# Declare the global/local variable: +set my_variable 'Hello from Fish!' -```fish +i# Remove the variable: set --erase my_variable ``` +### Slicing + +```fish +echo $my_variable[1..10] +echo $my_variable[2..] +echo $my_variable[..-2] +``` + +## Numbers + ### Incrementing and decrementing ```fish @@ -51,62 +91,62 @@ set my_variable (math $my_variable + 1) set my_variable (math $my_variable - 1) ``` -### Slicing +### Arithmetic ```fish -set my_variable $another_variable[1..10] -set my_variable $another_variable[2..] -set my_variable $another_variable[..-2] +echo (math 1 + 2) ``` -## Arithmetic +| Operator | Performs | +| --- | --- | +| `+` | Addition | +| `-` | Subtraction | +| `*` | Multiplication | +| `/` | Division | +| `%` | Modulo | +| `^` | Exponentiation | -```fish -math 1 + 2 -``` +## Strings -| Operator | Performs | -| --- | --- | -| `+` | Addition | -| `-` | Subtraction | -| `*` | Multiplication | -| `/` | Division | -| `%` | Modulo | -| `^` | Exponentiation | -{: .-shortcuts} +### Matching -## String manipulation +Match the string against a regular expresion: ```fish string match --regex --entire 'Fish' 'Hello from Fish!' ``` +| Pattern | Matches | +| --- | --- | +| `x?` | Zero or one `x` chars | +| `x*` | Any count `x` chars | +| `x+` | One or more `x` chars | +| `x{n}` | n times `x` chars | +| `x{n,m}` | n to m times `x` chars | +| `x{n,}` | n or more times `x` chars | +| `[xy]` | `x` or y char | +| `[^xy]` | not `x` or y char | +| --- | --- | +| `\w` | Word character | +| `\d` | Digit character | +| `\W` | Not word character | +| `\D` | Not digit character | + +Perl compatible regular expressions are described here. + +### Replacing + ```fish +# Replaces the first match string replace --regex 'Fish' 'fish' 'Hello from Fish!' + +# Replaces all matches +string replace --regex --all 'Fish' 'fish' 'Hello from Fish!' ``` -| Pattern | Matches | -| --- | --- | -| `x?` | Zero or one `x` chars | -| `x*` | Any count `x` chars | -| `x+` | One or more `x` chars | -| `x{n}` | n times `x` chars | -| `x{n,m}` | n to m times `x` chars | -| `x{n,}` | n or more times `x` chars | -| `x{n,}` | n or more times `x` chars | -| `[xy] ` | `x` or y char | -| `[^xy]` | not `x` or y char | -{: .-shortcuts} +## Conditionals -| Class | Description | -| --- | --- | -| `\w` | Word character | -| `\d` | Digit character | -| `\W` | Not word character | -| `\D` | Not digit character | -{: .-shortcuts} - -### Conditionals +### If/else ```fish if test $my_variable -lt $another_variable @@ -118,56 +158,88 @@ else end ``` -| Operator | Meaning | +### Comparisons + +#### Numbers + +| Number operator | Meaning | | --- | --- | | `-lt` | [L]ess [t]han | | `-eq` | [Eq]ual | | `-gt` | [G]reater [t]han | | `-le` | [L]ess than or [e]qual to | | `-ge` | [G]reater than or [e]qual to | +| `-ne` | [N]ot [E]qual | + +#### Strings + +| String operator | Meaning | +| --- | --- | +| `==` | [Eq]ual | +| `!=` | [N]ot [E]qual | + +#### Files + +| File operator | Meaning | +| --- | --- | | `-f` | [F]ile exists | | `-d` | [D]irectory exists | | `-r` | File or directory exists and [r]eadable | | `-w` | File or directory exists and [w]ritable | | `-x` | File or directory exists and e[x]ecutable | -{: .-shortcuts} -## Loops + +## Process communication + +### Writing to files ```fish -for i in (seq 1 10) - ... -end +# Overwrite file +echo 'Hello from Fish!' > my_file + +# Append to file +echo 'Hello from Fish!' >> my_file ``` -## Command substitution +### Piping ```fish -set my_variable (math $my_variable + 1) +my_command | another_command ``` +Passes the first command stdout output as an input to a second command. + +### Command substitution + +```fish +echo (math $my_variable + 1) +``` + +The `(...)` expression is substituted with the output of the command inside it. + + +### Process substitution + +```fish +echo (math $my_variable + 1 | psub) +``` + +The `(... | psub)` expression is substituted with a temporary file with the command's output. + ## Functions ### Defining and erasing ```fish -function my_function --description "My description" +# Declare the function +function my_function --description 'My description' ··· end -``` -```fish +# Remove the function functions --erase my_function ``` -### Event handling - -```fish -function my_hook --on-event my_event - ··· -end -``` - ## Events ### Emitting @@ -176,56 +248,74 @@ end emit my_event ``` +Emits an event that can be picked up by other functions. + +### Event handling + +```fish +function my_hook --on-event my_event + ··· +end +``` + +Reacts to the `my_event` event. ## Abbreviations ### Defining and erasing ```fish -abbr --add my_abbreviation echo "Hello from Fish!" +# Declare the abbreviation +abbr --add grh "git reset --hard HEAD" ``` + ```fish -abbr --erase my_abbreviation +# Remove the abbreviation +abbr --erase grh ``` ## Completions -### Defining and erasing +### Defining completions ```fish complete --command mycommand --arguments 'install uninstall' complete --command mycommand --short-option 'h' --long-option 'help' --description 'Display help' ``` +| Option | Description | +| --- | --- | +| `--arguments` | Arguments to the command itself or option | +| `--short-option` | Short option | +| `--long-option` | Long option | +| `--no-files` | Don't suggest files | +| `--force-files` | Suggest files | +| `--condition` | Display the hint only when a given condition is true | +| `--description` | Description | + +Declares the completion for a command. + +### Removing completions + ```fish complete --command mycommand --erase ``` -| Option | Description | -| --- | --- | -| `--arguments` | Arguments to command itself or option | -| `--short-option` | Short option | -| `--long-option` | Long option | -| `--no-files` | Don't suggest files | -| `--force-files` | Suggest files | -| `--condition` | Display hint only when condition is true | -| `--description` | Description | -{: .-shortcuts} - ## Useful built-in functions -| Condition | Description -| --- | --- -| `-n __fish_complete_directories STRING DESCRIPTION` | performs path completion on STRING, allowing only directories, and giving them the description DESCRIPTION. -| `-n __fish_complete_path STRING DESCRIPTION` | performs path completion on STRING, giving them the description DESCRIPTION. -| `-n __fish_complete_groups` | prints a list of all user groups with the groups members as description. -| `-n __fish_complete_pids` | prints a list of all processes IDs with the command name as description. -| `-n __fish_complete_suffix SUFFIX` | performs file completion allowing only files ending in SUFFIX. The mimetype database is used to find a suitable description. -| `-n __fish_complete_users` | prints a list of all users with their full name as description. -| `-n __fish_print_filesystems` | prints a list of all known file systems. Currently, this is a static list, and not dependent on what file systems the host operating system actually understands. -| `-n __fish_print_hostnames` | prints a list of all known hostnames. This functions searches the fstab for nfs servers, ssh for known hosts and checks the /etc/hosts file. -| `-n __fish_print_interfaces` | prints a list of all known network interfaces. -| `-n __fish_print_packages` | prints a list of all installed packages. This function currently handles Debian, rpm and Gentoo packages. -| `-n __fish_use_subcommand` | -| `-n __fish_seen_subcommand_from init` | +| Function | Description | +| --- | --- | +| `__fish_seen_argument` | Check whether the specified argument is used | +| `__fish_seen_subcommand_from` | Check whether the specified subcommand is used | +| `__fish_use_subcommand` | Check whether any subcommand is used | +| --- | --- | +| `__fish_complete_directories` | Complete directories with the specified letters in their name | +| `__fish_complete_suffix` | Complete files with the specified suffix | +| --- | --- | +| `__fish_complete_users` | List all users | +| `__fish_complete_groups` | List all user groups | +| `__fish_print_hostnames` | List all host names | +| `__fish_complete_pids` | List all PIDs | +| `__fish_print_filesystems` | List all known filesystems | +| `__fish_print_interfaces` | List all network interfaces |