From 4d71bb0cdf9570090ee3d3247cef1007ec5c4f17 Mon Sep 17 00:00:00 2001 From: Matthew McCune Date: Thu, 10 Oct 2024 16:00:52 -0700 Subject: [PATCH] docs(path): re-add URL examples to `@std/path/posix` examples --- path/posix/basename.ts | 17 +++++++++++++++++ path/posix/dirname.ts | 12 ++++++++++++ path/posix/extname.ts | 16 ++++++++++++++++ path/posix/join.ts | 13 +++++++++++++ path/posix/mod.ts | 7 +++++++ path/posix/normalize.ts | 18 ++++++++++++++++++ 6 files changed, 83 insertions(+) diff --git a/path/posix/basename.ts b/path/posix/basename.ts index ff4d1c4087a6..b772a212785d 100644 --- a/path/posix/basename.ts +++ b/path/posix/basename.ts @@ -23,6 +23,23 @@ import { isPosixPathSeparator } from "./_util.ts"; * assertEquals(basename("/home/user/Documents/image.png", ".png"), "image"); * ``` * + * @example Working with URLs + * + * Note: This function doesn't automatically strip hash and query parts from + * URLs. If your URL contains a hash or query, remove them before passing the + * URL to the function. This can be done by passing the URL to `new URL(url)`, + * and setting the `hash` and `search` properties to empty strings. + * + * ```ts + * import { basename } from "@std/path/posix/basename"; + * import { assertEquals } from "@std/assert"; + * + * assertEquals(basename("https://deno.land/std/path/mod.ts"), "mod.ts"); + * assertEquals(basename("https://deno.land/std/path/mod.ts", ".ts"), "mod"); + * assertEquals(basename("https://deno.land/std/path/mod.ts?a=b"), "mod.ts?a=b"); + * assertEquals(basename("https://deno.land/std/path/mod.ts#header"), "mod.ts#header"); + * ``` + * * Note: If you are working with file URLs, * use the new version of `basename` from `@std/path/posix/unstable-basename`. * diff --git a/path/posix/dirname.ts b/path/posix/dirname.ts index e927b085ffd4..38064b8ab895 100644 --- a/path/posix/dirname.ts +++ b/path/posix/dirname.ts @@ -15,6 +15,18 @@ import { isPosixPathSeparator } from "./_util.ts"; * * assertEquals(dirname("/home/user/Documents/"), "/home/user"); * assertEquals(dirname("/home/user/Documents/image.png"), "/home/user/Documents"); + * assertEquals(dirname("https://deno.land/std/path/mod.ts"), "https://deno.land/std/path"); + * ``` + * + * @example Working with URLs + * + * ```ts + * import { dirname } from "@std/path/posix/dirname"; + * import { assertEquals } from "@std/assert"; + * + * assertEquals(dirname("https://deno.land/std/path/mod.ts"), "https://deno.land/std/path"); + * assertEquals(dirname("https://deno.land/std/path/mod.ts?a=b"), "https://deno.land/std/path"); + * assertEquals(dirname("https://deno.land/std/path/mod.ts#header"), "https://deno.land/std/path"); * ``` * * Note: If you are working with file URLs, diff --git a/path/posix/extname.ts b/path/posix/extname.ts index ff579e424b29..eca1f61ef141 100644 --- a/path/posix/extname.ts +++ b/path/posix/extname.ts @@ -18,6 +18,22 @@ import { isPosixPathSeparator } from "./_util.ts"; * assertEquals(extname("/home/user/Documents/image.png"), ".png"); * ``` * + * @example Working with URLs + * + * Note: This function doesn't automatically strip hash and query parts from + * URLs. If your URL contains a hash or query, remove them before passing the + * URL to the function. This can be done by passing the URL to `new URL(url)`, + * and setting the `hash` and `search` properties to empty strings. + * + * ```ts + * import { extname } from "@std/path/posix/extname"; + * import { assertEquals } from "@std/assert"; + * + * assertEquals(extname("https://deno.land/std/path/mod.ts"), ".ts"); + * assertEquals(extname("https://deno.land/std/path/mod.ts?a=b"), ".ts?a=b"); + * assertEquals(extname("https://deno.land/std/path/mod.ts#header"), ".ts#header"); + * ``` + * * Note: If you are working with file URLs, * use the new version of `extname` from `@std/path/posix/unstable-extname`. * diff --git a/path/posix/join.ts b/path/posix/join.ts index 54c6633e8d58..dc4ff9835c1e 100644 --- a/path/posix/join.ts +++ b/path/posix/join.ts @@ -16,6 +16,19 @@ import { normalize } from "./normalize.ts"; * assertEquals(path, "/foo/bar/baz/asdf"); * ``` * + * @example Working with URLs + * ```ts + * import { join } from "@std/path/posix/join"; + * import { assertEquals } from "@std/assert"; + * + * const url = new URL("https://deno.land"); + * url.pathname = join("std", "path", "mod.ts"); + * assertEquals(url.href, "https://deno.land/std/path/mod.ts"); + * + * url.pathname = join("//std", "path/", "/mod.ts"); + * assertEquals(url.href, "https://deno.land/std/path/mod.ts"); + * ``` + * * Note: If you are working with file URLs, * use the new version of `join` from `@std/path/posix/unstable-join`. * diff --git a/path/posix/mod.ts b/path/posix/mod.ts index cc977e11dd06..af1656695414 100644 --- a/path/posix/mod.ts +++ b/path/posix/mod.ts @@ -6,6 +6,13 @@ /** * Utilities for working with POSIX-formatted paths. * + * This module also provides some functions that help when working with URLs. + * See the documentation for examples. + * + * Codes in the examples uses POSIX path but it automatically use Windows path + * on Windows. Use methods under `posix` or `win32` object instead to handle non + * platform specific path like: + * * ```ts * import { fromFileUrl } from "@std/path/posix/from-file-url"; * import { assertEquals } from "@std/assert"; diff --git a/path/posix/normalize.ts b/path/posix/normalize.ts index 2258feb48f95..e8bdb64f4acf 100644 --- a/path/posix/normalize.ts +++ b/path/posix/normalize.ts @@ -19,6 +19,24 @@ import { isPosixPathSeparator } from "./_util.ts"; * assertEquals(path, "/foo/bar/baz/asdf"); * ``` * + * @example Working with URLs + * + * Note: This function will remove the double slashes from a URL's scheme. + * Hence, do not pass a full URL to this function. Instead, pass the pathname of + * the URL. + * + * ```ts + * import { normalize } from "@std/path/posix/normalize"; + * import { assertEquals } from "@std/assert"; + * + * const url = new URL("https://deno.land"); + * url.pathname = normalize("//std//assert//.//mod.ts"); + * assertEquals(url.href, "https://deno.land/std/assert/mod.ts"); + * + * url.pathname = normalize("std/assert/../async/retry.ts"); + * assertEquals(url.href, "https://deno.land/std/async/retry.ts"); + * ``` + * * Note: If you are working with file URLs, * use the new version of `normalize` from `@std/path/posix/unstable-normalize`. *