ns: file
preamble: |
  Functions for working with files.
funcs:
  - name: file.Exists
    released: v2.4.0
    description: |
      Reports whether a file or directory exists at the given path.
    pipeline: true
    arguments:
      - name: path
        required: true
        description: The path
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ if (file.Exists "/tmp/foo") }}yes{{else}}no{{end}}
        ```

        ```console
        $ gomplate -f input.tmpl
        no
        $ touch /tmp/foo
        $ gomplate -f input.tmpl
        yes
        ```
  - name: file.IsDir
    released: v2.4.0
    description: |
      Reports whether a given path is a directory.
    pipeline: true
    arguments:
      - name: path
        required: true
        description: The path
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ if (file.IsDir "/tmp/foo") }}yes{{else}}no{{end}}
        ```

        ```console
        $ gomplate -f input.tmpl
        no
        $ touch /tmp/foo
        $ gomplate -f input.tmpl
        no
        $ rm /tmp/foo && mkdir /tmp/foo
        $ gomplate -f input.tmpl
        yes
        ```
  - name: file.Read
    released: v2.4.0
    description: |
      Reads a given file _as text_. Note that this will succeed if the given file is binary, but the output may be gibberish.
    pipeline: true
    arguments:
      - name: path
        required: true
        description: The path
    examples:
      - |
        $ echo "hello world" > /tmp/hi
        $ gomplate -i '{{file.Read "/tmp/hi"}}'
        hello world
  - name: file.ReadDir
    released: v2.4.0
    description: |
      Reads a directory and lists the files and directories contained within.
    pipeline: true
    arguments:
      - name: path
        required: true
        description: The path
    examples:
      - |
        $ mkdir /tmp/foo
        $ touch /tmp/foo/a; touch /tmp/foo/b; touch /tmp/foo/c
        $ mkdir /tmp/foo/d
        $ gomplate -i '{{ range (file.ReadDir "/tmp/foo") }}{{.}}{{"\n"}}{{end}}'
        a
        b
        c
        d
  - name: file.Stat
    released: v2.4.0
    description: |
      Returns a [`os.FileInfo`](https://pkg.go.dev/os/#FileInfo) describing the named path.

      Essentially a wrapper for Go's [`os.Stat`](https://pkg.go.dev/os/#Stat) function.
    pipeline: true
    arguments:
      - name: path
        required: true
        description: The path
    examples:
      - |
        $ echo "hello world" > /tmp/foo
        $ gomplate -i '{{ $s := file.Stat "/tmp/foo" }}{{ $s.Mode }} {{ $s.Size }} {{ $s.Name }}'
        -rw-r--r-- 12 foo
  - name: file.Walk
    released: v2.6.0
    description: |
      Like a recursive [`file.ReadDir`](#filereaddir), recursively walks the file tree rooted at `path`, and returns an array of all files and directories contained within.

      The files are walked in lexical order, which makes the output deterministic but means that for very large directories can be inefficient.

      Walk does not follow symbolic links.

      Similar to Go's [`filepath.Walk`](https://pkg.go.dev/path/filepath/#Walk) function.
    pipeline: true
    arguments:
      - name: path
        required: true
        description: The path
    examples:
      - |
        $ tree /tmp/foo
        /tmp/foo
        ├── one
        ├── sub
        │   ├── one
        │   └── two
        ├── three
        └── two

        1 directory, 5 files
        $ gomplate -i '{{ range file.Walk "/tmp/foo" }}{{ if not (file.IsDir .) }}{{.}} is a file{{"\n"}}{{end}}{{end}}'
        /tmp/foo/one is a file
        /tmp/foo/sub/one is a file
        /tmp/foo/sub/two is a file
        /tmp/foo/three is a file
        /tmp/foo/two is a file
  - name: file.Write
    released: v2.4.0
    description: |
      Write the given data to the given file. If the file exists, it will be overwritten.

      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.

      Non-existing directories in the output path will be created.

      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.
    pipeline: true
    arguments:
      - name: filename
        required: true
        description: The name of the file to write to
      - name: data
        required: true
        description: The data to write
    examples:
      - |
        $ gomplate -i '{{ file.Write "/tmp/foo" "hello world" }}'
        $ cat /tmp/foo
        hello world