github.com/wallyqs/gcli@v0.2.3-0.20151010121825-a114d5d1758d/README.md (about)

     1  gcli
     2  ====
     3  
     4  [![GitHub release](http://img.shields.io/github/release/tcnksm/gcli.svg?style=flat-square)][release]
     5  [![Wercker](http://img.shields.io/wercker/ci/5587a34baf7de9c51b02e04b.svg?style=flat-square)][wercker]
     6  [![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)][license]
     7  [![Go Documentation](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)][godocs]
     8  
     9  [release]: https://github.com/tcnksm/gcli/releases
    10  [wercker]: https://app.wercker.com/#applications/5587a34baf7de9c51b02e04b
    11  [license]: https://github.com/tcnksm/gcli/blob/master/LICENSE
    12  [godocs]: http://godoc.org/github.com/tcnksm/gcli
    13  
    14  `gcli` generates the codes and its directory structure you need to start building CLI tool by Golang right out of the box. You can use your favorite [framework](#support-frameworks). 
    15  
    16  ## Usage
    17  
    18  To start new command line tool, run the following command. It generates new cli skeleton project. At least, you must provide executable name. You can `go build`  && `go test` it from beginning.
    19  
    20  ```bash
    21  $ gcli new [options] NAME
    22  ```
    23  
    24  To see available frameworks,
    25  
    26  ```bash
    27  $ gcli list
    28  ```
    29  
    30  See more usage,
    31  
    32  ```bash
    33  $ gcli help
    34  ```
    35  
    36  ### Generate CLI project from design file
    37  
    38  You can generate CLI project from design template file (`.toml`). You can define command name, its description, commands there. 
    39  
    40  First, you can create default `toml` file via `design` command,
    41  
    42  ```bash
    43  $ gcli design <NAME>
    44  ```
    45  
    46  Then, edit design file by your favorite `$EDITOR`. You can see sample template file [`sample.toml`](/sample.toml),
    47  
    48  ```bash
    49  $ $EDITOR <NAME>-design.toml
    50  ```
    51  
    52  You can validate design by `validate` command to check it has required fields, 
    53  
    54  ```bash
    55  $ gcli validate <NAME>-design.toml
    56  ```
    57  
    58  To generate CLI project, use `apply` command, 
    59  
    60  ```bash
    61  $ gcli apply <NAME>-desigon.toml
    62  ```
    63  
    64  
    65  ## Support frameworks
    66  
    67  `gcli` can generate two types of CLI, 
    68  
    69  - [Flag pattern](#flag-pattern)
    70  - [Command pattern](#command-pattern)
    71  
    72  ### Flag pattern
    73  
    74  Flag pattern is the pattern which executable has only flag options like below (e.g., `grep`),
    75  
    76  ```bash
    77  $ grep —i -C 4 "some string" /tmp   
    78      │     │              │           
    79      │     │               `--------- Arguments 
    80      │     │                          
    81      │      `------------------------ Option flags   
    82      │                                
    83       `------------------------------ Executable  
    84  ```
    85  
    86  To generate above CLI application with [flag](https://golang.org/pkg/flag/) fraemwork,
    87   
    88  ```bash
    89  $ cd $GOPATH/src/github.com/YOUR_NAME
    90  $ gcli new -F flag -flag=i:Bool -flag=C:Int grep
    91    Created grep/main.go
    92    Created grep/CHANGELOG.md
    93    Created grep/cli_test.go
    94    Created grep/README.md
    95    Created grep/version.go
    96    Created grep/cli.go
    97  ====> Successfully generated grep
    98  ```
    99  
   100  `gcli` supports the following packages for the flag pattern:
   101  
   102  - [flag](https://golang.org/pkg/flag/)
   103  
   104  ### Command pattern
   105  
   106  Command pattern is the pattern which executable has command for change its behavior. For example, `todo` CLI application which has `add` (Add new task), `list` (List all tasks) and `delete`(Delete a task) command. 
   107  
   108  ```bash
   109  $ todo add 'Buy a milk' 
   110     │    │      │           
   111     │    │       `---------- Arguments 
   112     │    │ 
   113     │     `----------------- Command 
   114     │                                  
   115      `---------------------- Executable
   116  ```
   117  
   118  To generate above CLI application with [mitchellh/cli](https://github.com/mitchellh/cli) framework,
   119  
   120  ```bash
   121  $ cd $GOPATH/src/github.com/YOUR_NAME
   122  $ gcli new -F mitchellh_cli -c add -c list -c delete todo
   123    Created todo/main.go
   124    Created todo/command/meta.go
   125    Created todo/cli.go
   126    Created todo/CHANGELOG.md
   127    Created todo/version.go
   128    Created todo/commands.go
   129    Created todo/command/add.go
   130    Created todo/command/list.go
   131    Created todo/command/delete.go
   132    Created todo/README.md
   133    Created todo/command/add_test.go
   134    Created todo/command/list_test.go
   135    Created todo/command/delete_test.go
   136  ====> Successfully generated todo
   137  ```
   138  
   139  `gcli` supports the following packages for the command pattern:
   140  
   141  - [codegangsta_cli](https://github.com/codegangsta/cli)
   142  - [mitchellh_cli](https://github.com/mitchellh/cli)
   143  - [go_cmd](https://github.com/golang/go/blob/master/src/cmd/go/main.go#L30#L51) (without 3rd party framework, same as `go` command)
   144  
   145  ## Installation
   146  
   147  To install, use `go get` and `make install`. We tag versions so feel free to checkout that tag and compile.
   148  
   149  ```bash
   150  $ go get -d github.com/tcnksm/gcli
   151  $ cd $GOPATH/src/github.com/tcnksm/gcli
   152  $ make install 
   153  ```
   154  
   155  ## Contribution
   156  
   157  1. Fork ([https://github.com/tcnksm/gcli/fork](https://github.com/tcnksm/gcli/fork))
   158  1. Create a feature branch
   159  1. Commit your changes
   160  1. Rebase your local changes against the master branch
   161  1. Run test suite with the `make test` command and confirm that it passes
   162  1. Run `gofmt -s`
   163  1. Create a new Pull Request
   164  
   165  ## Author
   166  
   167  [Taichi Nakashima](https://github.com/tcnksm)