From 82c2752a6aec96a3f8f910b5403cf7bd5e80eb25 Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Thu, 4 Jan 2024 17:20:10 +0000 Subject: [PATCH] docs/howto: use path.{Base,Dir,Ext} to examine paths This adds a Commented CUE guide that demonstrates how to use path.Base, path.Dir, and path.Ext to access components of a file's name and path. A single guide was preferred, rather than 3 separate documents, to more accessibly display the relationship and potential overlap between the values the functions emit when given specific inputs. Preview-Path: /docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/ Signed-off-by: Jonathan Matthews Change-Id: I0c80c4fea19b018c902bcc3ffecefb7509083ca1 Dispatch-Trailer: {"type":"trybot","CL":1174212,"patchset":11,"ref":"refs/changes/12/1174212/11","targetBranch":"alpha"} --- .../en.md | 118 ++++++++++++++++++ .../gen_cache.cue | 18 +++ .../page.cue | 3 + .../index.md | 117 +++++++++++++++++ 4 files changed, 256 insertions(+) create mode 100644 content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/en.md create mode 100644 content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/gen_cache.cue create mode 100644 content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/page.cue create mode 100644 hugo/content/en/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/index.md diff --git a/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/en.md b/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/en.md new file mode 100644 index 000000000..39b84de66 --- /dev/null +++ b/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/en.md @@ -0,0 +1,118 @@ +--- +title: Using the built-in functions "path.Base", "path.Dir", and "path.Ext" to examine path and filename components +tags: +- commented cue +authors: +- jpluscplusm +toc_hide: true +--- + +This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}}) +demonstrates how to use the built-in functions +[`path.Base`](https://pkg.go.dev/cuelang.org/go/pkg/path#Base), +[`path.Dir`](https://pkg.go.dev/cuelang.org/go/pkg/path#Dir), and +[`path.Ext`](https://pkg.go.dev/cuelang.org/go/pkg/path#Ext) +to access components of a file's name and its path. + +{{{with code "en" "cc"}}} +# eval is used so the output's leaf values are horizontally aligned, allowing +# the user to more easily compare "Path" and "Dir" values visually +exec cue eval +cmp stdout out +-- file.cue -- +package example + +import "path" + +unixAbsolutePath: { + Path: "/foo/bar/baz.js" + Dir: path.Dir("/foo/baz/baz.js", path.Unix) + Base: path.Base("/foo/baz/baz.js", path.Unix) + Ext: path.Ext("/foo/baz/baz.js", path.Unix) +} + +unixDirectoryTraversal: { + Path: "foo/bar/../quux/a.js" + Dir: path.Dir(Path, path.Unix) + Base: path.Base(Path, path.Unix) + Ext: path.Ext(Path, path.Unix) +} + +unixDirtyPath: { + Path: "/foo///bar////baz.js" + Dir: path.Dir(Path, path.Unix) + Base: path.Base(Path, path.Unix) + Ext: path.Ext(Path, path.Unix) +} + +windowsAbsolutePath: { + Path: #"C:\foo\bar\baz.js"# + Dir: path.Dir(Path, path.Windows) + Base: path.Base(Path, path.Windows) + Ext: path.Ext(Path, path.Windows) +} + +windowsDirectoryTraversal: { + Path: #"C:\foo\bar\..\quux\a.js"# + Dir: path.Dir(Path, path.Windows) + Base: path.Base(Path, path.Windows) + Ext: path.Ext(Path, path.Windows) +} + +windowsDirtyPath: { + Path: #"C:\foo\\bar\\\baz.js"# + Dir: path.Dir(Path, path.Windows) + Base: path.Base(Path, path.Windows) + Ext: path.Ext(Path, path.Windows) +} +-- out -- +unixAbsolutePath: { + Path: "/foo/bar/baz.js" + Dir: "/foo/baz" + Base: "baz.js" + Ext: ".js" +} +unixDirectoryTraversal: { + Path: "foo/bar/../quux/a.js" + Dir: "foo/quux" + Base: "a.js" + Ext: ".js" +} +unixDirtyPath: { + Path: "/foo///bar////baz.js" + Dir: "/foo/bar" + Base: "baz.js" + Ext: ".js" +} +windowsAbsolutePath: { + Path: "C:\\foo\\bar\\baz.js" + Dir: "C:\\foo\\bar" + Base: "baz.js" + Ext: ".js" +} +windowsDirectoryTraversal: { + Path: "C:\\foo\\bar\\..\\quux\\a.js" + Dir: "C:\\foo\\quux" + Base: "a.js" + Ext: ".js" +} +windowsDirtyPath: { + Path: "C:\\foo\\\\bar\\\\\\baz.js" + Dir: "C:\\foo\\bar" + Base: "baz.js" + Ext: ".js" +} +{{{end}}} + +## Related content + +- The [`path`](https://pkg.go.dev/cuelang.org/go/pkg/path) built-in package + documentation details the rules that each of the functions + [`path.Base`](https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/path#Base), + [`path.Dir`](https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/path#Dir), and + [`path.Ext`](https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/path#Ext) follow + as they process their input +- Using CUE's ["raw" strings]({{< relref "docs/tour/types/stringraw" >}}) is + convenient when writing literal Windows paths. They avoid having to escape + every backslash (`\\`), as is demonstrated in the Windows-related examples + above. diff --git a/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/gen_cache.cue b/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/gen_cache.cue new file mode 100644 index 000000000..3141ffe47 --- /dev/null +++ b/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/gen_cache.cue @@ -0,0 +1,18 @@ +package site +{ + content: { + docs: { + howto: { + "use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components": { + page: { + cache: { + code: { + cc: "rieKFrdRcJRkdhv3Iczudv4XjDviWBcTLffQhCfQi0s=" + } + } + } + } + } + } + } +} diff --git a/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/page.cue b/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/page.cue new file mode 100644 index 000000000..2625eb1d2 --- /dev/null +++ b/content/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/page.cue @@ -0,0 +1,3 @@ +package site + +content: docs: howto: "use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components": {} diff --git a/hugo/content/en/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/index.md b/hugo/content/en/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/index.md new file mode 100644 index 000000000..5a327744b --- /dev/null +++ b/hugo/content/en/docs/howto/use-the-built-in-functions-path-base-path-dir-path-ext-to-examine-path-filename-components/index.md @@ -0,0 +1,117 @@ +--- +title: Using the built-in functions "path.Base", "path.Dir", and "path.Ext" to examine path and filename components +tags: +- commented cue +authors: +- jpluscplusm +toc_hide: true +--- + +This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}}) +demonstrates how to use the built-in functions +[`path.Base`](https://pkg.go.dev/cuelang.org/go/pkg/path#Base), +[`path.Dir`](https://pkg.go.dev/cuelang.org/go/pkg/path#Dir), and +[`path.Ext`](https://pkg.go.dev/cuelang.org/go/pkg/path#Ext) +to access components of a file's name and its path. + +{{< code-tabs >}} +{{< code-tab name="file.cue" language="cue" area="top-left" >}} +package example + +import "path" + +unixAbsolutePath: { + Path: "/foo/bar/baz.js" + Dir: path.Dir("/foo/baz/baz.js", path.Unix) + Base: path.Base("/foo/baz/baz.js", path.Unix) + Ext: path.Ext("/foo/baz/baz.js", path.Unix) +} + +unixDirectoryTraversal: { + Path: "foo/bar/../quux/a.js" + Dir: path.Dir(Path, path.Unix) + Base: path.Base(Path, path.Unix) + Ext: path.Ext(Path, path.Unix) +} + +unixDirtyPath: { + Path: "/foo///bar////baz.js" + Dir: path.Dir(Path, path.Unix) + Base: path.Base(Path, path.Unix) + Ext: path.Ext(Path, path.Unix) +} + +windowsAbsolutePath: { + Path: #"C:\foo\bar\baz.js"# + Dir: path.Dir(Path, path.Windows) + Base: path.Base(Path, path.Windows) + Ext: path.Ext(Path, path.Windows) +} + +windowsDirectoryTraversal: { + Path: #"C:\foo\bar\..\quux\a.js"# + Dir: path.Dir(Path, path.Windows) + Base: path.Base(Path, path.Windows) + Ext: path.Ext(Path, path.Windows) +} + +windowsDirtyPath: { + Path: #"C:\foo\\bar\\\baz.js"# + Dir: path.Dir(Path, path.Windows) + Base: path.Base(Path, path.Windows) + Ext: path.Ext(Path, path.Windows) +} +{{< /code-tab >}} +{{< code-tab name="TERMINAL" language="" type="terminal" area="top-right" >}} +$ cue eval +unixAbsolutePath: { + Path: "/foo/bar/baz.js" + Dir: "/foo/baz" + Base: "baz.js" + Ext: ".js" +} +unixDirectoryTraversal: { + Path: "foo/bar/../quux/a.js" + Dir: "foo/quux" + Base: "a.js" + Ext: ".js" +} +unixDirtyPath: { + Path: "/foo///bar////baz.js" + Dir: "/foo/bar" + Base: "baz.js" + Ext: ".js" +} +windowsAbsolutePath: { + Path: "C:\\foo\\bar\\baz.js" + Dir: "C:\\foo\\bar" + Base: "baz.js" + Ext: ".js" +} +windowsDirectoryTraversal: { + Path: "C:\\foo\\bar\\..\\quux\\a.js" + Dir: "C:\\foo\\quux" + Base: "a.js" + Ext: ".js" +} +windowsDirtyPath: { + Path: "C:\\foo\\\\bar\\\\\\baz.js" + Dir: "C:\\foo\\bar" + Base: "baz.js" + Ext: ".js" +} +{{< /code-tab >}} +{{< /code-tabs >}} + +## Related content + +- The [`path`](https://pkg.go.dev/cuelang.org/go/pkg/path) built-in package + documentation details the rules that each of the functions + [`path.Base`](https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/path#Base), + [`path.Dir`](https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/path#Dir), and + [`path.Ext`](https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/path#Ext) follow + as they process their input +- Using CUE's ["raw" strings]({{< relref "docs/tour/types/stringraw" >}}) is + convenient when writing literal Windows paths. They avoid having to escape + every backslash (`\\`), as is demonstrated in the Windows-related examples + above.