Language

What

A generic, fully configurable language/tool version segment. Use it to display the version of any executable without writing a dedicated segment: point it at one or more tools, a regex to parse their version output, and the files or folders that should trigger it.

Reach for a dedicated segment (like Fortran or Rust) when one already exists; use language for anything not already built in.

Sample Configuration

This example reproduces a GCC version segment purely through configuration.

json

{
  "type": "language",
  "style": "plain",
  "template": "{{ if .Error }}{{ else }}  {{ .Full }}{{ end }}",
  "options": {
    "name": "gcc",
    "extensions": [
      "*.c",
      "*.cpp",
      "*.h",
      "CMakeLists.txt"
    ],
    "tools": [
      {
        "name": "gcc",
        "executable": "gcc",
        "args": [
          "--version"
        ],
        "regex": "(?P<version>(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+))"
      }
    ]
  }
}

yaml

type: language
style: plain
template: "{{ if .Error }}{{ else }}  {{ .Full }}{{ end }}"
options:
  name: gcc
  extensions:
    - "*.c"
    - "*.cpp"
    - "*.h"
    - CMakeLists.txt
  tools:
    - name: gcc
      executable: gcc
      args:
        - --version
      regex: (?P<version>(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+))

toml

type = "language"
style = "plain"
template = "{{ if .Error }}{{ else }}  {{ .Full }}{{ end }}"

[options]
name = "gcc"
extensions = [ "*.c", "*.cpp", "*.h", "CMakeLists.txt" ]

[[options.tools]]
name = "gcc"
executable = "gcc"
args = [ "--version" ]
regex = "(?P<version>(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+))"

Options

Name	Type	Default	Description
name	string		a unique identifier for the segment, used as its version cache key. Required
tools	array	[]	the executables that can report the version, tried in order until one succeeds. See Tools below. Required
home_enabled	boolean	false	display the segment in the HOME folder or not
fetch_version	boolean	true	fetch the version
cache_duration	string	none	the duration for which the version will be cached. The duration is a string in the format 1h2m3s and is parsed using the time.ParseDuration function from the Go standard library. To disable the cache, use none
missing_command_text	string		text to display when the command is missing
display_mode	string	context	always: the segment is always displayed files: the segment is only displayed when file extensions listed are present context: displays the segment when the environment or files is active
version_url_template	string		a go text/template template that creates the URL of the version info / release notes
extensions	[]string	[]	the file extensions that trigger the segment
project_files	[]string	[]	files to look for in a parent directory that trigger the segment; when matched, .InProjectDir is true
folders	[]string	[]	the folder names that trigger the segment

Tools

Each entry in tools describes one executable that can report the segment's version:

Name	Type	Description
name	string	a unique identifier for the tool. Required
executable	string	the executable to run to fetch the version. Required
args	[]string	the arguments to pass to the executable
regex	string	the regex used to parse the version, with a named version capture group; optionally major, minor, patch, prerelease, buildmetadata. Required
version_url_template	string	a go text/template template that creates the URL of the version info / release notes for this tool

Template (info)

default template

{{ if .Error }}{{ .Error }}{{ else }}{{ .Full }}{{ end }}

Properties

Name	Type	Description
.Full	string	the full version
.Major	string	major number
.Minor	string	minor number
.Patch	string	patch number
.Prerelease	string	prerelease identifier
.BuildMetadata	string	build identifier
.URL	string	URL of the version info / release notes
.InProjectDir	bool	whether the working directory is within a project_files match
.Error	string	error encountered when fetching the version string