data.rst 14.1 KB
Newer Older
Mark Vander Stel's avatar
Mark Vander Stel committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
Data Functions
**************

.. contents::
   :local:

.. toctree::

   data/vcs

These functions are designed to be used by themes.

All data functions will return ``true`` (meaning return code ``0``) when they
are both enabled and have data. They will return ``false`` (meaning return code
``1``) when they do not have data. Most will return ``2`` when they are
disabled, either through the config or because the tool they depend on is not
installed. Such disable config options will be documented. Exceptions to this
rule are explicitly documented.

When a function returns ``false``, any return variables are not guaranteed to
be set. If running with ``set -u`` (or when building a theme to be
distributed), guard any return variable accesses with a check of the return
code, or use ``${var-}`` syntax.

Battery
-------

.. function:: _lp_battery() -> var:lp_battery

   Returns a return code depending on the status of the battery:

   * ``5`` if the battery feature is disabled or not available
   * ``4`` if no battery level is found
   * ``3`` if charging and the level is above the threshold
   * ``2`` if charging and the level is under the threshold
   * ``1`` if discharging and the level is above the threshold
   * ``0`` if discharging and the level is under the threshold

   Returns an integer percentage of the current battery level.

Mark Vander Stel's avatar
Mark Vander Stel committed
41
   If the threshold is not surpassed, the battery level is still returned.
Mark Vander Stel's avatar
Mark Vander Stel committed
42
43
44
45
46

   The threshold is configured with :attr:`LP_BATTERY_THRESHOLD`.

   Can be disabled by :attr:`LP_ENABLE_BATT`.

47
48
49
   .. versionchanged:: 2.1
      :attr:`LP_BATTERY_ID` can be used to specify which battery to monitor.

Mark Vander Stel's avatar
Mark Vander Stel committed
50
51
52
Development Environment
-----------------------

53
.. function:: _lp_kubernetes_context() -> var:lp_kubernetes_context, var:lp_kubernetes_namespace
54
55
56
57

   Returns ``true`` if a Kubernetes context is found.
   Returns the Kubernetes context name or the first name component.

58
59
60
61
   Splitting long context names into components is defined by
   :attr:`LP_DELIMITER_KUBECONTEXT_SUFFIX` and
   :attr:`LP_DELIMITER_KUBECONTEXT_PREFIX`. Both use greedy matches - see
   :doc:`../config` for examples.
62

63
64
65
   If enabled by :attr:`LP_ENABLE_KUBE_NAMESPACE`, will also return the default
   namespace for the current context, if one is set.

66
67
68
69
   Can be disabled by :attr:`LP_ENABLE_KUBECONTEXT`.

   .. versionadded:: 2.1

Mark Vander Stel's avatar
Mark Vander Stel committed
70
71
.. function:: _lp_python_env() -> var:lp_python_env

72
   Returns ``true`` if a Python or Conda environment is detected. Returns the
Mark Vander Stel's avatar
Mark Vander Stel committed
73
74
75
76
77
78
79
80
81
   virtual environment name.

   If the environment name contains a forward slash (``/``), only the substring
   after the last forward slash is returned.

   Can be disabled by :attr:`LP_ENABLE_VIRTUALENV`.

   .. versionadded:: 2.0

82
83
84
85
86
87
88
89
90
91
92
93
.. function:: _lp_ruby_env() -> var:lp_ruby_env

   Returns ``true`` if a RVM or RBENV ruby environment is detected. Returns the
   virtual environment name.

   In the case of a RVM environment, the label displayed can be customized
   with the :attr:`LP_RUBY_RVM_PROMPT_OPTIONS`.

   Can be disabled by :attr:`LP_ENABLE_RUBY_VENV`.

   .. versionadded:: 2.1

Mark Vander Stel's avatar
Mark Vander Stel committed
94
95
96
97
98
99
100
101
102
103
104
105
106
.. function:: _lp_software_collections() -> var:lp_software_collections

   Returns ``true`` if a `Red Hat Software Collection`_ is enabled. Returns the
   software collection name.

   If the software collection name has trailing whitespace, it is removed.

   Can be disabled by :attr:`LP_ENABLE_SCLS`.

   .. versionadded:: 2.0

   .. _`Red Hat Software Collection`: https://developers.redhat.com/products/softwarecollections/overview

Ken Crowell's avatar
Ken Crowell committed
107
108
109
110
111
112
113
114
115
116
.. function:: _lp_terraform_env() -> var:lp_terraform_env

   Returns ``true`` if a Terraform workspace is detected. Returns the workspace
   name.

   Can be enabled by :attr:`LP_ENABLE_TERRAFORM`.

   .. versionadded:: 2.1


Mark Vander Stel's avatar
Mark Vander Stel committed
117
118
119
Environment
-----------

120
121
.. function:: _lp_aws_profile() -> var:lp_aws_profile

Emil Lerch's avatar
Emil Lerch committed
122
123
124
   Returns ``true`` if the :envvar:`AWS_PROFILE`, :envvar:`AWS_DEFAULT_PROFILE`,
   or :envvar:`AWS_VAULT` variables are found in the environment
   (in that order of preference). Returns the contents of the variable.
125
126
127
128
129

   Can be disabled by :attr:`LP_ENABLE_AWS_PROFILE`.

   .. versionadded:: 2.1

Mark Vander Stel's avatar
Mark Vander Stel committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
.. function:: _lp_connected_display()

   Returns ``true`` if there is a connected X11 display.

   .. versionadded:: 2.0

.. function:: _lp_connection() -> var:lp_connection

   Returns a string matching the connection context of the shell. Valid values:

   * ``ssh`` - connected over OpenSSH
   * ``lcl`` - running in a local terminal
   * ``su`` - running in a ``su`` or ``sudo`` shell
   * ``tel`` - connected over Telnet

   It is not possible for more than one context to be returned. The contexts
   are checked in the order listed above, and the first one found will be
   returned.

   It is not possible for no context to be returned.

   .. versionchanged:: 2.0
      Return method changed from stdout.

154
155
.. function:: _lp_dirstack() -> var:lp_dirstack

156
157
158
    Returns ``true`` if directory stack support is enabled and the directory
    stack contains more than one directory. In that case, the return variable
    is set to the number of directories on the stack.
159
160
161
162
163

    Can be enabled by :attr:`LP_ENABLE_DIRSTACK`.

    .. versionadded:: 2.0

Mark Vander Stel's avatar
Mark Vander Stel committed
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
.. function:: _lp_error() -> var:lp_error

   Returns ``true`` if the last user shell command returned a non-zero exit
   code. Returns (in the return variable) the exit code of that command.

   Can be disabled by :attr:`LP_ENABLE_ERROR`.

   .. note::

      The return variable ``lp_error`` will always be set with the last command
      return code, as it must be the first thing done by the prompt. This
      function should still be used, as it checks for the feature being
      disabled by the user.

   .. versionadded:: 2.0

.. function:: _lp_http_proxy() -> var:lp_http_proxy

   Returns ``true`` if an HTTP or HTTPS proxy is enabled through environment
   variables in the shell. Returns the first found proxy string.

   Can be disabled by :attr:`LP_ENABLE_PROXY`.

   .. versionadded:: 2.0

.. function:: _lp_multiplexer() -> var:lp_mulitplexer

   Returns ``true`` if the current shell context is inside a terminal
   multiplexer. Returns a string matching the multiplexer:

   * ``tmux``
   * ``screen``

197
198
199
200
201
202
203
204
205
206
207
208
209
210
   .. versionadded:: 2.0

.. function:: _lp_terminal_device() -> var:lp_terminal_device

   Returns the basename of the terminal device connected to the shell's standard
   input.

   .. note::
      This value should never change during the life of the shell.

   .. note::
      This data source is unlikely to be wanted by the user, and should not be
      included in themes by default.

Mark Vander Stel's avatar
Mark Vander Stel committed
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
   .. versionadded:: 2.0

Jobs
----

.. function:: _lp_detached_sessions() -> var:lp_detached_sessions

   Returns ``true`` if any detached multiplexer sessions are found. Returns an
   integer count of how many sessions were found.

   Can be disabled by :attr:`LP_ENABLE_DETACHED_SESSIONS`.

   .. versionadded:: 2.0

.. function:: _lp_jobcount() -> var:lp_running_jobs, var:lp_stopped_jobs

   Returns ``true`` if any shell background jobs are found. Returns an integer
   count of how many jobs are running and how many are stopped.

   Stopped jobs are jobs suspended with Ctrl-Z.

   Running jobs are jobs started with the ``command &`` syntax, or stopped jobs
   started again with the ``bg`` command.

   Can be disabled by :attr:`LP_ENABLE_JOBS`.

   .. versionadded:: 2.0

Load
----

.. function:: _lp_cpu_load() -> var:lp_cpu_load

244
245
   Returns a string of the system load average smallest increment, usually 1
   minute. The return code is not defined.
Mark Vander Stel's avatar
Mark Vander Stel committed
246

247
.. function:: _lp_load() -> var:lp_load, var:lp_load_adjusted
Mark Vander Stel's avatar
Mark Vander Stel committed
248

249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
   Returns ``true`` if the system load average scaled by CPU count is greater
   than the threshold. Returns the system load average in *lp_load*, and the
   average scaled by CPU count, multiplied by 100 in *lp_load_adjusted*. In
   other words, the load average is multiplied by 100, then divided by the
   number of CPU cores.

   *lp_load* should be displayed to the user, while *lp_load_adjusted* should be
   used to compare values between machines using :attr:`LP_LOAD_CAP`. The
   default theme uses this to generate a color scale.

   .. note::
      :attr:`LP_LOAD_CAP` is a raw floating point configuration value that is
      difficult to do math on. ``_LP_LOAD_CAP`` contains the same value, but
      multiplied by 100 to make comparisons to *lp_load_adjusted* simple. Use
      it along with *lp_load_adjusted* as arguments to :func:`_lp_color_map`.
Mark Vander Stel's avatar
Mark Vander Stel committed
264

Mark Vander Stel's avatar
Mark Vander Stel committed
265
   If the threshold is not surpassed, the load average is still returned.
Mark Vander Stel's avatar
Mark Vander Stel committed
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282

   The threshold is configured with :attr:`LP_LOAD_THRESHOLD`.

   Can be disabled by :attr:`LP_ENABLE_LOAD`.

   .. versionadded:: 2.0

OS
--

.. function:: _lp_chroot() -> var:lp_chroot

   Returns ``true`` if a chroot environment is detected. Returns a string
   matching the chroot string if one is found.

   .. versionadded:: 2.0

283
.. function:: _lp_hostname() -> var:lp_hostname, var:lp_hostname_raw
Mark Vander Stel's avatar
Mark Vander Stel committed
284
285
286
287

   Returns ``true`` if a hostname should be displayed. Returns ``1`` if the
   connection type is local and :attr:`LP_HOSTNAME_ALWAYS` is not ``1``.

288
   Returns the hostname string in *lp_hostname*.
Mark Vander Stel's avatar
Mark Vander Stel committed
289

290
291
   Returns the hostname string not passed through :func:`__lp_escape` in
   *lp_hostname_raw*.
Mark Vander Stel's avatar
Mark Vander Stel committed
292
293
294
295
296

   Can be disabled by :attr:`LP_HOSTNAME_ALWAYS` set to ``-1``.

   .. versionadded:: 2.0

297
298
   .. versionchanged:: 2.1
      Returns the actual hostname instead of a shell prompt escape code.
299
      Added *lp_hostname_raw* return value.
300
301
      No longer sets :attr:`LP_HOST_SYMBOL` to the same return string.

Mark Vander Stel's avatar
Mark Vander Stel committed
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
.. function:: _lp_sudo_active()

   Returns ``true`` if ``sudo`` is currently activated with valid credentials.
   If ``sudo`` is configured to always allow a user to run commands with no
   password, this will always return ``true``.

   Can be disabled by :attr:`LP_ENABLE_SUDO`.

   .. versionadded:: 2.0

.. function:: _lp_user()

   Returns a return code depending on the logged in user:

   * ``2`` - the user is root
   * ``1`` - the user is a user other than the original login user
   * ``0`` - the user is the login user

   .. versionadded:: 2.0

322
.. function:: _lp_username() -> var:lp_username, var:lp_username_raw
Mark Vander Stel's avatar
Mark Vander Stel committed
323
324
325
326

   Returns ``true`` if a username should be displayed. Returns ``1`` if the
   user is the login user and :attr:`LP_USER_ALWAYS` is not ``1``.

327
   Returns the current user ID in *lp_username*.
Mark Vander Stel's avatar
Mark Vander Stel committed
328

329
330
   Returns the current user ID not passed through :func:`__lp_escape` in
   *lp_username_raw*.
Mark Vander Stel's avatar
Mark Vander Stel committed
331
332
333
334
335

   Can be disabled by :attr:`LP_USER_ALWAYS` set to ``-1``.

   .. versionadded:: 2.0

336
337
   .. versionchanged:: 2.1
      Returns the actual username instead of a shell prompt escape code.
338
      Added *lp_username_raw* return value.
339

340
341
342
343
344
345
346
347
348
Path
----

.. function:: _lp_path_format(path_format=$LP_COLOR_PATH, \
   last_directory_format=$path_format, vcs_root_format=$last_directory_format, \
   shortened_directory_format=$path_format, separator="/", \
   [separator_format]) -> var:lp_path, var:lp_path_format

   Returns a shortened and formatted string indicating the current working
349
350
351
352
   directory path. *lp_path* contains the path without any formatting, custom
   separators, or shell escapes, intended for use in the terminal title.
   *lp_path_format* contains the complete formatted path, to be inserted into
   the prompt.
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381

   The behavior of the shortening is controlled by
   :attr:`LP_ENABLE_SHORTEN_PATH`, :attr:`LP_PATH_METHOD`,
   :attr:`LP_PATH_LENGTH`, :attr:`LP_PATH_KEEP`, :attr:`LP_PATH_CHARACTER_KEEP`,
   and :attr:`LP_PATH_VCS_ROOT`. See their descriptions for details on how they
   change the output of this function.

   The last directory in the displayed path will be shown with the
   *last_directory_format*.

   If a VCS repository is detected with :func:`_lp_find_vcs`, the root of the
   VCS repository is formatted with *vcs_root_format*. The detection method is
   the same as for all other VCS display, so if a VCS type or directory is
   disabled, it will not be detected.

   If the path shortening shortens a directory (or multiple consecutive
   directories), they will be formatted with *shortened_directory_format*.

   A custom *separator* will only be substituted in the *lp_path_format* output.
   Note that this will cut into maximum path length if the separator is longer
   than one character.

   With no specified *separator_format*, each separator will take the format of
   the directory section preceding it. Otherwise every separator will be
   formatted with *separator_format*. Note that the root directory is treated as
   a directory, and is formatted as such.

   .. versionadded:: 2.0

382
383
384
   .. versionchanged:: 2.1
      Changed *lp_path* to no longer contain shell escapes.

Mark Vander Stel's avatar
Mark Vander Stel committed
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
Runtime
-------

.. function:: _lp_runtime_format() -> var:lp_runtime_format

   Returns ``true`` if the last command runtime was greater than the threshold.
   Returns a formatted string of the total runtime, split into days, hours,
   minutes, and seconds. Ex: ``3h27m6s``.

   The threshold is configured with :attr:`LP_RUNTIME_THRESHOLD`.

   Can be disabled by :attr:`LP_ENABLE_RUNTIME`.

   .. versionadded:: 2.0

Temperature
-----------

.. function:: _lp_temperature() -> var:lp_temperature

   Returns ``true`` if the highest system temperature is greater than the
   threshold. Returns the highest temperature integer.

Mark Vander Stel's avatar
Mark Vander Stel committed
408
   If the threshold is not surpassed, the highest temperature is still returned.
Mark Vander Stel's avatar
Mark Vander Stel committed
409

410
411
412
   If no temperature data is found, returns ``false`` and *lp_temperature* will
   not be set.

Mark Vander Stel's avatar
Mark Vander Stel committed
413
414
415
416
417
418
419
420
421
422
423
424
425
426
   The threshold is configured with :attr:`LP_TEMP_THRESHOLD`.

   Can be disabled by :attr:`LP_ENABLE_TEMP`.

   .. versionadded:: 2.0
      Note that a function by this name was renamed to
      ``_lp_temperature_color``.

Time
----

.. function:: _lp_time() -> var:lp_time

   Returns ``true`` if digital time is enabled. Returns the current digital time
427
   string, formatting set by :attr:`LP_TIME_FORMAT`.
Mark Vander Stel's avatar
Mark Vander Stel committed
428

429
   Can be disabled by :attr:`LP_ENABLE_TIME`, or :attr:`LP_TIME_ANALOG` set to
Mark Vander Stel's avatar
Mark Vander Stel committed
430
431
432
433
   ``1``.

   .. versionadded:: 2.0

434
435
436
   .. versionchanged:: 2.1
      Returns the actual time instead of a shell prompt escape code.

Mark Vander Stel's avatar
Mark Vander Stel committed
437
438
439
440
441
.. function:: _lp_analog_time() -> var:lp_analog_time

   Returns ``true`` if analog time is enabled. Returns the current analog time
   as a single Unicode character, accurate to the closest 30 minutes.

442
   Can be disabled by :attr:`LP_ENABLE_TIME`, or :attr:`LP_TIME_ANALOG` set to
Mark Vander Stel's avatar
Mark Vander Stel committed
443
444
445
   ``0``.

   .. versionadded:: 2.0