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| }