src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/pkg/edit/vars.d.elv (about)

     1  # Defines a new variable in the interactive REPL with an initial value. The new variable becomes
     2  # available during the next REPL cycle.
     3  #
     4  # Equivalent to running `var $name = $init` at a REPL prompt, but `$name` can be
     5  # dynamic.
     6  #
     7  # This is most useful for modules to modify the REPL namespace. Example:
     8  #
     9  # ```elvish-transcript
    10  # ~> cat .config/elvish/lib/a.elv
    11  # for i [(range 10)] {
    12  #   edit:add-var foo$i $i
    13  # }
    14  # ~> use a
    15  # ~> put $foo1 $foo2
    16  # ▶ (num 1)
    17  # ▶ (num 2)
    18  # ```
    19  #
    20  # Note that if you use a variable as the `$init` argument, `edit:add-var`
    21  # doesn't add the variable "itself" to the REPL namespace. The variable in the
    22  # REPL namespace will have the initial value set to the variable's value, but
    23  # it is not an alias of the original variable:
    24  #
    25  # ```elvish-transcript
    26  # ~> cat .config/elvish/lib/b.elv
    27  # var foo = foo
    28  # edit:add-var foo $foo
    29  # ~> use b
    30  # ~> put $foo
    31  # ▶ foo
    32  # ~> set foo = bar
    33  # ~> echo $b:foo
    34  # foo
    35  # ```
    36  #
    37  # ### Importing definition from a module into the REPL
    38  #
    39  # One common use of this command is to put the definitions of functions intended for REPL use in a
    40  # module instead of your [`rc.elv`](command.html#rc-file). For example, if you want to define `ll`
    41  # as `ls -l`, you can do so in your `rc.elv` directly:
    42  #
    43  # ```elvish
    44  # fn ll {|@a| ls -l $@a }
    45  # ```
    46  #
    47  # But if you move the definition into a module (say `util.elv` in one of the
    48  # [module search directories](command.html#module-search-directories), this
    49  # function can only be used as `util:ll` (after `use util`). To make it usable
    50  # directly as `ll`, you can add the following to `util.elv`:
    51  #
    52  # ```elvish
    53  # edit:add-var ll~ $ll~
    54  # ```
    55  #
    56  # ### Conditionally importing a module
    57  #
    58  # Another use case is to add a module or function to the REPL namespace
    59  # conditionally. For example, to only import [the `unix` module](unix.html)
    60  # when actually running on Unix, a straightforward solution is to do the
    61  # following in `rc.elv`:
    62  #
    63  # ```elvish
    64  # use platform
    65  # if $platform:is-unix {
    66  #   use unix
    67  # }
    68  # ```
    69  #
    70  # This doesn't work however, since what `use` does is introducing a variable
    71  # named `$unix:`. Since all variables in Elvish are lexically scoped, the
    72  # `$unix:` variable is only valid inside the `if` block.
    73  #
    74  # This can be fixed by explicitly introducing the `$unix:` variable to the REPL
    75  # namespace. The following works both from `rc.elv` and from a module:
    76  #
    77  # ```elvish
    78  # use platform
    79  # if $platform:is-unix {
    80  #   use unix
    81  #   edit:add-var unix: $unix:
    82  # }
    83  # ```
    84  fn add-var {|name init| }
    85  
    86  # Takes a map from strings to arbitrary values. Equivalent to calling
    87  # `edit:add-var` for each key-value pair in the map, but guarantees that all the
    88  # names will be added at the same time.
    89  fn add-vars {|map| }
    90  
    91  # Deletes a variable from the interactive REPL if it exists.
    92  #
    93  # Equivalent to running `del $name` at a REPL prompt, but `$name` can be
    94  # dynamic, and it is not an error to delete a non-existing variable.
    95  fn del-var {|name| }
    96  
    97  # Deletes variables from the interactive REPL.
    98  #
    99  # Equivalent to calling `edit:del-var` for each element of the list, but
   100  # guarantees that all the variables will be deleted at the same time.
   101  fn del-vars {|list| }