Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/IonicaBizau/tilda
Tiny module for building comand line tools.
https://github.com/IonicaBizau/tilda
hacktoberfest
Last synced: 12 days ago
JSON representation
Tiny module for building comand line tools.
- Host: GitHub
- URL: https://github.com/IonicaBizau/tilda
- Owner: IonicaBizau
- License: mit
- Created: 2016-04-14T12:57:57.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-08-09T16:28:51.000Z (over 4 years ago)
- Last Synced: 2024-05-02T06:14:58.507Z (6 months ago)
- Topics: hacktoberfest
- Language: JavaScript
- Size: 92.8 KB
- Stars: 22
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](#)
# tilda
[![Support me on Patreon][badge_patreon]][patreon] [![Buy me a book][badge_amazon]][amazon] [![PayPal][badge_paypal_donate]][paypal-donations] [](https://github.com/IonicaBizau/ama) [](https://www.npmjs.com/package/tilda) [](https://www.npmjs.com/package/tilda) [](https://www.codementor.io/johnnyb?utm_source=github&utm_medium=button&utm_term=johnnyb&utm_campaign=github)
> Tiny module for building command line tools.
### Features
- Human readable syntax and easy to use
- Supports custom options and commands
- Auto parse the command line arguments
- Supports reading the `stdin` data
- Opens prompts in the command line if the value is required but was not provided
## :cloud: Installation
```sh
# Using npm
npm install --save tilda
# Using yarn
yarn add tilda
```
## :clipboard: Example
```js
#!/usr/bin/env node
// ./index.js -f tux 'Hello World!'
// ______________
// < Hello World! >
// --------------
// \
// \
// .--.
// |o_o |
// |:_/ |
// // \ \
// (| | )
// /'\_ _/`\
// \___)=(___/
//
// Help output
// -----------
//
// ./index.js --help
// Usage: cowsay [options]
//
// Configurable speaking cow (and a bit more)
//
// Commands:
// list List the cow templates.
//
// Options:
// -e, --eye The eye string.
// -T, --tongue The tongue string.
// -f, --cowfile The cowfile.
// -v, --version Displays version information.
// -h, --help Displays this help.
//
// Examples:
// $ cowsay 'Hello there!'
// $ cowsay -e '*-' 'Heyyy!
// $ cowsay -T '++' 'I have a nice tongue!
//
// Well, this is just a tiny example how to use Tilda.
// Documentation can be found at https://github.com/IonicaBizau/tilda.
"use strict";
const Tilda = require("tilda")
, cowsay = require("cowsay")
;
let p = new Tilda({
name: "cowsay"
, version: "1.0.0"
, description: "Configurable speaking cow (and a bit more)"
, documentation: "https://github.com/IonicaBizau/tilda"
, examples: [
"cowsay 'Hello there!'"
, "cowsay -e '*-' 'Heyyy!"
, "cowsay -T '++' 'I have a nice tongue!"
]
, notes: "Well, this is just a tiny example how to use Tilda."
, args: [{
name: "text"
, type: String
, desc: "The text to display."
, stdin: true
}]
}, {
stdin: true
}).option([
{
opts: ["eye", "e"]
, desc: "The eye string."
, name: "str"
}
, {
opts: ["tongue", "T"]
, desc: "The tongue string."
, name: "str"
}
, {
opts: ["cowfile", "f"]
, desc: "The cowfile."
, name: "cow"
, default: "default"
}
]).action([
{
name: "list"
, desc: "List the cow templates."
, options: [
{
opts: ["list", "l"],
desc: "Display as list",
}
]
}
]).on("list", action => {
cowsay.list((err, list) => {
if (err) { return this.exit(err); }
let str = list.join(action.options.list.is_provided ? "\n" : ", ")
console.log(str);
});
}).main(action => {
console.log(cowsay.say({
text: action.stdinData || action.args.text || " "
, e: action.options.eye.value
, T: action.options.tongue.value
, f: action.options.cowfile.value
}));
});
```
## :question: Get Help
There are few ways to get help:
1. Please [post questions on Stack Overflow](https://stackoverflow.com/questions/ask). You can open issues with questions, as long you add a link to your Stack Overflow question.
2. For bug reports and feature requests, open issues. :bug:
3. For direct and quick help, you can [use Codementor](https://www.codementor.io/johnnyb). :rocket:
## :memo: Documentation
### `TildaOption(input)`
The `TildaOption` class used for creating option objects.
#### Params
- **Object** `input`: An object containing the following fields:
- `name` (String): The option name (optional).
- `description` (String): The option description.
- `opts` (Array): An array of aliases (e.g. `["age", "a"]`).
- `default` (Anything): The default value.
- `handler` (Function): The option handler which will be called when the
option is found in the arguments. The first parameter is the option
object and the second argument is the action where the option belongs to.
- `required` (Boolean): A flag representing if the option is mandatory or not (default: `false`).
- `type` (Class|String): The type class (e.g. `String`) or its stringified representation (e.g. `"string"`).
- `prompt` (Boolean|Object): If `false`, it will disable the prompt even if the option is required. If it's an object, it will passed as options to `prompt-sync`.
#### Return
- **TildaOption** The `TildaOption` instance.
- `description` (String): The option description.
- `opts` (Array): An array of aliases (e.g. `["age", "a"]`).
- `aliases` (Array): An array of strings containing the computed aliases,
the single letter ones being the first (e.g. `["-n", "--name"]`).
- `value` (null|String|DefaultValue): The option value which was found
after processing the arguments.
- `def` (Anything): The provided default value.
- `is_provided` (Boolean): A flag if the option was or not been provided.
- `handler` (Function): The handler function.
- `required` (Boolean): The required value.
- `type` (Class|String): The option value type.
- `prompt` (Boolean|Object): The prompt settings..
### `TildaAction(info, options)`
The `TildaAction` class used for creating action objects.
This is extended `EventEmitter`.
#### Params
- **String|Object** `info`: The path to a containing the needed information or an object containing:
- `description|desc` (String): The action description.
- `name` (String): The action name.
- `bin` (Object): A `package.json`-like `bin` field (optional).
- `args` (Array): An array of strings/objects representing the action argument names (default: `[]`).
- `examples` (Array): An array of strings containing examples how to use the action.
- `notes` (String): Additional notes to display in the help command.
- `documentation` (String): Action-related documentation.
- **Object** `options`: An object containing the following fields (if provided, they have priority over the `info` object):
- `args` (Array): An array of strings/objects representing the action argument names (default: `[]`).
- `examples` (Array): An array of strings containing examples how to use the action.
- `notes` (String): Additional notes to display in the help command.
- `documentation` (String): Action-related documentation.
#### Return
- **TildaAction** The `TildaAction` instance containing:
- `options` (Object): The action options.
- `description` (String): The action description.
- `name` (String): The action name.
- `uniqueOpts` (Array): An array of unique options in order.
- `_args` (Array): The action arguments.
- `argNames` (Array): The action argument names.
- `args` (Object): The arguments' values.
- `examples` (Array): An array of strings containing examples how to use the action.
- `notes` (String): Additional notes to display in the help command.
- `documentation` (String): Action-related documentation.
- `stdinData` (String): The stdin data.
### `readInfo(info)`
Converts the info input into json output.
#### Params
- **String|Object** `info`: The info object or path to a json file.
#### Return
- **Object** The info object.
### `option(input)`
Adds one or more options to the action object.
#### Params
- **Array|Object** `input`: An array of option objects or an object passed to the `TildaOption` class.
### `Tilda(info, options)`
Creates the parser instance.
#### Params
- **Object** `info`: The `info` object passed to `TildaAction`.
- **Object** `options`: The `options` passed to `TildaAction`, extended with:
- `defaultOptions` (Array): Default and global options (default: help and version options).
- `argv` (Array): A cutom array of arguments to parse (default: process arguments).
- `stdin` (Boolean): Whether to listen for stdin data or not (default: `false`).
#### Return
- **Tilda** The `Tilda` instance containing:
- `actions` (Object): An object containing the action objects.
- `version` (String): The version (used in help and version outputs).
- `argv` (Array): Array of arguments to parse.
- `_globalOptions` (Array): The global options, appended to all the actions.
- `actionNames` (Array): Action names in order.
### `globalOption(input)`
Adds a global option for all the actions.
#### Params
- **Array|Object** `input`: The option object.
### `action(input, opts)`
Adds a new action.
#### Params
- **Object** `input`: The info object passed to `TildaAction`.
- **Array** `opts`: The action options.
### `exit(msg, code)`
Exits the process.
#### Params
- **String|Object** `msg`: The stringified message or an object containing the error code.
- **Number** `code`: The exit code (default: `0`).
### `parse()`
Parses the arguments. This is called internally.
This emits the action names as events.
### `displayVersion()`
Returns the version information.
#### Return
- **String** The version information.
### `displayHelp(action)`
Displays the help output.
#### Params
- **TildaAction** `action`: The action you want to display help for.
### `main(cb)`
Append a handler when the main action is used.
#### Params
- **Function** `cb`: The callback function.
### `convertTo(classConst, input, opts)`
Converts an input into a class instance.
#### Params
- **Class** `classConst`: The class to convert to.
- **Object|Array** `input`: The object info.
- **Object** `opts`: The options object (optional).
#### Return
- **TildaAction|TildaOption** The input converted into a class instance.
## :yum: How to contribute
Have an idea? Found a bug? See [how to contribute][contributing].
## :sparkling_heart: Support my projects
I open-source almost everything I can, and I try to reply to everyone needing help using these projects. Obviously,
this takes time. You can integrate and use these projects in your applications *for free*! You can even change the source code and redistribute (even resell it).
However, if you get some profit from this or just want to encourage me to continue creating stuff, there are few ways you can do it:
- Starring and sharing the projects you like :rocket:
- [![Buy me a book][badge_amazon]][amazon]—I love books! I will remember you after years if you buy me one. :grin: :book:
- [![PayPal][badge_paypal]][paypal-donations]—You can make one-time donations via PayPal. I'll probably buy a ~~coffee~~ tea. :tea:
- [![Support me on Patreon][badge_patreon]][patreon]—Set up a recurring monthly donation and you will get interesting news about what I'm doing (things that I don't share with everyone).
- **Bitcoin**—You can send me bitcoins at this address (or scanning the code below): `1P9BRsmazNQcuyTxEqveUsnf5CERdq35V6`
Thanks! :heart:
## :dizzy: Where is this library used?
If you are using this library in one of your projects, add it in this list. :sparkles:
- `bloggify`
- `ajs`
- `cli-gh-cal`
- `cli-confeti`
- `bloggify-cli`
- `git-stats`
- `statique`
- `web-term`
- `blah`
- `babel-it`
- `face-detectify`
- `packy`
- `tilda-cowsay`
- `nuvi`
- `mastodon-create-account`
- `mastodon-get-token`
- `mastodon-register-app`
- `vivah`
- `obj2env-cli`
- `gitlist`
- `google-font-downloader`
- `streetpianos-scraper`
- `tithe`
- `tilda-init`
- `bloggify-tools`
- `striking-clock`
- `3abn`
- `cli-confetti`
- `cli-emoji`
- `cli-sunset`
- `exec-limiter-cli`
- `flight-tracker`
- `git-change-author`
- `git-stats-html`
- `git-unsaved`
- `img-ssim-cli`
- `machine-ip`
- `mdy`
- `ship-release`
- `set-creation-date-cli`
- `scrape-it-cli`
- `pull-from-source`
- `np-init-cli`
- `tester-init`
## :scroll: License
[MIT][license] © [Ionică Bizău][website]
[license]: /LICENSE
[website]: https://ionicabizau.net
[contributing]: /CONTRIBUTING.md
[docs]: /DOCUMENTATION.md
[badge_patreon]: https://ionicabizau.github.io/badges/patreon.svg
[badge_amazon]: https://ionicabizau.github.io/badges/amazon.svg
[badge_paypal]: https://ionicabizau.github.io/badges/paypal.svg
[badge_paypal_donate]: https://ionicabizau.github.io/badges/paypal_donate.svg
[patreon]: https://www.patreon.com/ionicabizau
[amazon]: http://amzn.eu/hRo9sIZ
[paypal-donations]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RVXDDLKKLQRJW