github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs/content/functions/file.md (about) 1 --- 2 title: file functions 3 menu: 4 main: 5 parent: functions 6 --- 7 8 Functions for working with files. 9 10 ## `file.Exists` 11 12 Reports whether a file or directory exists at the given path. 13 14 _Added in gomplate [v2.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.4.0)_ 15 ### Usage 16 17 ``` 18 file.Exists path 19 ``` 20 ``` 21 path | file.Exists 22 ``` 23 24 ### Arguments 25 26 | name | description | 27 |------|-------------| 28 | `path` | _(required)_ The path | 29 30 ### Examples 31 32 _`input.tmpl`:_ 33 ``` 34 {{ if (file.Exists "/tmp/foo") }}yes{{else}}no{{end}} 35 ``` 36 37 ```console 38 $ gomplate -f input.tmpl 39 no 40 $ touch /tmp/foo 41 $ gomplate -f input.tmpl 42 yes 43 ``` 44 45 ## `file.IsDir` 46 47 Reports whether a given path is a directory. 48 49 _Added in gomplate [v2.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.4.0)_ 50 ### Usage 51 52 ``` 53 file.IsDir path 54 ``` 55 ``` 56 path | file.IsDir 57 ``` 58 59 ### Arguments 60 61 | name | description | 62 |------|-------------| 63 | `path` | _(required)_ The path | 64 65 ### Examples 66 67 _`input.tmpl`:_ 68 ``` 69 {{ if (file.IsDir "/tmp/foo") }}yes{{else}}no{{end}} 70 ``` 71 72 ```console 73 $ gomplate -f input.tmpl 74 no 75 $ touch /tmp/foo 76 $ gomplate -f input.tmpl 77 no 78 $ rm /tmp/foo && mkdir /tmp/foo 79 $ gomplate -f input.tmpl 80 yes 81 ``` 82 83 ## `file.Read` 84 85 Reads a given file _as text_. Note that this will succeed if the given file is binary, but the output may be gibberish. 86 87 _Added in gomplate [v2.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.4.0)_ 88 ### Usage 89 90 ``` 91 file.Read path 92 ``` 93 ``` 94 path | file.Read 95 ``` 96 97 ### Arguments 98 99 | name | description | 100 |------|-------------| 101 | `path` | _(required)_ The path | 102 103 ### Examples 104 105 ```console 106 $ echo "hello world" > /tmp/hi 107 $ gomplate -i '{{file.Read "/tmp/hi"}}' 108 hello world 109 ``` 110 111 ## `file.ReadDir` 112 113 Reads a directory and lists the files and directories contained within. 114 115 _Added in gomplate [v2.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.4.0)_ 116 ### Usage 117 118 ``` 119 file.ReadDir path 120 ``` 121 ``` 122 path | file.ReadDir 123 ``` 124 125 ### Arguments 126 127 | name | description | 128 |------|-------------| 129 | `path` | _(required)_ The path | 130 131 ### Examples 132 133 ```console 134 $ mkdir /tmp/foo 135 $ touch /tmp/foo/a; touch /tmp/foo/b; touch /tmp/foo/c 136 $ mkdir /tmp/foo/d 137 $ gomplate -i '{{ range (file.ReadDir "/tmp/foo") }}{{.}}{{"\n"}}{{end}}' 138 a 139 b 140 c 141 d 142 ``` 143 144 ## `file.Stat` 145 146 Returns a [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo) describing the named path. 147 148 Essentially a wrapper for Go's [`os.Stat`](https://golang.org/pkg/os/#Stat) function. 149 150 _Added in gomplate [v2.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.4.0)_ 151 ### Usage 152 153 ``` 154 file.Stat path 155 ``` 156 ``` 157 path | file.Stat 158 ``` 159 160 ### Arguments 161 162 | name | description | 163 |------|-------------| 164 | `path` | _(required)_ The path | 165 166 ### Examples 167 168 ```console 169 $ echo "hello world" > /tmp/foo 170 $ gomplate -i '{{ $s := file.Stat "/tmp/foo" }}{{ $s.Mode }} {{ $s.Size }} {{ $s.Name }}' 171 -rw-r--r-- 12 foo 172 ``` 173 174 ## `file.Walk` 175 176 Like a recursive [`file.ReadDir`](#file-readdir), recursively walks the file tree rooted at `path`, and returns an array of all files and directories contained within. 177 178 The files are walked in lexical order, which makes the output deterministic but means that for very large directories can be inefficient. 179 180 Walk does not follow symbolic links. 181 182 Similar to Go's [`filepath.Walk`](https://golang.org/pkg/path/filepath/#Walk) function. 183 184 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 185 ### Usage 186 187 ``` 188 file.Walk path 189 ``` 190 ``` 191 path | file.Walk 192 ``` 193 194 ### Arguments 195 196 | name | description | 197 |------|-------------| 198 | `path` | _(required)_ The path | 199 200 ### Examples 201 202 ```console 203 $ tree /tmp/foo 204 /tmp/foo 205 ├── one 206 ├── sub 207 │ ├── one 208 │ └── two 209 ├── three 210 └── two 211 212 1 directory, 5 files 213 $ gomplate -i '{{ range file.Walk "/tmp/foo" }}{{ if not (file.IsDir .) }}{{.}} is a file{{"\n"}}{{end}}{{end}}' 214 /tmp/foo/one is a file 215 /tmp/foo/sub/one is a file 216 /tmp/foo/sub/two is a file 217 /tmp/foo/three is a file 218 /tmp/foo/two is a file 219 ``` 220 221 ## `file.Write` 222 223 Write the given data to the given file. If the file exists, it will be overwritten. 224 225 For increased security, `file.Write` will only write to files which are contained within the current working directory. Attempts to write elsewhere will fail with an error. 226 227 Non-existing directories in the output path will be created. 228 229 If the data is a byte array (`[]byte`), it will be written as-is. Otherwise, it will be converted to a string before being written. 230 231 _Added in gomplate [v2.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.4.0)_ 232 ### Usage 233 234 ``` 235 file.Write filename data 236 ``` 237 ``` 238 data | file.Write filename 239 ``` 240 241 ### Arguments 242 243 | name | description | 244 |------|-------------| 245 | `filename` | _(required)_ The name of the file to write to | 246 | `data` | _(required)_ The data to write | 247 248 ### Examples 249 250 ```console 251 $ gomplate -i '{{ file.Write "/tmp/foo" "hello world" }}' 252 $ cat /tmp/foo 253 hello world 254 ```