Skip to content

Commit

Permalink
Working on readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Hypercubed
Hypercubed committed Sep 7, 2013
1 parent 86e5d76 commit 9bc28f8
Showing 1 changed file with 49 additions and 56 deletions.
105 changes: 49 additions & 56 deletions Readme.md
View file
@@ -1,58 +1,62 @@
autocmdr
=============

This is a work in progress, experiment, proof of concept, and/or waste of time.
autocmdr is a both a command line interface (CLI) for running tasks and a set of components for building CLIs. autocmdr is designed to work with generator-commander to enable easily building of great CLI apps.

# Description

autocmdr is a command runner, command builder, and CLI application builder. autocmdr itself was partially built using autocmdr. Also see the obligatory todo app here [todo-md](https://github.com/Hypercubed/todo-md) (Works with GFM task lists!!).
autocmdr itself was partially built using autocmdr/generator-commader. Please also see the obligatory todo app here [todo-md](https://github.com/Hypercubed/todo-md) (Works with GFM task lists!!).

Warning... The usage is changing rapidly. I'm working towards a [0.1.0](https://github.com/Hypercubed/autocmdr/issues?milestone=1) release soon. Feedback is welcome.

[![Gittip donate button](http://badgr.co/gittip/hypercubed.png)](https://www.gittip.com/hypercubed/ "Donate weekly to this project using Gittip")
[![Paypal donate button](http://badgr.co/paypal/donate.png?bg=%23feb13d)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=X7KYR6T9U2NHC "One time donation to this project using Paypal")

# Introduction

The diverse ecosystem of modules available for node.js through npm make it a great tool the rapid development of a variety of tools including useful command line interfaces. [Commander.js](https://github.com/visionmedia/commander.js) from [visionmedia](https://github.com/visionmedia) is an excellent node.js command line parser that, using a natural, clean and highly readable syntax, allows for easy development of versatile self-documenting command line interfaces (CLIs). However, a command line parser is just the beginning. Many CLIs will inevitably need to include additional modules for debug logging, configuration management, and other CLI type actions. autocmdr is a command line tool that implements these modules, so you don't have too. In fact in what I am calling local mode all you need to do is add command modules to your local directory and autocmdr will load them automatically along with a reasonable set of additional support modules. Furthermore, in global mode autocmdr provides tools for easily building and managing these commands. This includes converting a detached set of command modules into a semi-independent CLI application that uses autocmdr (along with all it's support modules) as a library.
The diverse ecosystem of modules available for node.js through npm make it a great tool the rapid development of a variety of tools including useful command line interfaces. [Commander.js](https://github.com/visionmedia/commander.js) from [visionmedia](https://github.com/visionmedia) is an excellent node.js command line parser that, using a natural, clean and highly readable syntax, allows for easy development of versatile self-documenting command line interfaces (CLIs). However, a command line parser is just the beginning. Many CLIs will inevitably need to include additional components for debug logging, configuration management, and other CLI type actions. autocmdr is a command line tool that implements these modules, so you don't have too. In fact in what I am using the autocmdr executable all you need to do is add command modules to your local directory and autocmdr will load them automatically along with a reasonable set of additional support components. Using autocmdr along with yoeman and generator-commander provides tools for easily building command components and full CLI applications. This includes converting a detached set of command components into a semi-independent CLI application that uses autocmdr (along with all it's support modules) as a library.

## Philosophy ad Workflow

Building excellent command tools using excellent tools.

## Philosophy
commander.js is an node.js command line parser library.

autocmdr is a CLI application builder. autocmdr itself is CLI that includes a reasonable set of support modules that enhance its interface. It stands to reason that CLIs built using autocmdr would benefit from using these same modules.
autocmdr is a set of components that add interfaces and support to commander.js based applications.

Yo is a scaffolding tool built by google.

commander-generator is a commander.js application generator for Yo.

Yo, together with commander generator, makes it easy to scaffold complete command line tools that uses commander.js command line parser and autocmdr components to enable great command line interfaces.

# Usage

## Summary

Essentially autocmdr works in three modes. Local detached mode, global builder mode (accessed using the `-g` switch on the command line), and library mode. In local mode autocmdr (executing `autocmdr` without the `-g` flag) will load any commands located in the current working directory's (cwd's) `cmds/` folder. By convention each file in the `cmds/` directory corresponds to one commander.js command, although this is not necessary. In this mode it is not necessary to install autocmdr in the current working directory, you are using the global autocmdr executable with the local `cmds/` commands.
Essentially autocmdr, like most node.js modules, works in two modes; executable (command line) mode and library (require) mode. In executable mode autocmdr will load any commands located in the current working directory's (cwd's) `cmds/` folder. By convention each file in the `cmds/` directory corresponds to one commander.js command, although this is not necessary. In this mode it is not necessary to install autocmdr in the current working directory, you are using the global autocmdr executable with the local `cmds/` commands.

In global builder mode (`autocmdr -g`) autocmdr is loaded with commands that enable management of the cwd's command files and building of autocmdr/commader.js CLI apps. You are still working in the cwd, but using the global commands to manage the local commands. See below for more details and examples.
In library mode a local commander.js based CLI executable has access to autocmdr components extending its interface.

In library mode a local commander.js based CLI executable is created that has access to autocmdr plug-ins (see below).
##
## Using autocmdr as a task runner (Local detached mode)

## Install autocmdr globally
Install autocmdr globally

npm install -g Hypercubed/autocmdr

## Using autocmdr as a task runner (Local detached mode)

When running in local mode (not using the `-g` flag) all commands located in the `cmds/` folder of the current working directory are automatically loaded. These commands can be be run by invoking `autocmdr commandname`. `autocmdr --help` will list help on these local commands. By using the globally installed `autocmdr` executable the rest of your project remains untouched so you can add commands to augment existing projects.
When running in executable mode all commands located in the `cmds/` folder of the current working directory are automatically loaded. These commands can be be run by invoking `autocmdr commandname`. `autocmdr --help` will list help on these local commands. By using the globally installed `autocmdr` executable the rest of your project remains untouched so you can add commands to augment existing projects.

## Using autocmdr as a command builder (Global builder mode)

In global mode (`-g`) you can add and edit commands to the current working directory's `cmds/` folder. Referring to the example below notice that `autocmdr -g add mycmd` call is in global mode to add the `mycmd` to the cwd. The second `autocmdr mycmd` call executes the `mycmd` command. If you change to another directory these commands are no longer available.
Install yo and generator-commander

> cd example
> autocmdr -g --help
npm install -g yo generator-commander

using yo and generator-commander you can add commands to the current working directory's `cmds/` folder. Referring to the example below `yo commander:command mycmd` will add the `mycmd` command to the cwd's cmd/ directory. The `autocmdr mycmd` call executes the `mycmd` command. If you change to another directory these commands are no longer available.

$ mkdir example && cd example
$ autocmdr --help

Usage: autocmdr [options] [command]

Commands:

add [options] [name] Create a command file.
edit [options] <name> Edit command file.
init [options] [name] Create a new CLI application.
rm [options] <cmdfile> Delete a command.
config [key] [value] Get and set options
completion Print command completion script

Expand All @@ -61,12 +65,11 @@ In global mode (`-g`) you can add and edit commands to the current working direc
-h, --help output usage information
-d, --debug enable debugger
-V, --version output the version number
-g, --global use global autocmdr tasks

Bug reports, suggestions, updates:
https://github.com/Hypercubed/autocmdr/issues

> autocmdr -g add mycmd
$ yo commander:command mycmd

prompt: name: (mycmd)
prompt: description: ( )
Expand All @@ -90,7 +93,6 @@ In global mode (`-g`) you can add and edit commands to the current working direc
-h, --help output usage information
-d, --debug enable debugger
-V, --version output the version number
-g, --global use global autocmdr tasks

Bug reports, suggestions, updates:
https://github.com/Hypercubed/autocmdr/issues
Expand All @@ -100,15 +102,14 @@ In global mode (`-g`) you can add and edit commands to the current working direc
> autocmdr mycmd
> error: 'mycmd' is not a known command. See 'autocmdr --help'.

## Using autocmdr as a app builder (Library mode)
## Using generator-commander

If a set of commands in a folder are useful globally you can convert a set of tasks to an semi-independent commander.js command line application.
If a set of commands in a folder are useful globally you can convert a set of tasks to an semi-independent commander.js command line application. Notice after running `yo commander` the previously created command `mycmd` is available within the newly created `example` application.

1. Create an independent commander.js based app with autocmdr default plug-ins.


> cd example
> autocmdr -g init
> yo commander
info: Initializing example
autocmdr: name: (example)
Expand Down Expand Up @@ -155,24 +156,17 @@ If a set of commands in a folder are useful globally you can convert a set of ta
-d, --debug enable debugger
-V, --version output the version number

The new executable you just created, by default, will have access to the autocmdr plugins as well as the commands in the `cmds/` folder. Edit `bin/example` to change these defaults.

## autocmdr options

You can set options with this the `autocmdr config` command. `autocmdr config` will list all config variables. `autocmdr config name` will get a value, `autocmdr config name value` will set a value. Currently the following config options are available:

`autocmdr -g config author` will get/set the default cli author name
`autocmdr -g config editor` will get/set the default editor
The new executable you just created, when you include the autocmdr components, will have access to the autocmdr plugins as well as the commands in the `cmds/` folder. Edit `bin/example` to change what components are loaded.

# Commander.js components

Commands and plug-ins are node.js modules that export a single initialization function. This function is called with a commander.js program and an optional options object. Commands and plug-ins have a simple syntax that doesn't deviate far from the syntax established by commander.js itself. See autocmdr's [commands](https://github.com/Hypercubed/autocmdr/tree/master/cmds) and [plug-ins](https://github.com/Hypercubed/autocmdr/tree/master/lib) for examples.
autocmdr components are node.js modules that export a single initialization function. This function is called with a commander.js program and an optional options object. Components have a simple syntax that doesn't deviate far from the syntax established by commander.js itself. See autocmdr's [example commands](https://github.com/Hypercubed/autocmdr/tree/master/cmds) and [lib](https://github.com/Hypercubed/autocmdr/tree/master/lib) for examples.

## Command modules
## Commands

The most basic form of a command module is shown below. Within the function the commander.js program is manipulated to add a single command as any other commander.js program (see [commander.js api documentationn](http://visionmedia.github.io/commander.js/)).
The most basic form of a command component is shown below. Within the exported function the a single command is added to the commander.js `program` as you would in any other commander.js program (see [commander.js api documentationn](http://visionmedia.github.io/commander.js/)).

module.exports = function (program) {
module.exports = function(program) {

program
.command('name')
Expand All @@ -184,25 +178,25 @@ The most basic form of a command module is shown below. Within the function the

};

## Plug-in modules
## Components

autocmdr plug-in modules have the same structure as command modules. The only difference is that they are not designed to be automatically loaded. Plugins are loaded using node's require function again exporting a single initialization function; this time accepting an options object as the second parameter. Below are the built-in autocmdr plug-ins.
autocmdr plug-in modules have the same structure as command modules. The only difference is that they are not designed to be automatically loaded. Plugins are loaded using node's require function again exporting a single initialization function; this time accepting an optional options object as the second parameter. Below are the built-in autocmdr plug-ins.

module.exports = function (program, options) {
module.exports = function(program, options) {

// Do plug-in stuff here

};

### loader

This plug-in is what loads the `cmds/` modules.
This component is what loads the `cmds/` modules.

Adding `require('autocmdr/lib/loader.js')(program)` will load all modules in the `cmds` folder just above the executable. This path can be overridden by setting the path option; for example `require('autocmdr/lib/loader.js')(program, { path: path.join(process.cwd(), 'cmds/') )` will load modules from the cwd's `/cmds` folder.

### logger

The logger plug-in uses [Winston](https://github.com/flatiron/winston) for logging.
The logger component uses [Winston](https://github.com/flatiron/winston) for logging.

Adding `require('autocmdr/lib/logger')(program)` will add `program.log` to your application. The plug-in will enable output to the terminal depending on the log level. The plug-in will also add the `-d` option to your application to enable debug logging. Then logging can be done like this:

Expand All @@ -214,7 +208,7 @@ While this component is optional other components expect to find and instant of

### config

This plug-in will load [nconf](https://github.com/flatiron/nconf) for handling of configuration. It will add program.config as an instance of nconf.
This component will load [nconf](https://github.com/flatiron/nconf) for handling of configuration. It will add program.config as an instance of nconf.

Adding `require('autocmdr/lib/config')(program)` will enable this.

Expand All @@ -241,12 +235,6 @@ Adding `require('autocmdr/lib/completion')(program)` just before `program.parse(
* Add completion helper to ~/.bashrc (or ~/.zshrc) `pkgname completion >> ~/.bashrc`
* Add completion to current shell `. <(pkgname completion)`

### prompt
`var prompt = require('autocmdr/lib/prompt')(program)`

### render
`var render = require('autocmdr/lib/render')(program)`

# Questions

Q: Doesn't flatiron do the same thing? You're even using some flatiron modules! Why not just use [flatiron](https://github.com/flatiron/flatiron) to build your cli applications.
Expand All @@ -270,10 +258,15 @@ See [todo.md](https://github.com/Hypercubed/autocmdr/blob/master/todo.md) \( man

# License

MIT
Copyright (c) 2013 Jayson Harshbarger

[MIT License](http://en.wikipedia.org/wiki/MIT_License)

# Acknowledgments

autocmdr itself was (partially) built using [autocmdr](https://github.com/Hypercubed/autocmdr).

autocmdr is build on top of [commander.js](https://github.com/visionmedia/commander.js) and inspired by other task managers \( [grunt](https://github.com/gruntjs/grunt), [automaton](https://github.com/IndigoUnited/automaton) \) and command line tools \( [docpad](https://github.com/bevry/docpad), [git](https://github.com/git/git) \) and (of course) [flatiron](https://github.com/flatiron/flatiron).

[![Gittip donate button](http://badgr.co/gittip/hypercubed.png)](https://www.gittip.com/hypercubed/ "Donate weekly to this project using Gittip")
[![Paypal donate button](http://badgr.co/paypal/donate.png?bg=%23feb13d)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=X7KYR6T9U2NHC "One time donation to this project using Paypal")

0 comments on commit 9bc28f8

Please sign in to comment.