github.com/elves/elvish@v0.15.0/website/ref/builtin.md (about)

     1  <!-- toc -->
     2  
     3  # Introduction
     4  
     5  The builtin module contains facilities that are potentially useful to all users.
     6  
     7  ## Using builtin: explicitly
     8  
     9  The builtin module is consulted implicitly when resolving unqualified names, so
    10  you usually don't need to specify `builtin:` explicitly. However, there are some
    11  cases where it is useful to do that:
    12  
    13  -   When a builtin function is shadowed by a local function, you can still use
    14      the builtin function by specifying `builtin:`. This is especially useful
    15      when wrapping a builtin function:
    16  
    17      ```elvish
    18      use builtin
    19      fn cd [@args]{
    20          echo running my cd function
    21          builtin:cd $@args
    22      }
    23      ```
    24  
    25  -   Introspecting the builtin module, for example `keys $builtin:`.
    26  
    27  ## Usage Notation
    28  
    29  The usage of a builtin command is described by giving an example usage, using
    30  variables as arguments. For instance, The `repeat` command takes two arguments
    31  and are described as:
    32  
    33  ```elvish
    34  repeat $n $v
    35  ```
    36  
    37  Optional arguments are represented with a trailing `?`, while variadic arguments
    38  with a trailing `...`. For instance, the `count` command takes an optional list:
    39  
    40  ```elvish
    41  count $input-list?
    42  ```
    43  
    44  While the `put` command takes an arbitrary number of arguments:
    45  
    46  ```elvish
    47  put $values...
    48  ```
    49  
    50  Options are given along with their default values. For instance, the `echo`
    51  command takes an `sep` option and arbitrary arguments:
    52  
    53  ```elvish
    54  echo &sep=' ' $value...
    55  ```
    56  
    57  (When you calling functions, options are always optional.)
    58  
    59  ## Supplying Input
    60  
    61  Some builtin functions, e.g. `count` and `each`, can take their input in one of
    62  two ways:
    63  
    64  1. From pipe:
    65  
    66      ```elvish-transcript
    67      ~> put lorem ipsum | count # count number of inputs
    68      2
    69      ~> put 10 100 | each [x]{ + 1 $x } # apply function to each input
    70      ▶ 11
    71      ▶ 101
    72      ```
    73  
    74      Byte pipes are also possible; one line becomes one input:
    75  
    76      ```elvish-transcript
    77      ~> echo "a\nb\nc" | count # count number of lines
    78      ▶ 3
    79      ```
    80  
    81  1. From an argument -- an iterable value:
    82  
    83      ```elvish-transcript
    84      ~> count [lorem ipsum] # count number of elements in argument
    85      2
    86      ~> each [x]{ + 1 $x } [10 100] # apply to each element in argument
    87      ▶ 11
    88      ▶ 101
    89      ```
    90  
    91      Strings, and in future, other sequence types are also possible:
    92  
    93      ```elvish-transcript
    94      ~> count lorem
    95      ▶ 5
    96      ```
    97  
    98  When documenting such commands, the optional argument is always written as
    99  `$input-list?`. On the other hand, a trailing `$input-list?` always indicates
   100  that a command can take its input in one of two ways above: this fact is not
   101  repeated below.
   102  
   103  **Note**: You should prefer the first form, unless using it requires explicit
   104  `put` commands. Avoid `count [(some-command)]` or
   105  `each $some-func [(some-command)]`; they are, most of the time, equivalent to
   106  `some-command | count` or `some-command | each $some-func`.
   107  
   108  **Rationale**: An alternative way to design this is to make (say) `count` take
   109  an arbitrary number of arguments, and count its arguments; when there is 0
   110  argument, count inputs. However, this leads to problems in code like `count *`;
   111  the intention is clearly to count the number of files in the current directory,
   112  but when the current directory is empty, `count` will wait for inputs. Hence it
   113  is required to put the input in a list: `count [*]` unambiguously supplies input
   114  in the argument, even if there is no file.
   115  
   116  ## Commands That Operate On Numbers
   117  
   118  Commands that operate on numbers are quite flexible about the format of those
   119  numbers. See the discussion of the [number data type](./language.html#number).
   120  
   121  Because numbers are normally specified as strings, rather than as an explicit
   122  `float64` data type, some builtin commands have variants intended to operate on
   123  strings or numbers exclusively. For instance, the numerical equality command is
   124  `==`, while the string equality command is `==s`. Another example is the `+`
   125  builtin, which only operates on numbers and does not function as a string
   126  concatenation command. Consider these examples:
   127  
   128  ```elvish-transcript
   129  ~> + x 1
   130  Exception: wrong type of 1'th argument: cannot parse as number: x
   131  [tty], line 1: + x 1
   132  ~> + inf 1
   133  ▶ (float64 +Inf)
   134  ~> + -inf 1
   135  ▶ (float64 -Inf)
   136  ~> + -infinity 1
   137  ▶ (float64 -Inf)
   138  ~> + -infinityx 1
   139  Exception: wrong type of 1'th argument: cannot parse as number: -infinityx
   140  [tty], line 1: + -infinityx 1
   141  ```
   142  
   143  ## Predicates
   144  
   145  Predicates are functions that write exactly one output that is either `$true` or
   146  `$false`. They are described like "Determine ..." or "Test ...". See [`is`](#is)
   147  for one example.
   148  
   149  ## "Do Not Use" Functions and Variables
   150  
   151  The name of some variables and functions have a leading `-`. This is a
   152  convention to say that it is subject to change and should not be depended upon.
   153  They are either only useful for debug purposes, or have known issues in the
   154  interface or implementation, and in the worst case will make Elvish crash.
   155  (Before 1.0, all features are subject to change, but those ones are sure to be
   156  changed.)
   157  
   158  Those functions and variables are documented near the end of the respective
   159  sections. Their known problem is also discussed.
   160  
   161  @elvdoc -dir ../pkg/eval