From a35c0f3cbfa6147b1bd5a54decc633744118d7d3 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Sun, 13 May 2018 12:30:21 -0700 Subject: [PATCH] website: Docs for all of the "filesystem" functions --- .../configuration/functions/basename.html.md | 43 ++++++++++++++ .../configuration/functions/dirname.html.md | 42 ++++++++++++++ .../docs/configuration/functions/file.html.md | 44 +++++++++++++++ .../functions/filebase64.html.md | 48 ++++++++++++++++ .../functions/pathexpand.html.md | 56 +++++++++++++++++++ website/layouts/functions.erb | 2 +- 6 files changed, 234 insertions(+), 1 deletion(-) create mode 100644 website/docs/configuration/functions/basename.html.md create mode 100644 website/docs/configuration/functions/dirname.html.md create mode 100644 website/docs/configuration/functions/file.html.md create mode 100644 website/docs/configuration/functions/filebase64.html.md create mode 100644 website/docs/configuration/functions/pathexpand.html.md diff --git a/website/docs/configuration/functions/basename.html.md b/website/docs/configuration/functions/basename.html.md new file mode 100644 index 000000000..5731a7239 --- /dev/null +++ b/website/docs/configuration/functions/basename.html.md @@ -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`. diff --git a/website/docs/configuration/functions/dirname.html.md b/website/docs/configuration/functions/dirname.html.md new file mode 100644 index 000000000..bad955522 --- /dev/null +++ b/website/docs/configuration/functions/dirname.html.md @@ -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`. diff --git a/website/docs/configuration/functions/file.html.md b/website/docs/configuration/functions/file.html.md new file mode 100644 index 000000000..d1bd82e1e --- /dev/null +++ b/website/docs/configuration/functions/file.html.md @@ -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. diff --git a/website/docs/configuration/functions/filebase64.html.md b/website/docs/configuration/functions/filebase64.html.md new file mode 100644 index 000000000..6a1270561 --- /dev/null +++ b/website/docs/configuration/functions/filebase64.html.md @@ -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(...)`. diff --git a/website/docs/configuration/functions/pathexpand.html.md b/website/docs/configuration/functions/pathexpand.html.md new file mode 100644 index 000000000..cc5ac10e1 --- /dev/null +++ b/website/docs/configuration/functions/pathexpand.html.md @@ -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 +``` diff --git a/website/layouts/functions.erb b/website/layouts/functions.erb index 2e70a7d5d..13470416d 100644 --- a/website/layouts/functions.erb +++ b/website/layouts/functions.erb @@ -233,7 +233,7 @@ basename - > + > file