Merge pull request #493 from hairyhenderson/file-write-create-dirs

file.Write should create non-existing subdirectories

1 files changed, 151 insertions, 0 deletions

diff --git a/docs-src/content/functions/file.yml b/docs-src/content/functions/file.yml
new file mode 100644
index 00000000..8589cbb6
--- /dev/null
+++ b/docs-src/content/functions/file.yml
@@ -0,0 +1,151 @@
+ns: file
+preamble: |
+  Functions for working with files.
+funcs:
+  - name: file.Exists
+    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
+    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
+    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
+    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
+    description: |
+      Returns a [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo) describing the named path.
+
+      Essentially a wrapper for Go's [`os.Stat`](https://golang.org/pkg/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
+    description: |
+      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.
+
+      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://golang.org/pkg/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
+    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