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