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

     1  # Outputs whether `$file` is a terminal device.
     2  #
     3  # The `$file` can be a file object or a number. If it's a number, it's
     4  # interpreted as the number of an [IO port](language.html#io-ports).
     5  #
     6  # ```elvish-transcript
     7  # ~> var f = (file:open /dev/tty)
     8  # ~> file:is-tty $f
     9  # ▶ $true
    10  # ~> file:close $f
    11  # ~> var f = (file:open /dev/null)
    12  # ~> file:is-tty $f
    13  # ▶ $false
    14  # ~> file:close $f
    15  # ~> var p = (file:pipe)
    16  # ~> file:is-tty $p[r]
    17  # ▶ $false
    18  # ~> file:is-tty $p[w]
    19  # ▶ $false
    20  # ~> file:close $p[r]
    21  # ~> file:close $p[w]
    22  # ~> file:is-tty 0
    23  # ▶ $true
    24  # ~> file:is-tty 1
    25  # ▶ $true
    26  # ~> file:is-tty 2
    27  # ▶ $true
    28  # ~> file:is-tty 0 < /dev/null
    29  # ▶ $false
    30  # ~> file:is-tty 0 < /dev/tty
    31  # ▶ $true
    32  # ```
    33  fn is-tty {|file| }
    34  
    35  # Opens a file for input. The file must be closed with [`file:close`]() when no
    36  # longer needed.
    37  #
    38  # Example:
    39  #
    40  # ```elvish-transcript
    41  # ~> cat a.txt
    42  # This is
    43  # a file.
    44  # ~> use file
    45  # ~> var f = (file:open a.txt)
    46  # ~> cat < $f
    47  # This is
    48  # a file.
    49  # ~> file:close $f
    50  # ```
    51  #
    52  # See also [`file:open-output`]() and [`file:close`]().
    53  fn open {|filename| }
    54  
    55  # Opens a file for output. The file must be closed with [`file:close`]() when no
    56  # longer needed.
    57  #
    58  # If `&also-input` is true, the file may also be used for input.
    59  #
    60  # The `&if-not-exists` option can be either `create` or `error`.
    61  #
    62  # The `&if-exists` option can be either `truncate` (removing all data), `append`
    63  # (appending to the end), `update` (updating in place) or `error`. The `error`
    64  # value may only be used with `&if-not-exists=create`.
    65  #
    66  # The `&create-perm` option specifies what permission to create the file with if
    67  # the file doesn't exist and `&if-not-exists=create`. It must be an integer
    68  # within [0, 0o777]. On Unix, the actual file permission is subject to filtering
    69  # by [`$unix:umask`]().
    70  #
    71  # Example:
    72  #
    73  # ```elvish-transcript
    74  # ~> use file
    75  # ~> var f = (file:open-output new)
    76  # ~> echo content > $f
    77  # ~> file:close $f
    78  # ~> cat new
    79  # content
    80  # ```
    81  #
    82  # See also [`file:open`]() and [`file:close`]().
    83  fn open-output {|filename &also-input=$false &if-not-exists=create &if-exists=truncate &create-perm=(num 0o644)| }
    84  
    85  # Closes a file opened with `open`.
    86  #
    87  # See also [`file:open`]().
    88  fn close {|file| }
    89  
    90  # Creates a new pipe that can be used in redirections. Outputs a map with two
    91  # fields: `r` contains the read-end of the pipe, and `w` contains the write-end.
    92  # Both are [file object](language.html#file))
    93  #
    94  # When redirecting command input from a pipe with `<`, the read-end is used. When redirecting
    95  # command output to a pipe with `>`, the write-end is used. Redirecting both input and output with
    96  # `<>` to a pipe is not supported.
    97  #
    98  # Pipes have an OS-dependent buffer, so writing to a pipe without an active
    99  # reader does not necessarily block. Both ends of the pipes must be explicitly
   100  # closed with `file:close`.
   101  #
   102  # Putting values into pipes will cause those values to be discarded.
   103  #
   104  # Examples (assuming the pipe has a large enough buffer):
   105  #
   106  # ```elvish-transcript
   107  # ~> var p = (file:pipe)
   108  # ~> echo 'lorem ipsum' > $p
   109  # ~> head -n1 < $p
   110  # lorem ipsum
   111  # ~> put 'lorem ipsum' > $p
   112  # ~> file:close $p[w] # close the write-end
   113  # ~> head -n1 < $p # blocks unless the write-end is closed
   114  # ~> file:close $p[r] # close the read-end
   115  # ```
   116  #
   117  # See also [`file:close`]().
   118  fn pipe { }
   119  
   120  # Sets the offset for the next read or write operation on `$file`.
   121  #
   122  # The `&whence` option specifies what the offset is relative to, and can be
   123  # `start`, `current` or `end`.
   124  #
   125  # The behavior of `seek` on a file opened using [`file:open-output`]() with
   126  # `&if-exists=append` is unspecified.
   127  #
   128  # Example:
   129  #
   130  # ```elvish-transcript
   131  # ~> print 0123456789 > file
   132  # ~> var f = (file:open file)
   133  # ~> read-bytes 3 < $f
   134  # ▶ 012
   135  # ~> file:seek $f 0
   136  # ~> read-bytes 3 < $f
   137  # ▶ 012
   138  # ~> file:seek $f 2 &whence=current
   139  # ~> read-bytes 3 < $f
   140  # ▶ 567
   141  # ~> file:seek $f -3 &whence=end
   142  # ~> read-bytes 3 < $f
   143  # ▶ 789
   144  # ~> file:close $f
   145  # ```
   146  fn seek {|file offset &whence=start| }
   147  
   148  # Outputs the current offset within `$file`, relative to the start of the file.
   149  #
   150  # Example:
   151  #
   152  # ```elvish-transcript
   153  # ~> print 0123456789 > file
   154  # ~> var f = (file:open file)
   155  # ~> read-bytes 3 < $f
   156  # ▶ 012
   157  # ~> file:tell $f
   158  # ▶ (num 3)
   159  # ~> file:close $f
   160  # ```
   161  fn tell {|file| }
   162  
   163  # changes the size of the named file. If the file is a symbolic link, it
   164  # changes the size of the link's target. The size must be an integer between 0
   165  # and 2^64-1.
   166  fn truncate {|filename size| }