rbcli 0.1.10 → 0.2.0

data/docs-src/docs/imported/quick_reference.md

@@ -0,0 +1,150 @@
+# Quick Reference
+
+## Installation
+
+RBCli is available on rubygems.org. You can add it to your application's `Gemfile` or `gemspec`, or install it manually by running:
+
+```bash
+gem install rbcli
+```
+
+Then, `cd` to the folder you'd like to create your project under and run:
+
+```bash
+rbcli init -n mytool -d "A simple CLI tool"
+```
+
+Or, for a single-file tool without any folder/gem tructure, run `rbcli init -t mini -n <projectname>` or `rbcli init -t micro -n <projectname>`.
+
+
+## Creating a command
+
+There are three types of commands: standard, scripted, and external.
+
+* __Standard__ commands let you code the command directly in Ruby
+* __Scripted__ commands provide you with a bash script, where all of the parsed information (params, options, args, and config) is shared
+* __External__ commands let you wrap 3rd party applications directly
+
+### Standard Commands
+
+To create a new command called `foo`, run:
+
+```bash
+rbcli command -n foo
+```
+
+You will now find the command code in `application/commands/list.rb`. Edit the `action` block to write your coode.
+
+### Scripted Commands
+
+To create a new scripted command called `bar`, run:
+
+```bash
+rbcli script -n bar
+```
+
+You will then find two new files:
+
+* The command declaration under `application/commands/bar.rb`
+* The script code under `application/commands/scripts/bar.sh`
+
+Edit the script to write your code.
+
+### External Commands
+
+To create a new external command called `baz`, run:
+
+```bash
+rbcli extern -n baz
+```
+
+You will then find the command code in `application/commands/baz.rb`.
+
+Use one of the two provided modes -- direct path mode or variable path mode -- to provide the path to the external program.
+
+
+## Hooks
+
+RBCli has several hooks that run at different points in the exectution chain. They can be created via the `rbcli` command line tool:
+
+```bash
+rbcli hook --default      # Runs when no command is provided
+rbcli hook --pre          # Runs before any command
+rbcli hook --post         # Runs after any command
+rbcli hook --firstrun     # Runs the first time a user runs your application. Requires userspace config.
+rbcli hook -dpof          # Create all hooks at once
+```
+
+## Storage
+
+RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.
+
+### Local State
+
+RBCli can provide you with a unique hash that can be persisted to disk on any change to a top-level value.
+
+Enable local state in `config/storage.rb`.
+
+Then access it in your Standard Commands with `Rbcli.local_state[:yourkeyhere]`.
+
+### Remote State
+
+Similar to the Local State above, RBCli can provide you with a unique hash that can be persisted to a remote storage location.
+
+Currently only AWS DynamoDB is supported, and credentials will be required for each user.
+
+Enable remote state in `config/storage.rb`.
+
+Then access it in your Standard Commands with `Rbcli.remote_state[:yourkeyhere]`.
+
+
+## Userspace Configuration Files
+
+RBCli provides an easy mechanism to generate and read configuration files from your users. You set the default values and help text with the __defaults chain__, and leverage the __user chain__ to read them.
+
+You can set defaults either by placing a YAML file in the `userconf/` folder or by specifying individual options in `application/options.rb` (global) or `application/command/*.rb` (command-specific).
+
+Users can generate a config file, complete with help text, by running your tool with the `--generate-config` option.
+
+
+## Logging
+
+RBCli's logger is configured in `config/logging.rb`.
+
+```ruby
+log_level :info
+log_target 'stderr'
+```
+
+Then it can be accessed when writing your commands via:
+
+```ruby
+Rbcli::log.info { 'These logs can go to STDERR, STDOUT, or a file' }
+```
+
+The user will also be able to change the log level and target via their config file, if it is enabled.
+
+
+## Automatic Update Check
+
+RBCli can automatically notify users when an update is available. Two sources are currently supported: Github (including Enterprise) and RubyGems.
+
+You can configure automatic updates in `config/autoupdate.rb` in your project.
+
+
+## Development and Contributing
+
+For more information about development and contributing, please see the [Official Development Documentation][documentation_development]
+
+## License
+
+The gem is available as open source under the terms of the [GPLv3](https://github.com/akhoury6/rbcli/blob/master/CODE_OF_CONDUCT.md).
+
+## Full Documentation
+
+[You can find the Official Documentation for RBCli Here.][documentation_home]
+
+
+[documentation_home]: https://akhoury6.github.com/rbcli
+[documentation_development]: https://akhoury6.github.com/rbcli/development/contributing/
+[license_text]: https://github.com/akhoury6/rbcli/blob/master/LICENSE.txt

data/docs-src/docs/index.md

@@ -0,0 +1,38 @@
+# This is RBCli
+
+
+As technologists today, we work with the command line a lot. We script a lot. We write tools to share with each other to make our lives easier. We even write applications to make up for missing features in the 3rd party software that we buy. Unfortunately, when writing CLI tools, this process has typically been very painful. We've been working with low-level frameworks for decades; frameworks like `getopt` (1980) and `curses` (1977). They fit their purpose well; they were both computationally lightweight for the computers of the day, and they gave engineers full control and flexibility when it came to how things were built. Over the years, we've used them to settle on several design patterns that we know work well. Patterns as to what a CLI command looks like, what a config file looks like, what remote execution looks like, and even how to use locks (mutexes, semaphores, etc) to control application flow and data atomicity. Yet we're stuck writing the same low-level code anytime we want to write our tooling. Not anymore.
+
+Enter RBCli. RBCli is a framework to quickly develop advanced command-line tools in Ruby. It has been written from the ground up with the needs of the modern technologist in mind, designed to make advanced CLI tool development as painless as possible. In RBCli, low-level code has been wrapped and/or replaced with higher-level methods. Much of the functionality has even been reduced to single methods: for example, it takes just one declaration to define, load, and generate a user's config file at the appropriate times. Many other features are automated and require no work by the engineer. These make RBCli a fundamental re-thining of how we develop CLI tools, enabling the rapid development of applications for everyone from hobbyists to enterprises.
+
+
+Some of its key features include:
+
+* __Simple DSL Interface__: To cut down on the amount of code that needs to be written, RBCli has a DSL that is designed to cut to the chase. This makes the work a lot less tedious.
+  
+* __Multiple Levels of Parameters and Arguments__: Forget about writing parsers for command-line options, or about having to differentiate between parameters and arguments. All of that work is taken care of.
+
+* __Config File Generation__: Easily piece together a default configuration even with declarations in different parts of the code. Then the user can generate their own configuration, and it gets stored in whatever location you'd like.
+
+* __Multiple Hooks and Entry Points__: Define commands, pre-execution hooks, post-execution hooks, and first_run hooks to quickly and easily customize the flow of your application code.
+
+* __Logging__: Keep track of all instances of your tool through logging. Logs can go to STDOUT, STDERR, or a given file, making them compatible with log aggregators such as Splunk, Logstash, and many others.
+
+* __Local State Storage__: Easily manage a set of data that persists between runs. You get access to a hash that is automatically kept in-sync with a file on disk.
+
+* __Remote State__: It works just like Local State Storage, but store the data on a remote server! It can be used in tandem with Local State Storage or on its own. Currently supports AWS DyanmoDB.  
+
+* __State Locking and Sharing__: Share remote state safely between users with built-in locking! When enabled, it makes sure that only one user is accessing the data at any given time.
+
+* __Automatic Update Notifications__: Just provide the gem name or git repo, and RBCli will take care of notifying users!
+
+* __External Script Wrapping__: High-level wrapping for Bash scripts, or any other applcication you'd like to wrap into a command.
+
+* __Project Structure and Generators__: Create a well-defined project directory structure which organizes your code and allows you to package and distribute your application as a Gem. Generators can also help speed up the process of creating new commands, scripts, and hooks!
+
+
+If you're just getting started with RBCli, take a look at the [Tutorial][tutorial]. Or take a look at the [Advanced] menu above to look through RBCli's additional featureset.
+
+
+[tutorial]: ./tutorial/10-getting_started.md
+[advanced]: ./advanced/user_config_files.md

data/docs-src/docs/tutorial/10-getting_started.md

@@ -0,0 +1,41 @@
+# Getting Started
+
+Welcome to the RBCli getting started tutorial! In this tutorial we're going to cover the basics of RBCli and get a simple application up and running. It should take you between 30-60 minutes to complete, depending on your skill level with Ruby.
+
+As you go throught the tutorial, you can either use the __Next__ and __Back__ buttons on the page to navigate, or use the menu directly.
+
+## Supported Ruby Versions
+
+You'll need Ruby installed before you can use RBCli. If you don't know how to install it, we recommend using either [rbenv][rbenv] (our favorite) or [rvm][rvm].
+
+RBCli officially supports Ruby versions 2.5.0 and above. It may work on earlier releases even though we haven't tested them. If you do try it find any bugs that break compatibility, feel free to submit a github issue or pull request.
+
+## Installation
+
+RBCli is available on rubygems.org. You can add it to your application's `Gemfile` or `gemspec`, or install it manually by running:
+
+```bash
+gem install rbcli
+```
+
+Then, `cd` to the folder you'd like to create your project under and run:
+
+```bash
+rbcli init -n mytool -d "A simple CLI tool"
+```
+
+where `mytool` can be replaced with any other command name you'd like. You should then see some output about generating a bunch of files. Once it finishes, run:
+
+```bash
+cd mytool
+ls -ahl
+```
+
+Congratulations! This is the beginning of your first project.
+
+## Next Steps
+
+Next, you will learn about the layout of an RBCli project and how to code with it.
+
+[rbenv]: https://github.com/rbenv/rbenv
+[rvm]: https://rvm.io

data/docs-src/docs/tutorial/20-project_layout.md

@@ -0,0 +1,115 @@
+# The Project Layout
+
+Now we will learn about what an RBCli project looks like and how to start using it.
+
+## Project Initialization Types
+
+RBCli can initialize a tool in three different modes:
+
+- Project Mode (default)
+- Mini Mode
+- Micro Mode
+
+### Project Mode
+
+If you've been following along with the tutorial, you've already seen Project Mode. An RBCli Project consists of several folders, each of which has a specific function. The RBCli framework handles loading and parsing the code automatically. To generate a standard, full-featured RBCli project, run:
+
+```bash
+rbcli init -n mytool
+```
+
+where `mytool` can be replaced with any other command name you'd like. (We will continue using `mytool` in this tutorial though!)
+
+Inside the newly created `mytool` folder you will see a bunch of files and folders related to your project. We will go over the structure later.
+
+### Mini & Micro Modes
+
+If you need to write a CLI tool but project mode feels a bit overkill for you -- if you think a single-file script is all that is needed -- that's where the Mini and Micro modes come in. Instead of generating a full directory tree, you get only a single file that contains most of the functionality of RBCli. To use it, run:
+
+```bash
+rbcli init -n mytool -t mini
+# or
+rbcli init -n mytool -t micro
+```
+
+The only difference between the two is that `mini` will show you all available options and some documentation to help you, while `micro` is for advanced users who just want the samllest file possible.
+
+As far as documentation goes, every piece of code present in those files is identical to Project mode so it should be pretty easy to navigate.
+
+## Project Mode Structure
+
+An RBCli project has the following structure:
+
+```text
+<name>/
+|--- application/
+|   |--- commands/
+|   |   |--- scripts/
+|   |--- options.rb
+|--- config/
+|--- exe/
+|   |--- <name>
+|--- hooks/
+|--- lib/
+|--- spec/
+|--- userconf/
+|--- .gitignore
+|--- .rbcli
+|--- .rspec
+|--- CODE_OF_CONDUCT.md
+|--- Gemfile
+|--- README.md
+|--- Rakefile
+|--- <name>.gemspec
+```
+
+## Git, RubyGems, and rspec
+
+A few files aren't part of RBCli itself, but are provided for your convenience. If you're experienced in Ruby and Git you can skip over this.
+
+* `.gitignore`
+	* Specifies which files to ignore in git. If you don't use git you can delete this file
+* `.rspec`
+	* Configures Rspec for testing your code
+* `Gemfile`
+	* Allows declaring dependencies for when your users install your application
+* `Gemspec`
+	* Same as above, but also lets you fill in more information so that you can publish your application as a gem
+* `README.md`
+	* A skeleton README file that will appear as a front page documentation to your code in most source control systems (i.e. Github, Bitbucket)
+* `CODE_OF_CONDUCT.md`
+	* Taken directly from the [contributor covenant][contributor_covenant] for your convenience
+* `Rakefile`
+	* So you can run rspec tests as a rake task
+
+There is a lot of controvesy online regarding using the `gemfile` vs the `gemspec`. If you are new to Ruby in general then I suggest declaring your dependencies in the gemspec and leaving the `gemfile` as-is. This keeps things simple and allows publishing and distributing your tool as a gem.
+
+Additionally, note that a git repo is not created automatically. Using git is out of scope of this tutorial, but you can find tutorials [here][git_tutorials].
+
+## RBCli Folders
+
+* `application/`
+	* This is where the core of your application will live. You will define CLI options, commands, scripts, and hooks within this folder.
+* `config/`
+	* This folder contains the configuration for RBCli's features; such as storage, logging, and automatic updates.
+* `exe/`
+	* This folder contains the executable for your tool. You should not edit it; doing so may lead to unexpected behavior.
+* `hooks/`
+	* RBCli has several hooks that can be used to run code at different times, such as the 'default' code that is run when no command is selected. This is where they are placed.
+* `lib/`
+	* This folder is for you to write any additional code as you see fit, for importing into your commands, scripts, and hooks. It is automatically added to the $LOAD_PATH for you, so you can just use require statements like `require 'abc.rb'`  without worrying about where they are located on the filesystem.
+* `userconf/`
+	* This folder is for you to place the layout and defaults of any userspace config file. Acceptable formats are yaml and json, though we recommend YAML since it is by far easier to read and supports comments.
+* `spec/`
+	* This folder is for your rspec tests.
+* `.rbcli`
+	* This file is for internal use by RBCli. It should not be modified or deleted.
+
+## Next Steps
+
+For the purposes of getting started right now, you don't actually need to edit any of the defaults already present.
+
+We just finished going through what an RBCli project looks like. Now let's create our first application with it!
+
+[contributor_covenant]: http://contributor-covenant.org
+[git_tutorials]: https://www.tutorialspoint.com/git/

data/docs-src/docs/tutorial/30-your_first_command.md

@@ -0,0 +1,126 @@
+# Your First Command
+
+## Creating the Command
+
+Creating the command is straightforward:
+
+```bash
+rbcli command --name=list
+#or
+rbcli command -n list
+```
+
+And there you have it! Now you can try out your command by typing:
+
+```bash
+./exe/mytool list
+```
+
+Congrats! You should now see a generic output listing the values of several variables. We'll get into what they mean in a bit, but first, let's make the tool's execution a bit easier.
+
+
+Now that you know your way around a project, its time to create your first command! But before we do, let's make development just a little bit easier. Go to the base directory of the folder and type:
+
+```bash
+alias mytool="$(pwd)/exe/mytool"
+```
+
+And now you'll be able to execute your application as if it was already installed as a gem, without worrying about the working path. You can see this in action by running your application again, but without the path:
+
+```bash
+mytool list
+```
+
+So, now let's take a more in-dpeth look at what the command code looks like.
+
+## The Command Declaration
+
+As mentioned in the previous section, you can find your commands listed under the `application/commands/` directory. Each command will appear as its own unique file with some base code to work from. Let's take a look at that code a little more in-depth:
+
+```ruby
+class List < Rbcli::Command                                                           # Declare a new command by subclassing Rbcli::Command
+	description 'TODO: Description goes here'                                           # (Required) Short description for the global help
+	usage <<-EOF
+TODO: Usage text goes here
+EOF                                                                                   # (Required) Long description for the command-specific help
+	parameter :force, 'Force testing', type: :boolean, default: false, required: false  # (Optional, Multiple) Add a command-specific CLI parameter. Can be called multiple times
+
+	config_default :myopt2, description: 'My Option #2', default: 'Default Value Here'  # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config.
+                                                                                      # Alternatively, you can simply create a yaml file in the `default_user_configs` directory in your project that specifies the default values of all options
+
+	action do |params, args, global_opts, config|                                       # (Required) Block to execute if the command is called.
+		Rbcli::log.info { 'These logs can go to STDERR, STDOUT, or a file' }              # Example log. Interface is identical to Ruby's logger
+		puts "\nArgs:\n#{args}"                    # Arguments that came after the command on the CLI (i.e.: `mytool test bar baz` will yield args=['bar', 'baz'])
+		puts "Params:\n#{params}"                  # Parameters, as described through the option statements above
+		puts "Global opts:\n#{global_opts}"        # Global Parameters, as descirbed in the Configurate section
+		puts "Config:\n#{config}"                  # Config file values
+		puts "LocalState:\n#{Rbcli.local_state}"   # Local persistent state storage (when available) -- if unsure use Rbcli.local_state.nil?
+		puts "RemoteState:\n#{Rbcli.remote_state}" # Remote persistent state storage (when available) -- if unsure use Rbcli.remote_state.nil?
+		puts "\nDone!!!"
+	end
+end
+```
+
+Commands are declared to RBCli simply by subclassing them from `Rbcli::Command` as shown above. Then, you have a list of declarations that tell RBCli information about it. They are:
+
+* `description`
+	* A short description of the command, which will appear in the top-level help (when the user runs `mytool -h`).
+* `usage`
+	* A description of how the command is meant to be used. This description can be as long as you want, and can be as in-depth as you'd like. It will show up as a long, multi-line description when the user runs the command-sepcific help (`mytool list -h`).
+* `parameter`
+	* Command-line tags that the user can enter that are specific to only this command. We will get into these in the next section on [Options, Parameters, and Arguments][parameters_documentation]
+* `config_default`
+	* This sets a single item in the config file that will be made available to the user. More information can be found in the documentation on [User Config Files][user_config_documentation]
+* `action`
+	* This loads the block of code that will run when the command is called. It brings in all of the CLI and user config data as variables. We will also get into these in the next section [Options, Parameters, and Arguments][parameters_documentation]
+
+There is an additional declaration not shown here, `extern`. You can find more information on it in the section on [Advanced Command Types][avanced_command_types_documentation]
+
+
+## Creating the "list" Command
+
+Now we're going to modify this command to list the contents of the current directory to the terminal. So let's change the code in that file to:
+
+```ruby
+class List < Rbcli::Command
+	description %q{List files in current directory}
+	usage <<-EOF
+Ever wanted to see your files?
+Now you can!
+EOF
+
+	action do |params, args, global_opts, config|
+		filelist = []
+
+		# We store a list of the files in an array, including dotfiles if specified
+		Dir.glob "./*" do |filename|
+			outname = filename.split('/')[1]
+			outname += '/' if File.directory? filename
+			filelist.append outname
+		end
+		
+		# Apply color
+		filelist.map! do |filename|
+			if File.directory? filename
+				filename.light_blue
+			elsif File.executable? filename
+				filename.light_green
+			else
+				filename
+			end
+		end if global_opts[:color]
+
+		puts filelist
+	end
+end
+```
+
+Go ahead and test it out! The output doesn't show much obviously, just a list of names and nothing else. Don't worry though, we'll fix that in the next secion.
+
+## Next Steps
+
+Next we're going to take a look at options, parameters, and arguments, and we'll clean up our list command by using them. If you'd like to learn more about the additional command types in RBCli before continuing, see the [Advanced Command Types][avanced_command_types_documentation] documentation.
+
+[parameters_documentation]: 40-options_parameters_and_arguments.md
+[user_config_documentation]: ../advanced/user_config_files.md
+[avanced_command_types_documentation]: ../advanced/command_types.md