Expose state information via environment variables to child processes

Close #3582

CHANGELOG.md

@@ -4,6 +4,33 @@ CHANGELOG
 0.46.0 (WIP)
 ------
 - Added `result` event that is triggered when the filtering for the current query is complete and the result list is ready.
+- fzf now exports the following environment variables to the child processes
+  | Variable           | Description                                                 |
+  | ---                | ---                                                         |
+  | `FZF_LINES`        | Number of lines fzf takes up excluding padding and margin   |
+  | `FZF_COLUMNS`      | Number of columns fzf takes up excluding padding and margin |
+  | `FZF_TOTAL_COUNT`  | Total number of items                                       |
+  | `FZF_MATCH_COUNT`  | Number of matched items                                     |
+  | `FZF_SELECT_COUNT` | Number of selected items                                    |
+  | `FZF_QUERY`        | Current query string                                        |
+  | `FZF_PROMPT`       | Prompt string                                               |
+  | `FZF_ACTION`       | The name of the last action performed                       |
+  - This allows you to write sophisticated transformations like so
+    ```sh
+    # Dynamically resize preview window
+    seq 10000 | fzf --bind 'result:transform:
+      # 1 line for info, another for prompt, and 2 more lines for preview window border
+      lines=$(( FZF_LINES - FZF_MATCH_COUNT - 4 ))
+      if [[ $FZF_MATCH_COUNT -eq 0 ]]; then
+        echo "change-preview-window:hidden"
+      elif [[ $lines -gt 3 ]]; then
+        echo "change-preview-window:$lines"
+      elif [[ $FZF_PREVIEW_LINES -ne 3 ]]; then
+        echo "change-preview-window:3"
+      fi
+    ' --preview 'seq {} 10000' --preview-window up
+    ```
+  - And we're phasing out `{fzf:prompt}` and `{fzf:action}`
 - Bug fixes
 
 0.45.0

man/man1/fzf.1

@@ -592,8 +592,6 @@ Also,
 * \fB{n}\fR is replaced to the zero-based ordinal index of the current item.
   Use \fB{+n}\fR if you want all index numbers when multiple lines are selected.
 .br
-* \fB{fzf:action}\fR is replaced to to the name of the last action performed
-* \fB{fzf:prompt}\fR is replaced to to the prompt string
 
 Note that you can escape a placeholder pattern by prepending a backslash.
 
@@ -901,6 +899,39 @@ of field index expressions.
 .BR .. "     All the fields"
 .br
 
+.SH ENVIRONMENT VARIABLES EXPORTED TO CHILD PROCESSES
+
+fzf exports the following environment variables to its child processes.
+
+.BR FZF_LINES "           Number of lines fzf takes up excluding padding and margin"
+.br
+.BR FZF_COLUMNS "         Number of columns fzf takes up excluding padding and margin"
+.br
+.BR FZF_TOTAL_COUNT "     Total number of items"
+.br
+.BR FZF_MATCH_COUNT "     Number of matched items"
+.br
+.BR FZF_SELECT_COUNT "    Number of selected items"
+.br
+.BR FZF_QUERY "           Current query string"
+.br
+.BR FZF_PROMPT "          Prompt string"
+.br
+.BR FZF_ACTION "          The name of the last action performed"
+.br
+.BR FZF_PORT "            Port number when --listen option is used"
+.br
+
+The following variables are additionally exported to the preview commands.
+
+.BR FZF_PREVIEW_TOP "     Top position of the preview window"
+.br
+.BR FZF_PREVIEW_LEFT "    Left position of the preview window"
+.br
+.BR FZF_PREVIEW_LINES "   Number of lines in the preview window"
+.br
+.BR FZF_PREVIEW_COLUMNS " Number of columns in the preview window"
+
 .SH EXTENDED SEARCH MODE
 
 Unless specified otherwise, fzf will start in "extended-search mode". In this

src/terminal.go

@@ -291,6 +291,8 @@ type Terminal struct {
 	termSize           tui.TermSize
 	lastAction         actionType
 	lastFocus          int32
+	areaLines          int
+	areaColumns        int
 }
 
 type selectedItem struct {
@@ -451,6 +453,17 @@ const (
 	actHideHeader
 )
 
+func (a actionType) Name() string {
+	name := ""
+	for i, r := range a.String()[3:] {
+		if i > 0 && r >= 'A' && r <= 'Z' {
+			name += "-"
+		}
+		name += string(r)
+	}
+	return strings.ToLower(name)
+}
+
 func processExecution(action actionType) bool {
 	switch action {
 	case actTransform,
@@ -825,6 +838,14 @@ func (t *Terminal) environ() []string {
 	if t.listenPort != nil {
 		env = append(env, fmt.Sprintf("FZF_PORT=%d", *t.listenPort))
 	}
+	env = append(env, "FZF_QUERY="+string(t.input))
+	env = append(env, "FZF_ACTION="+t.lastAction.Name())
+	env = append(env, "FZF_PROMPT="+string(t.promptString))
+	env = append(env, fmt.Sprintf("FZF_TOTAL_COUNT=%d", t.count))
+	env = append(env, fmt.Sprintf("FZF_MATCH_COUNT=%d", t.merger.Length()))
+	env = append(env, fmt.Sprintf("FZF_SELECT_COUNT=%d", len(t.selected)))
+	env = append(env, fmt.Sprintf("FZF_LINES=%d", t.areaLines))
+	env = append(env, fmt.Sprintf("FZF_COLUMNS=%d", t.areaColumns))
 	return env
 }
 
@@ -1291,6 +1312,9 @@ func (t *Terminal) resizeWindows(forcePreview bool) {
 	width -= paddingInt[1] + paddingInt[3]
 	height -= paddingInt[0] + paddingInt[2]
 
+	t.areaLines = height
+	t.areaColumns = width
+
 	// Set up preview window
 	noBorder := tui.MakeBorderStyle(tui.BorderNone, t.unicode)
 	if forcePreview || t.needPreviewWindow() {
@@ -2543,14 +2567,7 @@ func replacePlaceholder(params replacePlaceholderParams) string {
 				}
 			}
 		case match == "{fzf:action}":
-			name := ""
-			for i, r := range params.lastAction.String()[3:] {
-				if i > 0 && r >= 'A' && r <= 'Z' {
-					name += "-"
-				}
-				name += string(r)
-			}
-			return strings.ToLower(name)
+			return params.lastAction.Name()
 		case match == "{fzf:prompt}":
 			return quoteEntry(params.prompt)
 		default: