From 1d5d43534d535c917ec85080354e3e6b5ac054af Mon Sep 17 00:00:00 2001 From: Arman karimi <67087266+iArmann@users.noreply.github.com> Date: Thu, 25 Feb 2021 09:57:35 +0330 Subject: [PATCH] Closes #51 : Added index.d.ts + documentation for javascript and typescript (#59) Co-authored-by: Lachlan Heywood --- README.md | 69 +++++++++++++++++++--- index.d.ts | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++ index.js | 119 +++++++++++++++++++++++++++++++++++++ package.json | 1 + 4 files changed, 342 insertions(+), 9 deletions(-) create mode 100644 index.d.ts diff --git a/README.md b/README.md index c5f457f..1e5ecd7 100644 --- a/README.md +++ b/README.md @@ -49,17 +49,17 @@ It acts in the same way as the original cowsay, so consult `cowsay(1)` or run `c ## Usage as a module cowsay can be used as any other npm dependency +```js +var cowsay = require("cowsay"); - var cowsay = require("cowsay"); - - console.log(cowsay.say({ - text : "I'm a moooodule", - e : "oO", - T : "U " - })); - - // or cowsay.think() +console.log(cowsay.say({ + text : "I'm a moooodule", + e : "oO", + T : "U " +})); +// or cowsay.think() +``` ```` _________________ ( I'm a moooodule ) @@ -71,6 +71,57 @@ cowsay can be used as any other npm dependency || || ```` +getting a list of cow names: +```js +function get_cows(error, cow_names) { + if (error) { + console.log(error) + } + else if (cow_names) { + console.log(`Number of cows available: ${cow_names.length}`); + } +} + +cowsay.list(get_cows); +``` + +#### Typescript examples: +```ts +import * as cowsay from "cowsay" + +let output: string = cowsay.say({ text: 'Hello from typescript!' }); + +console.log(output); +``` + +getting a list of cow names: +```ts +function get_cows(error: NodeJS.ErrnoException, cow_names: Array): void { + if (error) { + console.log(`Error getting cow names: ${error.message}`) + } + else if (cow_names) { + console.log(`Number of cows available: ${cow_names.length}`); + } +} + +cowsay.list(get_cows); +``` + +importing the `IOptions` interface directly: +```ts +import { IOptions } from "cowsay" // optional + +let opts: IOptions = { + text: "Hello from TypeScript!", + e: '^^', + r: true, +}; + +console.log(cowsay.say(opts)); +``` + + ## Pipe from standard input echo please repeat | cowsay diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..2537ffd --- /dev/null +++ b/index.d.ts @@ -0,0 +1,162 @@ +/** + * @property text : text + * + * @Cow + * @property f : cow name + * @property r : random selection + * + * @Face + * @property T : Tongue + * @property e : eyes + * + * @Modes + * @property b : borg + * @property d : dead + * @property g : greedy + * @property p : paranoia + * @property s : stoned + * @property t : tired + * @property w : wired + * @property y : youthful + */ +export interface IOptions { + text: string, + // cow + f?: string, // cow name + r?: boolean, // random mode + // face + e?: string, // eyes + T?: string, // tongue + // modes + b?: boolean, // borg + d?: boolean, // dead + g?: boolean, // greedy + p?: boolean, // paranoia + s?: boolean, // stoned + t?: boolean, // tired + w?: boolean, // wired + y?: boolean, // youthful +} + +type callback_type = (error: NodeJS.ErrnoException, cow_names: string[]) => void; + +/** + * @param callback + * @returns a list of cow names from the cows folder without the .cow extension. + * @example + * ``` + * function get_cows(error: NodeJS.ErrnoException, cow_names: Array): void { + * if (error) { + * console.log(`Error getting cow names: ${error.message}`); + * } + * else if (cow_names) { + * console.log(`Number of cows available: ${cow_names.length}`); + * } + * } + * + * cowsay.list(get_cows); + * ``` + */ +export function list(callback: callback_type): Promise; + +/** + * @param options + * ## Face : + * Either choose a mode (set the value as true) **_or_** + * set your own defined eyes and tongue to `e` and `T`. + * - ### `e` : eyes + * - ### `T` : tongue + * + * ## Cow : + * Either specify a cow name (e.g. "fox") **_or_** + * set the value of `r` to true which selects a random cow. + * - ### `r` : random selection + * - ### `f` : cow name - from `cows` folder + * + * ## Modes : + * Modes are just ready-to-use faces, here's their list: + * - #### `b` : borg + * - #### `d` : dead + * - #### `g` : greedy + * - #### `p` : paranoia + * - #### `s` : stoned + * - #### `t` : tired + * - #### `w` : wired + * - #### `y` : youthful + * + * @example + * ``` + * // custom cow and face + * cowsay.say({ + * text: 'Hello world!', + * e: '^^', // eyes + * T: 'U ', // tongue + * f: 'USA' // name of the cow from `cows` folder + * }) + * + * // using a random cow + * cowsay.say({ + * text: 'Hello world!', + * e: 'xx', // eyes + * r: true, // random mode - use a random cow. + * }) + * + * // using a mode + * cowsay.say({ + * text: 'Hello world!', + * y: true, // using y mode - youthful mode + * }) + * ``` + */ +export function say(options: IOptions): string; + +/** + * @param options + * ## Face : + * Either choose a mode (set the value as true) **_or_** + * set your own defined eyes and tongue to `e` and `T`. + * - ### `e` : eyes + * - ### `T` : tongue + * + * ## Cow : + * Either specify a cow name (e.g. "fox") **_or_** + * set the value of `r` to true which selects a random cow. + * - ### `r` : random selection + * - ### `f` : cow name - from `cows` folder + * + * ## Modes : + * Modes are just ready-to-use faces, here's their list: + * - #### `b` : borg + * - #### `d` : dead + * - #### `g` : greedy + * - #### `p` : paranoia + * - #### `s` : stoned + * - #### `t` : tired + * - #### `w` : youthful + * - #### `y` : wired + * + * @example + * ``` + * // custom cow and face + * cowsay.think({ + * text: 'Hello world!', + * e: '^^', // eyes + * T: 'U ', // tongue + * f: 'USA' // name of the cow from `cows` folder + * }) + * + * // using a random cow + * cowsay.think({ + * text: 'Hello world!', + * e: 'xx', // eyes + * r: true, // random mode - use a random cow. + * }) + * + * // using a mode + * cowsay.think({ + * text: 'Hello world!', + * y: true, // using y mode - youthful mode + * }) + * ``` + */ +export function think(options: IOptions): string; diff --git a/index.js b/index.js index a4667c1..4162e0f 100644 --- a/index.js +++ b/index.js @@ -2,14 +2,133 @@ var balloon = require("./lib/balloon"); var cows = require("./lib/cows"); var faces = require("./lib/faces"); +/** + * @param options + * ## Face : + * Either choose a mode (set the value as true) **_or_** + * set your own defined eyes and tongue to `e` and `T`. + * - ### `e` : eyes + * - ### `T` : tongue + * + * ## Cow : + * Either specify a cow name (e.g. "fox") **_or_** + * set the value of `r` to true which selects a random cow. + * - ### `r` : random selection + * - ### `f` : cow name - from `cows` folder + * + * ## Modes : + * Modes are just ready-to-use faces, here's their list: + * - #### `b` : borg + * - #### `d` : dead + * - #### `g` : greedy + * - #### `p` : paranoia + * - #### `s` : stoned + * - #### `t` : tired + * - #### `w` : wired + * - #### `y` : youthful + * + * @example + * ``` + * // custom cow and face + * cowsay.say({ + * text: 'Hello world!', + * e: '^^', // eyes + * T: 'U ', // tongue + * f: 'USA' // name of the cow from `cows` folder + * }) + * + * // using a random cow + * cowsay.say({ + * text: 'Hello world!', + * e: 'xx', // eyes + * r: true, // random mode - use a random cow. + * }) + * + * // using a mode + * cowsay.say({ + * text: 'Hello world!', + * y: true, // using y mode - youthful mode + * }) + * ``` + * + * @returns {string} compiled cow + */ exports.say = function (options) { return doIt(options, true); }; +/** + * @param options + * ## Face : + * Either choose a mode (set the value as true) **_or_** + * set your own defined eyes and tongue to `e` and `T`. + * - ### `e` : eyes + * - ### `T` : tongue + * + * ## Cow : + * Either specify a cow name (e.g. "fox") **_or_** + * set the value of `r` to true which selects a random cow. + * - ### `r` : random selection + * - ### `f` : cow name - from `cows` folder + * + * ## Modes : + * Modes are just ready-to-use faces, here's their list: + * - #### `b` : borg + * - #### `d` : dead + * - #### `g` : greedy + * - #### `p` : paranoia + * - #### `s` : stoned + * - #### `t` : tired + * - #### `w` : wired + * - #### `y` : youthful + * + * @example + * ``` + * // custom cow and face + * cowsay.think({ + * text: 'Hello world!', + * e: '^^', // eyes + * T: 'U ', // tongue + * f: 'USA' // name of the cow from `cows` folder + * }) + * + * // using a random cow + * cowsay.think({ + * text: 'Hello world!', + * e: 'xx', // eyes + * r: true, // random mode - use a random cow. + * }) + * + * // using a mode + * cowsay.think({ + * text: 'Hello world!', + * y: true, // using y mode - youthful mode + * }) + * ``` + * + * @returns {string} compiled cow + */ exports.think = function (options) { return doIt(options, false); }; +/** + * @example + * ``` + * function get_cows(error, cow_names) { + * if (error) { + * console.log(error); + * } + * else if (cow_names) { + * console.log(`Number of cows available: ${cow_names.length}`); + * } + * } + * + * cowsay.list(get_cows); + * ``` + * @param callback + * @returns {Promise} promise + */ exports.list = cows.list; function doIt (options, sayAloud) { diff --git a/package.json b/package.json index dd9997c..4f55a44 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ }, "license": "MIT", "main": "./index", + "types": "./index.d.ts", "module": "./build/cowsay.es.js", "browser": "./build/cowsay.umd.js", "bin": {