Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gerard2perez/node-mce
create cli tools easy
https://github.com/gerard2perez/node-mce
bulider cli command-line mce
Last synced: 9 days ago
JSON representation
create cli tools easy
- Host: GitHub
- URL: https://github.com/gerard2perez/node-mce
- Owner: gerard2perez
- License: mit
- Created: 2018-05-29T21:40:51.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2023-03-04T02:47:08.000Z (over 1 year ago)
- Last Synced: 2024-10-08T13:09:12.578Z (29 days ago)
- Topics: bulider, cli, command-line, mce
- Language: TypeScript
- Homepage:
- Size: 1.29 MB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @gerard2p/mce
 |  | [](https://github.com/ellerbrock/typescript-badges/)
-|-|-
[](https://github.com/gerard2p/node-mce/actions) | [](https://david-dm.org/gerard2p/node-mce) | [](https://david-dm.org/gerard2p/node-mce?type=dev)
[](https://codeclimate.com/github/gerard2p/node-mce?style=flat-square) | [](https://codeclimate.com/github/gerard2p/node-mce/coverage) | [](https://codeclimate.com/github/gerard2p/node-mce)
 | [](https://app.fossa.io/projects/git%2Bgithub.com%2Fgerard2p%2Fnode-mce?ref=badge_shield) |
## Installation
```sh
npm i -g @gerard2p/mce
```
## Usage
```sh
mce new [options]
Creates a new MCE project.
-f, --force Overrides target directory
-n, --npm Install npm dependencies
-s, --style Define the style of command you will use. If you need
more than one command use git.
Values: git | *single
mce add <command>
Adds a new command to the git project.
```
This will create project that is ready to work with mce. The project scaffolding look like this:
### Project Structure
```
project_name::
|--.vscode
| |--launch.json
| |--settings.json
| |--task.json
|
|--src
| |--index.ts [single-style]
| |--cli.ts
| |--commands [git-style]
| |--removeme.ts
|
|--.gitignore
|--package.json
|--tsconfig.json
|--project_name
```
### Configuring command
- **Single-Style** only uses a **index.ts** in the src folder.
- **Git-Style uses** [command].ts files inside the commands folder.
> In any of both cases a command is defined in the same way.
```typescript
import { numeric, floating, range, text, list, collect, bool, verbose, enumeration, Parsed} from '@gerard2p/mce';
import { ok, error, warn, info, ask, input } from '@gerard2p/mce/verbose';
import { created, updated, makeDir, cp, printRelativePath, targetPath, cliPath } from '@gerard2p/mce/utils';
import { spin } from '@gerard2p/mce/spinner';
enum Styles {
git = 'git',
single = 'single'
}
export let description = 'A description for your command';
export let args = '<arg1> [varidac...]';
export let options = {
enumeration: enumeration('-e <enum>', 'Define the style of command you will use', Styles,Styles.single),
number: numeric('-n <n>', 'A number'),
floating: floating('-f <n>', 'A float number'),
range: range('-r <a>..<b>', 'A Range of two numbers'),
text: text('-t <n>', 'A string value'),
list: list('-l <n>', 'comma separed values'),
collect: collect('-c <n>', 'A repetable value'),
bool: bool('-b', 'A boolean value'),
verbose: verbose('Increase system verbosity'),
};
export async function action(arg1:string, varidac:string[], opt:Parsed<typeof options>) {
// Your Code
}
```
## Option Parsing
You must export a options variable with the options that you want to use.
As you can see you can defined a lot of types for your options most of the options cant take a '' as first parameter and mce will generate the tags for you.
The name in the you use to define the property is used as main tag, if you pass '' as the first argument it will fill with a automatic tag_desc and no sort tag will be generated.
On the other hand if you pass a string like `-e --env <env>` mce will use those values as the short tag, tag and tag value.
option|short|tag|tag_desc|desc
-|-|-|-|-
`enumeration:enumeration('', 'description', ['a','b'])`| | --enumeration|`<e>`|description Values a \| b
`enumeration:enumeration('-l', 'description', ['a','b'])`|-l|--enumeration|`<e>`|description Values a \| b
`enumeration:enumeration('-l --list', 'description', ['a','b'])`|-l|--list|`<e>`|description Values a \| b
`enumeration:enumeration('-l --list <l>', 'description', ['a','b'])`|-l|--list|`<l>`|description Values a \| b
No mather the case the actual property that is created in the *opt* is always *enumeration* for this case.
### Coercion
As you can see mce come with some handy functios to coerce and validate the user input.
```typescript
import { numeric, floating, range, text, list, collect, bool, verbose, enumeration } from '@gerard2p/mce';
```
### Validation
If you need to validate the information of any of your arguments you can pass a RegExp as the third arguments of the option_functions
```
import { text } from '@gerard2p/mce';
export let options = {
size: text('-s --size <size>', 'Pizza size', /^(large|medium|small)$/);
}
```
### Defaults
The last argument you pass will always be the default value.
```
import { text } from '@gerard2p/mce';
export let options = {
size: text('-s --size <size>', 'Pizza size', /^(large|medium|small)$/, 'medium');
}
```
### Version option
By default mce will trace the --version tag and will respond with the version in your package.json.
### Verbose option
By default mce will trace the ```-v --verbose``` tag and will respond wwith the version in your package.json.
> Only if you define a verbose obtion you will be passed with the actual verbose value but in most of the cases is no needed.
## Arguments
You need to export a ```args:string``` property with you arguments definition
### Required args
```<arg>``` is the convention to make your arg required is no arg detected mce will throw and error.
### Optional args
```[arg]``` is the convention to make your arg optional.
### Varidac args
```[arg ...]``` is the convention to make the rest of the args be presented as varidad ```string[]```
### Coecion
Argument can be coerced by default they are treated as string but if you use:
- `<arg:`**number**`>` will be coerce to number.
- `<arg:`**boolean**`>` will be coerce to boolean.
## Help Generation
By default mce will trace the ```-h --help``` options and will automatically render help
# Add a new command to project
Just run:
```sh
mce add <command>
```
Adds a new command to a git-style project.
# Useful Utilities
MCE con with a handy bunch of utilities to help you build your commands easily.
## Input
```ts
import { confirm, override, question} from '@gerard2p/mce/input'
```
### question(display:string)=>Promise\<string\>
This is the basic function that allows you to wait for user input. Is compatible with the spinner, so, whenever you call this functions the spinner will stop and display the new message.
When the user enters the input the spinner will continue working as expected.
```
let answer = await question('Are you ready?')
```
Will display
```
Are you ready? _
```
And will wait for user input.
if inside a spinner:
```
await spin('demo', async ()=>{
let answer = await question('Are you ready?')
});
```
```
demo - Are you ready? _
```
### confirm (display:string)=>Promise\<boolean\>
```ts
if(await confirm('Are you ready')) {
// code
}
// Are you ready? [y/n]: _
```
```ts
await spin('demo', async ()=>{
if(await confirm('Are you ready')) {
// code
}
});
// demo - Are you ready? [y/n]: _
```
### override (display:string, testdir:string, state:boolean)=>Promise\<boolean\>
Returns true if safe to write the directory and content.
Removes the directory if is needed.
```ts
if(await override('Path already exists do you want to continue')) {
// code
}
// Path already exists do you want to continue? [y/n]: _
```
```ts
await spin('demo', async ()=>{
if(await override('Path already exists do you want to continue')) {
// code
}
});
// demo - Path already exists do you want to continue? [y/n]: _
```
## tree-maker
```ts
import { pathResolver } from '@gerard2p/mce/tree-maker/fs'
```
This function allows you to intersect the path that resolves to your templates and the target path.
### pathResolver(_template:(path:string)=>string, _target?:(path:string)=>string):void
_template will resolve to a template folder located next to your package.json
```ts
import { cpy, cmp, dir, root, wrt } from '@gerard2p/mce/tree-maker'
import { c, z, d, r, w } from '@gerard2p/mce/tree-maker'
```
This utility allows to create a directory structure in a really easy and chainable way.
```ts
root('proyect')
.with(
cpy('LICENSE')
)
.dir('subfolder',
cmp('README.md', {...values}, 'DOC.md'),
cmp('README.md', {...values}),
wrt('.gitignore','node_modules\ttemplates')
)
```
will produde:
```sh
proyect
|- LICENSE
|-subfolder
|-DOC.md
|-README.md
|-.gitignore
```
### root(dir:string)=>TreeMaker
Creates the initial directory.
### cpy(source:string, target:string)=>chainable
Copies a file from your template directory to the destination folder.
Target can be undefined and will use the same name as your source.
### cmp(source:string, data:any, target:string)=>chainable
Renders a file from your template directory to the destination folder.
Target can be undefined and will use the same name as your source.
### wrt(target:string, content:string)=>chainable
Create a file at target location.
### dir(folder:string, ...operations:chainable[])=>chainable
Create a new directory and allows to chain new operations
# Final Notes
The executable file that is generated only call your ./cli file.
When in git-style cli.ts will look like:
```typescript
import { MCE } from "@gerard2p/mce";
MCE(__dirname).subcommand(process.argv);
```
And in single-style:
```typescript
import { MCE } from "@gerard2p/mce";
MCE(__dirname).command(process.argv);
```
> During local development I use ts-node to call direct the .ts files