RubyGems - rbcli - Versions diffs - 0.3.3 → 0.4.0 - Mend

rbcli 0.3.3 → 0.4.0

Files changed (506) hide show

data/README.md CHANGED Viewed

@@ -1,223 +1,127 @@
-# RBCli
+# Rbcli
-RBCli is currently in Beta stages of development. All releases can be considered stable, though breaking changes may be made between versions.
+Rbcli is currently in the late Beta stages of development. The current release can be considered stable, and the interface has been ironed out and finalized, so if there are any breaking changes between here and v1.0 they should be minor. It is currently being used in production.
 Latest Release: [![Gem Version](https://badge.fury.io/rb/rbcli.svg)](https://badge.fury.io/rb/rbcli) -- See the [changelog][changelog] for complete details.
-[You can find the Official Documentation for RBCli Here.][documentation_home]
+[You can find the Official Documentation for Rbcli Here.][documentation_home]
-[If you want to support RBCli's development, please donate and help keep it going!][documentation_whoami]
+[If you want to support Rbcli's development, please donate and help keep it going!][documentation_whoami]
-## Introduction
-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.
+## About 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.
-* __Lazy Loading__: Even though RBCli is a heavyweight tool, it uses lazy loading to speed up application startup time. This means you don't have to worry about a large framework slowing your application down.
+* __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.
+* __Portable Executable__: Jump-start using Rbcli by creating a simple portable executable! Just fill in the blanks and you're good to go.
-* __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.
+* __Full Gem Structure__: Alternatively, Rbcli can piggyback off of `bundler` to create a full Gem project structure with custom folders to make using the framework easier. This makes using Rbcli to create larger applications a breeze.
-* __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.
+* __Lazy Loading__: Even though Rbcli is a heavyweight tool, it uses lazy loading with its optional features to speed up application startup time. This means you don't have to worry about a large framework slowing your application down, no matter how big it gets.
-* __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.
+* __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.
-* __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.
+* __Config File Generation__: Easily define a configuration file in code, complete with annotations, and have it automatically generated for your users in the format of your choice (yaml, toml, json, or ini).
-* __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.
+* __Config File Validation__: Apply a [schema](https://json-schema.org) to validate the format of the config file when it is loaded, no matter which file format you choose.
-* __Automatic Update Notifications__: Just provide the gem name or git repo, and RBCli will take care of notifying users!
+* __Environment Variable Parsing__: Simply define a prefix and all of the environment variables with that prefix will be parsed into their respective types and put into a Hash for convenient, along with any optional defaults you'd like to set
-* __External Script Wrapping__: High-level wrapping for Bash scripts, or any other applcication you'd like to wrap into a command.
+* __Shell Script Integration__: Integrate with shell scripts to pass along everything from command-line options to parsed config values, and even to allow the script to output logs through Rbcli directly
-* __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!
+* __Multiple Hooks and Entry Points__: Define pre- and post- execution hooks to quickly and easily customize the flow of your application code. Parse all of the config, options, and environment variables before they reach your commands, or clean up your environment afterwards.
-* __Remote Execution__: Automatically execute commands on remote machines via SSH
+* __Logging__: Logs can go to your standard output, a file, or any custom stream of your choice, and can even be redirected or reformatted mid-execution. In additional, Multiple common log formats have been pre-defined to make it easy to get started, and you can even define custom ones.
-* __Interactive Commands__: Automatically prompt users for paramter values if not given on the command line. This pattern allows for easy user interaction while still allowing scripting without the use of _expect_.
+* __Automatic Update Checks__: Just provide the gem name or git repo, and Rbcli will take care of notifying users when you have an update ready for them
 For more information, take a look at the __[official documentation][documentation_home]__ or keep reading for a quick reference.
-# Quick Reference
+# Getting Started
 ## 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
+Rbcli is available on rubygems.org. You can add it to your application's `Gemfile` or `gemspec`:
-### Standard Commands
-To create a new command called `foo`, run:
-```bash
-rbcli command -n foo
+```ruby
+spec.add_dependency 'rbcli', '~> 0.4'
 ```
-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:
+Or install it manually by running:
 ```bash
-rbcli script -n bar
+gem install rbcli
 ```
-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.
+## Quick Start
-### External Commands
+### Rbcli generators (the easy way)
-To create a new external command called `baz`, run:
+Simply `cd` to the folder you'd like to create your project under and run:
 ```bash
-rbcli extern -n baz
+rbcli gem mytool
 ```
-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:
+Or, if you'd just like a single-file executable, run:
 ```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'
+rbcli portable mytool
+rbcli portable -a mytool # Adds annotations
 ```
-Then it can be accessed when writing your commands via:
+### Write it yourself (the hard way)
-```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.
-## Remote Execution
-RBCli can automatically execute script and extern commands on remote machines via SSH. Enable this feature in `config/general.rb` by changing the following line to `true`:
+The generators are generally the easiest way to get up and running, but here's an example of a simple application.
 ```ruby
-remote_execution permitted: false
+#!/usr/bin/env ruby
+require 'rbcli'
+Rbcli::Configurate.cli do
+  appname 'mytool'
+  version '0.1.0'
+  helptext <<~HELPTEXT
+    Something to tell your users about your application in --help
+  HELPTEXT
+  opt :verbose, 'Verbose output'
+end
+Rbcli.command "mycmd" do
+  default
+  action do |opts, _params, _args, _config, _env|
+    Rbcli.log.info "Verbose!" if opts[:verbose]
+    Rbcli.log.info "Hello, world!"
+  end
+end
+Rbcli.go!
 ```
-Then for each command you want to enable remote execution for, add the following directive:
-```ruby
-remote_permitted
+```shell
+$ mytool -v
+Verbose!
+Hello, world!
 ```
-Users can then execute commands remotly by specifying the connection string and credentials on the command line:
-```bash
-mytool --remote-exec [user@]host[:port] --identity (/path/to/private/ssh/key or password) <command> ...
-```
+## Full Documentation
+[You can find the Official Documentation for Rbcli here.][documentation_home]
 ## Development and Contributing
-For more information about development and contributing, please see the [Official Development Documentation][documentation_development]
+For more information about development and contributing, please see the [Official Contribution Guide][documentation_development]
 ## License
-The gem is available as open source under the terms of the [GPLv3][license_text].
-## Full Documentation
-[You can find the Official Documentation for RBCli Here.][documentation_home]
+The gem is available as open source under the terms of the [MIT License][license_text].
 [documentation_home]: https://akhoury6.github.io/rbcli
+[documentation_quickref]: https://akhoury6.github.io/rbcli/quick_reference
 [documentation_development]: https://akhoury6.github.io/rbcli/development/contributing/
 [documentation_whoami]: https://akhoury6.github.io/rbcli/whoami/
 [license_text]: https://github.com/akhoury6/rbcli/blob/master/LICENSE.txt
-[changelog]: https://github.com/akhoury6/rbcli/blob/master/CHANGELOG.md
+[changelog]: https://github.com/akhoury6/rbcli/blob/master/CHANGELOG.md

data/VERSION ADDED Viewed

	@@ -0,0 +1 @@
1	+ 0.4.0