website: Docs for all of the "filesystem" functions

This commit is contained in:
Martin Atkins 2018-05-13 12:30:21 -07:00
parent a491013054
commit a35c0f3cbf
6 changed files with 234 additions and 1 deletions

View File

@ -0,0 +1,43 @@
---
layout: "functions"
page_title: "basename function"
sidebar_current: "docs-funcs-file-basename"
description: |-
The basename function removes all except the last portion from a filesystem
path.
---
# `basename` Function
`basename` takes a string containing a filesystem path and removes all except
the last portion from it.
This function works only with the path string and does not access the
filesystem itself. It is therefore unable to take into account filesystem
features such as symlinks.
If the path is empty then the result is `"."`, representing the current
working directory.
The behavior of this function depends on the host platform. On Windows systems,
it uses backslash `\` as the path segment separator. On Unix systems, the slash
`/` is used.
Referring directly to filesystem paths in resource arguments may cause
spurious diffs if the same configuration is applied from multiple systems or on
different host operating systems. We recommend using filesystem paths only
for transient values, such as the argument to [`file`](./file.html) (where
only the contents are then stored) or in `connection` and `provisioner` blocks.
## Examples
```
> basename("foo/bar/baz.txt")
baz.txt
```
## Related Functions
* [`dirname`](./dirname.html) returns all of the segments of a filesystem path
_except_ the last, discarding the portion that would be returned by
`basename`.

View File

@ -0,0 +1,42 @@
---
layout: "functions"
page_title: "dirname function"
sidebar_current: "docs-funcs-file-dirname"
description: |-
The dirname function removes the last portion from a filesystem path.
---
# `dirname` Function
`dirname` takes a string containing a filesystem path and removes the last
portion from it.
This function works only with the path string and does not access the
filesystem itself. It is therefore unable to take into account filesystem
features such as symlinks.
If the path is empty then the result is `"."`, representing the current
working directory.
The behavior of this function depends on the host platform. On Windows systems,
it uses backslash `\` as the path segment separator. On Unix systems, the slash
`/` is used. The result of this function is normalized, so on a Windows system
any slashes in the given path will be replaced by backslashes before returning.
Referring directly to filesystem paths in resource arguments may cause
spurious diffs if the same configuration is applied from multiple systems or on
different host operating systems. We recommend using filesystem paths only
for transient values, such as the argument to [`file`](./file.html) (where
only the contents are then stored) or in `connection` and `provisioner` blocks.
## Examples
```
> dirname("foo/bar/baz.txt")
foo/bar
```
## Related Functions
* [`basename`](./basename.html) returns _only_ the last portion of a filesystem
path, discarding the portion that would be returned by `dirname`.

View File

@ -0,0 +1,44 @@
---
layout: "functions"
page_title: "file function"
sidebar_current: "docs-funcs-file-file-x"
description: |-
The file function reads the contents of the file at the given path and
returns them as a string.
---
# `file` Function
`file` reads the contents of a file at the given path and returns them as
a string.
```hcl
file(path)
```
Strings in the Terraform language are sequences of Unicode characters, so
this function will interpret the file contents as UTF-8 encoded text and
return the resulting Unicode characters. If the file contains invalid UTF-8
sequences then this function will produce an error.
This function can be used only with functions that already exist as static
files on disk at the beginning of a Terraform run. Language functions do not
participate in the dependency graph, so this function cannot be used with
files that are generated dynamically during a Terraform operation. We do not
recommend using of dynamic local files in Terraform configurations, but in rare
situations where this is necessary you can use
[the `local_file` data source](/docs/providers/local/d/file.html)
to read files while respecting resource dependencies.
## Examples
```
> file("${path.module}/hello.txt")
Hello World
```
## Related Functions
* [`filebase64`](./filebase64.html) also reads the contents of a given file,
but returns the raw bytes in that file Base64-encoded, rather than
interpreting the contents as UTF-8 text.

View File

@ -0,0 +1,48 @@
---
layout: "functions"
page_title: "filebase64 function"
sidebar_current: "docs-funcs-file-filebase64"
description: |-
The filebase64 function reads the contents of the file at the given path and
returns them as a base64-encoded string.
---
# `filebase64` Function
`filebase64` reads the contents of a file at the given path and returns them as
a base64-encoded string.
```hcl
filebase64(path)
```
The result is a Base64 representation of the raw bytes in the given file.
Strings in the Terraform language are sequences of Unicode characters, so
Base64 is the standard way to represent raw binary data that cannot be
interpreted as Unicode characters. Resource types that operate on binary
data will accept this data encoded in Base64, thus avoiding the need to
decode the result of this function.
Terraform uses the "standard" Base64 alphabet as defined in
[RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4).
This function can be used only with functions that already exist as static
files on disk at the beginning of a Terraform run. Language functions do not
participate in the dependency graph, so this function cannot be used with
files that are generated dynamically during a Terraform operation.
## Examples
```
> filebase64("${path.module}/hello.txt")
SGVsbG8gV29ybGQ=
```
## Related Functions
* [`file`](./file.html) also reads the contents of a given file,
but interprets the data as UTF-8 text and returns the result directly
as a string, without any further encoding.
* [`base64decode`](./base64decode.html) can decode a Base64 string representing
bytes in UTF-8, but in practice `base64decode(filebase64(...))` is equivalent
to the shorter expression `file(...)`.

View File

@ -0,0 +1,56 @@
---
layout: "functions"
page_title: "pathexpand function"
sidebar_current: "docs-funcs-file-pathexpand"
description: |-
The pathexpand function expands a leading ~ character to the current user's
home directory.
---
# `pathexpand` Function
`pathexpand` takes a filesystem path that might begin with a `~` segment,
and if so it replaces that segment with the current user's home directory
path.
This function works only with the path string and does not access the
filesystem itself. It is therefore unable to take into account filesystem
features such as symlinks.
If the leading segment in the path is not `~` then the given path is returned
unmodified.
Using this function in resource arguments will cause spurious diffs if the
same configuration is run by multiple users with different home directory
paths, or used on different host operating systems. We recommend using this
function only for transient values, such as in `connection` and `provisioner`
blocks to locate SSH keys, etc.
The rules for determining the "home directory" for the current user vary
depending on host operating system.
**For Unix systems**, the following sources are consulted, in order of preference:
* The `HOME` environment variable.
* The result of running `getent passwd` followed by the Terraform process uid.
* The result of running `cd && pwd` in `sh`.
**For Windows systems**, there is not really the concept of a home directory
in the same sense as on Unix, but the following sources are consulted in
order of preference:
* The `HOME` environment variable.
* The `HOMEDRIVE` and `HOMEPATH` environment variables, if both are set.
* The `USERPROFILE` environment variable.
The exact rules employed for each operating system may change in future
releases of Terraform.
## Examples
```
> pathexpand("~/.ssh/id_rsa")
/home/steve/.ssh/id_rsa
> pathexpand("/etc/resolv.conf")
/etc/resolv.conf
```

View File

@ -233,7 +233,7 @@
<a href="/docs/configuration/functions/basename.html">basename</a> <a href="/docs/configuration/functions/basename.html">basename</a>
</li> </li>
<li<%= sidebar_current("docs-funcs-file-file") %>> <li<%= sidebar_current("docs-funcs-file-file-x") %>>
<a href="/docs/configuration/functions/file.html">file</a> <a href="/docs/configuration/functions/file.html">file</a>
</li> </li>