From 2e1ed890b85d4ecf1a6332cf2e0c121d5640b496 Mon Sep 17 00:00:00 2001 From: Vincent LE GOFF Date: Mon, 18 Mar 2019 16:08:01 +0100 Subject: [PATCH] Documentation clean up (denoland/deno_std#288) Original: https://github.com/denoland/deno_std/commit/b699fa67befaef4423f365e55eff0fec2e14def8 --- colors/test.ts | 2 +- datetime/README.md | 37 +++++++++++++++++++++++++ colors/example.ts => examples/colors.ts | 2 +- fs/glob.ts | 33 ++++++++++------------ strings/README.md | 26 +++++++++++++++++ testing/README.md | 9 +++++- 6 files changed, 88 insertions(+), 21 deletions(-) create mode 100644 datetime/README.md rename colors/example.ts => examples/colors.ts (68%) create mode 100644 strings/README.md diff --git a/colors/test.ts b/colors/test.ts index 0c9090c5fe..6f3f7e5a8b 100644 --- a/colors/test.ts +++ b/colors/test.ts @@ -2,7 +2,7 @@ import { test } from "../testing/mod.ts"; import { assertEquals } from "../testing/asserts.ts"; import { red, bgBlue, setEnabled, getEnabled } from "./mod.ts"; -import "./example.ts"; +import "../examples/colors.ts"; test(function singleColor() { assertEquals(red("Hello world"), "Hello world"); diff --git a/datetime/README.md b/datetime/README.md new file mode 100644 index 0000000000..470aba6513 --- /dev/null +++ b/datetime/README.md @@ -0,0 +1,37 @@ +# datetime + +Simple helper to help parse date strings into `Date`, with additionnal functions. + +## Usage + +### parseDate / parseDateTime + +- `parseDate()` - Take an input string and a format to parse the date. Supported formats are exported in `DateFormat`. +- `parseDateTime()` - Take an input string and a format to parse the dateTime. Supported formats are exported in `DateTimeFormat`. + +```ts +import { parseDate, parseDateTime } from 'https://deno.land/std/datetime/mod.ts' + +parseDate("03-01-2019", "dd-mm-yyyy") // output : new Date(2019, 1, 3) +parseDate("2019-01-03", "yyyy-mm-dd") // output : new Date(2019, 1, 3) +... + +parseDateTime("01-03-2019 16:34", "mm-dd-yyyy hh:mm") // output : new Date(2019, 1, 3, 16, 34) +parseDateTime("16:34 01-03-2019", "hh:mm mm-dd-yyyy") // output : new Date(2019, 1, 3, 16, 34) +... +``` + +### dayOfYear / currentDayOfYear + +- `dayOfYear()` - Returns the number of the day in the year. +- `currentDayOfYear()` - Returns the number of the current day in the year. + +```ts +import { + dayOfYear, + currentDayOfYear +} from "https://deno.land/std/datetime/mod.ts"; + +dayOfYear(new Date("2019-03-11T03:24:00")); // output: 70 +currentDayOfYear(); // output: ** depends on when you run it :) ** +``` diff --git a/colors/example.ts b/examples/colors.ts similarity index 68% rename from colors/example.ts rename to examples/colors.ts index c6bbd614db..9468e87688 100644 --- a/colors/example.ts +++ b/examples/colors.ts @@ -1,4 +1,4 @@ // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. -import { bgBlue, red, bold, italic } from "./mod.ts"; +import { bgBlue, red, bold, italic } from "../colors/mod.ts"; console.log(bgBlue(italic(red(bold("Hello world!"))))); diff --git a/fs/glob.ts b/fs/glob.ts index 4d4ccc7ce9..4e1dedda91 100644 --- a/fs/glob.ts +++ b/fs/glob.ts @@ -20,27 +20,24 @@ export interface GlobOptions { * Generate a regex based on glob pattern and options * This was meant to be using the the `fs.walk` function * but can be used anywhere else. + * Examples: + * + * Looking for all the `ts` files: + * walkSync(".", { + * match: [glob("*.ts")] + * }) + * + * Looking for all the `.json` files in any subfolder: + * walkSync(".", { + * match: [glob(join("a", "**", "*.json"),flags: "g", + * extended: true, + * globstar: true + * })] + * }) + * * @param glob - Glob pattern to be used * @param options - Specific options for the glob pattern * @returns A RegExp for the glob pattern - * @example - * Looking for all the `ts` files - * ```typescript - * walkSync(".", { - * match: [glob("*.ts")] - * }) - * ``` - * @example - * Looking for all the `.json` files in any subfolder - * of the `a` folder - * ```typescript - * walkSync(".", { - * match: [glob(join("a", "**", "*.json"),flags: "g", - * extended: true, - * globstar: true - * })] - * }) - * ``` */ export function glob(glob: string, options: GlobOptions = {}): RegExp { return globrex(glob, options).regex; diff --git a/strings/README.md b/strings/README.md new file mode 100644 index 0000000000..8b41fee672 --- /dev/null +++ b/strings/README.md @@ -0,0 +1,26 @@ +# Strings + +This module provides a few basic utilities to manipulate strings. + +## Usage + +### pad + +Input string is processed to output a string with a minimal length. +If the parameter `strict` is set to true, the output string length +is equal to the `strLen` parameter. + +Basic usage: + +```ts +import { pad } from "https://deno.land/std/strings/pad.ts"; +pad("deno", 6, { char: "*", side: "left" }) // output : "**deno" +pad("deno", 6, { char: "*", side: "right"}) // output : "deno**" +pad("denosorusrex", 6 { + char: "*", + side: "left", + strict: true, + strictSide: "right", + strictChar: "..." +}) // output : "den..." +``` diff --git a/testing/README.md b/testing/README.md index 05cb8b92e4..3d49c5a765 100644 --- a/testing/README.md +++ b/testing/README.md @@ -9,7 +9,7 @@ The module exports a `test` function which is the test harness in Deno. It accepts either a function (including async functions) or an object which contains a `name` property and a `fn` property. When running tests and outputting the results, the name of the past function is used, or if the -object is passed, the `name` property is used to identify the test. +object is passed, the `name` property is used to identify the test. If the assertion is false an `AssertionError` will be thrown. Asserts are exposed in `testing/asserts.ts` module. @@ -18,8 +18,13 @@ Asserts are exposed in `testing/asserts.ts` module. - `assert()` - Expects a boolean value, throws if the value is `false`. - `assertEquals()` - Uses the `equal` comparison and throws if the `actual` and `expected` are not equal. +- `assertNotEquals()` - Uses the `equal` comparison and throws if the `actual` and + `expected` are equal. - `assertStrictEq()` - Compares `actual` and `expected` strictly, therefore for non-primitives the values must reference the same instance. +- `assertStrContains()` - Make an assertion that `actual` contains `expected`. +- `assertMatch()` - Make an assertion that `actual` match RegExp `expected`. +- `assertArrayContains()` - Make an assertion that `actual` array contains the `expected` values. - `assertThrows()` - Expects the passed `fn` to throw. If `fn` does not throw, this function does. Also compares any errors thrown to an optional expected `Error` class and checks that the error `.message` includes an optional @@ -29,6 +34,8 @@ Asserts are exposed in `testing/asserts.ts` module. function will throw asynchronously. Also compares any errors thrown to an optional expected `Error` class and checks that the error `.message` includes an optional string. +- `unimplemented()` - Use this to stub out methods that will throw when invoked +- `unreachable()` - Used to assert unreachable code `runTests()` executes the declared tests.