feat(dircycle): add bindings to go up or down in hierarchy (#12291)

Co-authored-by: Marc Cornellà <marc@mcornella.com>

plugins/dircycle/README.md

@@ -37,13 +37,13 @@ Say you opened these directories on the terminal:
 3       ~
 ```
 
-By pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>, the current working directory or `$CWD` will be from `oh-my-zsh` to `Hacktoberfest`. Press it again and it will be at `Projects`.
+By pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>, the current working directory or `$PWD` will be from `oh-my-zsh` to `Hacktoberfest`. Press it again and it will be at `Projects`.
 
-And by pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd>, the `$CWD` will be from `Projects` to `Hacktoberfest`. Press it again and it will be at `oh-my-zsh`.
+And by pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd>, the `$PWD` will be from `Projects` to `Hacktoberfest`. Press it again and it will be at `oh-my-zsh`.
 
 Here's a example history table with the same accessed directories like above:
 
-| Current `$CWD`  | Key press                                             | New `$CWD`      |
+| Current `$PWD`  | Key press                                             | New `$PWD`      |
 | --------------- | ----------------------------------------------------- | --------------- |
 | `oh-my-zsh`     | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>  | `Hacktoberfest` |
 | `Hacktoberfest` | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>  | `Projects`      |
@@ -53,7 +53,7 @@ Here's a example history table with the same accessed directories like above:
 | `Hacktoberfest` | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> | `oh-my-zsh`     |
 | `oh-my-zsh`     | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> | `~`             |
 
-Note the last traversal, when pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> on a last known `$CWD`, it will change back to the first known `$CWD`, which in the example is `~`.
+Note the last traversal, when pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> on a last known `$PWD`, it will change back to the first known `$PWD`, which in the example is `~`.
 
 Here's an asciinema cast demonstrating the example above:
 
@@ -61,18 +61,22 @@ Here's an asciinema cast demonstrating the example above:
 
 ## Functions
 
-| Function             | Description                                                                                               |
-| -------------------- | --------------------------------------------------------------------------------------------------------- |
-| `insert-cycledleft`  | Change `$CWD` to the previous known stack, binded on <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd> |
-| `insert-cycledright` | Change `$CWD` to the next known stack, binded on <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd>    |
+| Function             | Description                                                                                                         |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `insert-cycledleft`  | Change `$PWD` to the previous known stack, bound to <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>            |
+| `insert-cycledright` | Change `$PWD` to the next known stack, bound to <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd>               |
+| `insert-cycledup`    | Change `$PWD` to the parent folder, bound to <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Up</kbd>                     |
+| `insert-cycleddown`  | Change `$PWD` to the first alphabetical child folder, bound to <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Down</kbd> |
 
 ## Rebinding keys
 
-You can bind these functions to other key sequences, as long as you know the bindkey sequence. For example, these commands bind to <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd> / <kbd>Right</kbd> in `xterm-256color`:
+You can bind these functions to other key sequences, as long as you know the bindkey sequence. For example, these commands bind to <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>key</kbd> in `xterm-256color`:
 
 ```zsh
 bindkey '^[[1;4D' insert-cycledleft
 bindkey '^[[1;4C' insert-cycledright
+bindkey "\e[1;4A" insert-cycledup
+bindkey "\e[1;4B" insert-cycleddown
 ```
 
 You can get the bindkey sequence by pressing <kbd>Ctrl</kbd> + <kbd>V</kbd>, then pressing the keyboard shortcut you want to use.

plugins/dircycle/dircycle.plugin.zsh

@@ -8,7 +8,16 @@
 #  pushd +N: start counting from left of `dirs' output
 #  pushd -N: start counting from right of `dirs' output
 
+# Either switch to a directory from dirstack, using +N or -N syntax
+# or switch to a directory by path, using `switch-to-dir -- <path>`
 switch-to-dir () {
+	# If $1 is --, then treat $2 as a directory path
+	if [[ $1 == -- ]]; then
+		# We use `-q` because we don't want chpwd to run, we'll do it manually
+		[[ -d "$2" ]] && builtin pushd -q "$2" &>/dev/null
+		return $?
+	fi
+
 	setopt localoptions nopushdminus
 	[[ ${#dirstack} -eq 0 ]] && return 1
 
@@ -22,10 +31,10 @@ switch-to-dir () {
 }
 
 insert-cycledleft () {
-	switch-to-dir +1 || return
+	switch-to-dir +1 || return $?
 
 	local fn
-	for fn (chpwd $chpwd_functions precmd $precmd_functions); do
+	for fn in chpwd $chpwd_functions precmd $precmd_functions; do
 		(( $+functions[$fn] )) && $fn
 	done
 	zle reset-prompt
@@ -33,22 +42,46 @@ insert-cycledleft () {
 zle -N insert-cycledleft
 
 insert-cycledright () {
-	switch-to-dir -0 || return
+	switch-to-dir -0 || return $?
 
 	local fn
-	for fn (chpwd $chpwd_functions precmd $precmd_functions); do
+	for fn in chpwd $chpwd_functions precmd $precmd_functions; do
 		(( $+functions[$fn] )) && $fn
 	done
 	zle reset-prompt
 }
 zle -N insert-cycledright
 
+insert-cycledup () {
+	switch-to-dir -- .. || return $?
+
+	local fn
+	for fn in chpwd $chpwd_functions precmd $precmd_functions; do
+		(( $+functions[$fn] )) && $fn
+	done
+	zle reset-prompt
+}
+zle -N insert-cycledup
+
+insert-cycleddown () {
+	switch-to-dir -- "$(find . -mindepth 1 -maxdepth 1 -type d | sort -n | head -n 1)" || return $?
+
+	local fn
+	for fn in chpwd $chpwd_functions precmd $precmd_functions; do
+		(( $+functions[$fn] )) && $fn
+	done
+	zle reset-prompt
+}
+zle -N insert-cycleddown
 
 # These sequences work for xterm, Apple Terminal.app, and probably others.
 # Not for rxvt-unicode, but it doesn't seem differentiate Ctrl-Shift-Arrow
 # from plain Shift-Arrow, at least by default.
+#
 # iTerm2 does not have these key combinations defined by default; you will need
 # to add them under "Keys" in your profile if you want to use this. You can do
 # this conveniently by loading the "xterm with Numeric Keypad" preset.
-bindkey "\e[1;6D" insert-cycledleft
-bindkey "\e[1;6C" insert-cycledright
+bindkey "\e[1;6D" insert-cycledleft     # Ctrl+Shift+Left
+bindkey "\e[1;6C" insert-cycledright    # Ctrl+Shift+Right
+bindkey "\e[1;6A" insert-cycledup       # Ctrl+Shift+Up
+bindkey "\e[1;6B" insert-cycleddown     # Ctrl+Shift+Down