github.com/markusbkk/elvish@v0.0.0-20231204143114-91dc52438621/pkg/eval/builtin_ns.go (about)

     1  package eval
     2  
     3  import (
     4  	"strconv"
     5  	"syscall"
     6  
     7  	"github.com/markusbkk/elvish/pkg/buildinfo"
     8  	"github.com/markusbkk/elvish/pkg/eval/vars"
     9  )
    10  
    11  //elvdoc:var _
    12  //
    13  // A blackhole variable.
    14  //
    15  // Values assigned to it will be discarded. Referencing it always results in $nil.
    16  
    17  //elvdoc:var args
    18  //
    19  // A list containing command-line arguments. Analogous to `argv` in some other
    20  // languages. Examples:
    21  //
    22  // ```elvish-transcript
    23  // ~> echo 'put $args' > args.elv
    24  // ~> elvish args.elv foo -bar
    25  // ▶ [foo -bar]
    26  // ~> elvish -c 'put $args' foo -bar
    27  // ▶ [foo -bar]
    28  // ```
    29  //
    30  // As demonstrated above, this variable does not contain the name of the script
    31  // used to invoke it. For that information, use the `src` command.
    32  //
    33  // @cf src
    34  
    35  //elvdoc:var false
    36  //
    37  // The boolean false value.
    38  
    39  //elvdoc:var ok
    40  //
    41  // The special value used by `?()` to signal absence of exceptions.
    42  
    43  //elvdoc:var nil
    44  //
    45  // A special value useful for representing the lack of values.
    46  
    47  //elvdoc:var paths
    48  //
    49  // A list of search paths, kept in sync with `$E:PATH`. It is easier to use than
    50  // `$E:PATH`.
    51  
    52  //elvdoc:var pid
    53  //
    54  // The process ID of the current Elvish process.
    55  
    56  //elvdoc:var pwd
    57  //
    58  // The present working directory. Setting this variable has the same effect as
    59  // `cd`. This variable is most useful in a temporary assignment.
    60  //
    61  // Example:
    62  //
    63  // ```elvish
    64  // ## Updates all git repositories
    65  // for x [*/] {
    66  //   pwd=$x {
    67  //     if ?(test -d .git) {
    68  //       git pull
    69  //     }
    70  //   }
    71  // }
    72  // ```
    73  //
    74  // Etymology: the `pwd` command.
    75  //
    76  // @cf cd
    77  
    78  //elvdoc:var true
    79  //
    80  // The boolean true value.
    81  
    82  //elvdoc:var buildinfo
    83  //
    84  // A [psuedo-map](./language.html#pseudo-map) that exposes information about the Elvish binary.
    85  // Running `put $buildinfo | to-json` will produce the same output as `elvish -buildinfo -json`.
    86  //
    87  // @cf version
    88  
    89  //elvdoc:var version
    90  //
    91  // The full version of the Elvish binary as a string. This is the same information reported by
    92  // `elvish -version` and the value of `$buildinfo[version]`.
    93  //
    94  // **Note:** In general it is better to perform functionality tests rather than testing `$version`.
    95  // For example, do something like
    96  //
    97  // ```
    98  // has-key $builtin: new-var
    99  // ````
   100  //
   101  // to test if variable `new-var` is available rather than comparing against `$version` to see if the
   102  // elvish version is equal to or newer than the version that introduced `new-var`.
   103  //
   104  // @cf buildinfo
   105  
   106  var builtinNs = BuildNsNamed("").AddVars(map[string]vars.Var{
   107  	"_":         vars.NewBlackhole(),
   108  	"pid":       vars.NewReadOnly(strconv.Itoa(syscall.Getpid())),
   109  	"ok":        vars.NewReadOnly(OK),
   110  	"nil":       vars.NewReadOnly(nil),
   111  	"true":      vars.NewReadOnly(true),
   112  	"false":     vars.NewReadOnly(false),
   113  	"buildinfo": vars.NewReadOnly(buildinfo.Value),
   114  	"version":   vars.NewReadOnly(buildinfo.Value.Version),
   115  	"paths":     vars.NewEnvListVar("PATH"),
   116  })
   117  
   118  func addBuiltinFns(fns map[string]interface{}) {
   119  	builtinNs.AddGoFns(fns)
   120  }