rbcli 0.3.2 → 0.4.0

data/docs-src/content/advanced/state_storage.md

@@ -1,120 +0,0 @@
----
-title: "State Storage"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-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's local state storage gives you access to a hash that is automatically persisted to disk when changes are made.
-
-### Configuration
-
-You can configure it in `config/storage.rb`.
-
-```ruby
-local_state '/var/mytool/localstate', force_creation: true, halt_on_error: true
-```
-
-There are three parameters to configure it with:
-
-* The `path` as a string (self-explanatory)
-* `force_creation`
-	* This will attempt to create the path and file if it does not exist (equivalent to an `mkdir -p` and `touch` in linux)
-* `halt_on_error`
-	* RBCli's default behavior is to raise an exception if the file can not be created, read, or updated at any point in time
-	* If this is set to `false`, RBCli will silence any errors pertaining to file access and will fall back to whatever data is available. Note that if this is enabled, changes made to the state may not be persisted to disk.
-		* If creation fails and file does not exist, you start with an empty hash
-		* If file exists but can't be read, you will have an empty hash
-		* If file can be read but not written, the hash will be populated with the data. Writes will be stored in memory while the application is running, but will not be persisted to disk.
-
-
-### Access and Usage
-
-Once configured you can access it with a standard hash syntax in your Standard Commands:
-
-```ruby
-Rbcli.local_state[:yourkeyhere]
-```
-
-The methods available for use at the top level are as follows:
-
-Hash native methods:
-
-* `[]` (Regular hash syntax. Keys are accessed via either symbols or strings indifferently.)
-* `[]=` (Assignment operator)
-* `delete`
-* `each`
-* `key?`
-
-Additional methods:
-
-* `commit`
-	* Every assignment to the top level of the hash will result in a write to disk (for example: `Rbcli.local_state[:yourkey] = 'foo'`). However, if you are manipulating nested hashes, these saves will not be triggered. You can trigger them manually by calling `commit`.
-* `clear`
-	* Resets the data back to an empty hash.
-* `refresh`
-	* Loads the most current version of the data from the disk
-* `disconnect`
-	* Removes the data from memory and sets `Rbcli.local_state = nil`. Data will be read from disk again on next access.
-
-
-Every assignment will result in a write to disk, so if an operation will require a large number of assignments/writes it should be performed to a different hash before beign assigned to this one.
-
-
-## Remote State
-
-RBCli's remote state storage gives you access to a hash that is automatically persisted to a remote storage location when changes are made. It has optional locking built-in, meaning that multiple users may share remote state without any data consistency issues.
-
-Currently, this feature requires AWS DynamoDB, though other backend systems will be added in the future.
-
-### Configuration
-
-Before DynamoDB can be used, AWS API credentials have to be created and made available. RBCli will attempt to find credentials from the following locations in order:
-
-1. User's config file
-2. Environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
-3. User's AWSCLI configuration at `~/.aws/credentials`
-
-For more information about generating and storing AWS credentials, see [Configuring the AWS SDK for Ruby][aws_sdk_credentials]. Please make sure that your users are aware that they will need to provide their own credentials to use this feature.
-
-You can configure it in `config/storage.rb`.
-
-```ruby
-remote_state_dynamodb table_name: 'mytable', region: 'us-east-1', force_creation: true, halt_on_error: true, locking: false
-```
-
-These are the parameters:
-
-* `table_name`
-	* The name of the DynamoDB table to use.
-* `region`
-	* The AWS region that the database is located
-* `force_creation`
-	* Creates the DynamoDB table if it does not already exist
-* `halt_on_error`
-	* Similar to the way [Local State](#local-state) works, setting this to `false` will silence any errors in connecting to the DynamoDB table. Instead, your application will simply have access to an empty hash that does not get persisted anywhere.
-	* This is good for use cases that involve using this storage as a cache, where a connection error might mean the feature doesn't work but its not important enough to interrupt the user.
-* `locking`
-	* Setting this to `true` enables locking, meaning only one instance of your application can access the shared data at any given time. For more information see [Distributed State Locking][distributed_state_locking].
-
-
-### Access and Usage
-
-Once configured you can access it with a standard hash syntax:
-
-```ruby
-Rbcli.remote_state[:yourkeyhere]
-```
-
-This works the same way that [Local State](#local-state) does, with the same performance caveats (try not to write too frequently).
-
-Note that all state in Rbcli is __lazy-loaded__, so no connections will be made until your code attempts to access the data even if the feature is enabled.
-
-For more information on the available commands, see the documentation on [Local State](#local-state)
-
-
-[aws_sdk_credentials]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html
-[distributed_state_locking]: {{< ref "advanced/distributed_state_locking" >}}

data/docs-src/content/advanced/user_config_files.md

@@ -1,51 +0,0 @@
----
-title: "User Configuration Files"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-RBCli provides built-in support for creating and managing userspace configuration files. It does this through two chains: the __defaults chain__ and the __user chain__.
-
-## Defaults chain
-
-The defaults chain allows you to specify sane defaults for your CLI tool throughout your code. This gives you the ability to declare configuration alongside the code, and allows RBCli to generate a user config automatically given your defaults. There are two ways to set them:
-
-* YAML Files
-	* You can store your defaults in one or more YAML files and RBCli will import and combine them. Note that when generating the user config, RBCli will use the YAML text as-is, so comments are transferred as well. This allows you to write descriptions for the options directly in the file that the user can see.
-	* This is good for tools with large or complex configuration that needs user documentation written inline
-	* These YAML files should be placed in the `userconf/` directory in your project and they will automatically be loaded
-* DSL Statements
-	* In the DSL, you can specify options individually by providing a name, description, and default value
-	* This is good for simpler configuration, as the descriptions provided are written out as comments in the generated user config
-	* You can put global configuration options in `config/userspace.rb`
-	* Command-specific confiugration can be placed in the command declarations in `application/commands/*.rb`
-
-DSL statements appear in both of the above locations as the following:
-
-```ruby
-config_default :name, description: '<description_help_text>', default: '<default_value>'
-```
-## User chain
-
-The user chain has two functions: generating and loading configuration from a YAML file on the end user's machine.
-
-Rbcli will determine the correct location to locate the user configuration based on two factors:
-
-1. The default location set in `config/userspace.rb`
-2. The location specified on the command line using the `--config-file=<filename>` option (overrides #1)
-
-To configure the default location, edit `config/userspace.rb`:
-
-```ruby
-config_userfile '~/.mytool', merge_defaults: true, required: false
-```
-
-* `path/to/config/file`
-	* Self explanatory. Recommended locations are a dotfile in the user's home directory, or a file under `/etc` such as `/etc/mytool/userconf.yaml`
-* `merge_defaults`
-	* If set to `true`, default settings override user settings. If set to `false`, default settings are not loaded at all and the user is required to have all values specified in their config.
-* `required`
-	* If set to `true` the application will not run if the file does not exist. A message will be displayed to the user to run your application with the `--generate-config` option to generate the file given your specified defaults.
-
-
-Users can generate configs by running `yourclitool --generate-config`. This will generate a config file at the tool's default location specified in the DSL. This location can be overridden via the `--config-file=<filename>` option.

data/docs-src/content/development/_index.md

@@ -1,11 +0,0 @@
-+++
-title = "Development"
-date = 2019-06-20T15:27:12-04:00
-weight = 30
-chapter = true
-#pre = "<b>X. </b>"
-+++
-
-# Development
-
-Want to make RBCli even better? On behalf of all RBCli users everywhere, it's much appreciated. Of course, even if you keep your changes to yourself and don't contribute back, now that you're a ninja you'll likely want to pave your own road forward. This section will guide you how.

data/docs-src/content/development/changelog.md

@@ -1,179 +0,0 @@
----
-title: "Changelog"
-date: 2019-06-20T15:07:21-04:00
-draft: false
-weight: 100
----
-
-
-## 0.3.1 (October 19, 2021)
-
-### Bugfixes
-
-* Fixed prompt for option value to ignore nil defaults instead of displaying an empty string
-* Skeleton script command `script.sh` updated to function correctly when development mode is enabled
-* Updated Github Pages links to point to `github.io` instead of `github.com` which are being deprecated
-* Updated dependencies, closing the security hole of the gem `addressable <= 1.7.0`
-
-## 0.3 (July 31, 2020)
-
-### Improvements
-
-* Deprecated Ruby code has been updated to be compatible with Ruby 2.7.x
-* All depedencies have been updated to their latest versions and tested to ensure continued compatibility
-* Old-style execution hooks have been fully deprecated in favor of declaring them in the `Rbcli::Configurate.hooks` block. To ensure compatibility, save your current hooks and generate new ones using the command `rbcli hook`
-* Skeleton gemspec now includes `spec.required_ruby_version`, which matches Rbcli's requirement
-* Documentation updated to support latest Hugo and theme versions (Hugo 0.74.3 and hugo-theme-learn 2.5.0)
-
-### Features
-
-* Rbcli Deprecation Warnings now show the offending line of code to ease updating
-* The `$libdir` global variable is defined by default in the skeleton project, allwoing easy access to the project's `lib` folder
-
-## 0.2.12 (July 29, 2019)
-
-### Improvements
-
-* The base project skeleton now includes an improved structure for the `lib/` folder
-* Documentation now uses Hugo instead of MkDocs for site generation.
-* Updated dependencies in project skeleton to latest versions
-
-### Features
-
-* Development mode can be enabled by setting the environment variables: `RBCLI_ENV=development` and `RBCLI_DEVPATH=[path to local Rbcli folder]` to simplify changes to Rbcli during development. Combined with setting `alias rbcli='/path/to/rbcli/exe/rbcli'`, gem installation is not required for development work
-
-## 0.2.11 (Feb 27, 2019)
-
-### Improvements
-
-* Updated the dependent gem verions to use the latest available versions
-
-### Bugfixes
-
-* Fixed the nested triggers of the message I/O system
-
-## 0.2.8 (Nov 7, 2018)
-
-### Features
-
-* Added a standardized message I/O system
-
-### Improvements
-
-* Enabled the safe usage of anchors in YAML config files
-* Improved the method of determining the script name to be more portable across OS'es
-
-### Bugfixes
-
-* Fixed an error which caused RBCli to crash when using `local_state`
-* Fixed a bug which caused the `rbcli init` command to occassionally fail for mini and micro projects
-
-### Changes
-
-* Changed the `rbcli init` helptext to match the order of complexity of projects (standard -> mini -> micro)
-
-## 0.2.7 (Oct 17, 2018)
-
-### Improvements
-
-* Added a dev mode for scripts that allows using a local RBCli copy instead of requiring the gem to be installed
-
-### Bugfixes
-
-* Fixed a bug that caused the rbcli tool not to detect project folders correctly.
-* Command parameter `prompt:` now works when `required` is set to `true`.
-
-### Changes
-
-* The `rbcli init` command now initializes into the current working directory instead of creating a new one. 
-* Fixed erroneous documentation about the 'merge' setting on userspace config.
-
-## 0.2.5 (Oct 8, 2018)
-
-### Improvements
-
-* Added a useful error message when local or remote state is used but not initialized.
-
-### Bugfixes
-
-* Fixed a bug in the Github Updater where RBCli crashed when a version tag was not present in the repo. 
-* Fixed a bug where deleting a state key would crash Rbcli
-* Fixed a bug where remote state crashed with certain configurations
-
-## 0.2.4 (Sep 4, 2018)
-
-* This is a dummy release required to update the License in the Gemspec file. The license has not changed (GPLv3).
-
-## 0.2.3 (Sep 4, 2018)
-
-### Features
-
-* Interactive Commands -- Prompt the user for parameters with a given value
-
-### Improvements
-
-* Added documentation on logging
-
-## 0.2.2 (Aug 22, 2018)
-
-### Features
-
-### Bugfixes
-
-* Fixed a bug that caused the logger's target and level not to be configured properly via the Configurate block.
-
-### Improvements
-
-* Lazy-loading has been implemented in optional modules such as autoupdates, remote storage, etc. This means that if you do not enable them in the code, they will not be loaded into memory. This significantly improves loding times for applications.
-* Abstraction system created for configuration. This has significantly simplified the existing codebase and makes future development easier.
-* Deprecation warning system added. This allows for RBCli contributors to notify users of breaking changes that may impact their code.
-* Folder structure has been simplified to ease development.
-* Much of the code has been refactored.
-
-### Deprecations/Changes
-
-* The `Rbcli` module is now `RBCli` to better match the branding. The original `Rbcli` module will still work for this current release, with a warning, but future releases will require code changes. 
-* Hooks are now defined under the `RBCli.Configurate.hooks` block instead of `RBCli.Configurate.me`.
-* The logger is now silent by default. To enable it, it must be configured either via the `Configurate` block or via the user's config file.
-
-
-## 0.2.1 (Aug 8, 2018)
-
-### Features
-
-* Remote Execution added for Script and External commands
-
-### Bugfixes
-
-* Fixed a bug that caused RBCli to crash if a direct path mode script's environment variables were declared as symbols
-
-
-## 0.2.0 (Aug 5, 2018)
-
-### Features
-
-* CLI tool Autoupdate Enabled; when an upgrade to RBCli is detected, the RBCli CLI tool will notify the developer.
-* Official documentation created and hosted with Github Pages
-* RBCli released under GPLv3
-* Copyright/License notice displayed via RBCli tool with `rbcli license` in accordance with GPLv3 guidelines
-
-### Bugfixes
-
-* Fixed version number loading for projects
-* Cleaned up command usage help output
-* Fixed script and external command generation
-
-### Improvements
-
-* A quick reference guide can now be found in README.md
-* Autoupdate feature now allows supplying a custom message
-* Direct Path Mode for External Commands now
-* Added support for a `lib` folder in projects, as a place for custom code, which is automatically added to `$LOAD_PATH` for developers
-* Improved language regarding external commands: Documentation now differentiates between Standard, Scripted, and External Commands
-* Improved language regarding user config files: Now called Userspace Config
-* Options and Parameters now allow specifying the letter to be used for the short version, or to disable it altogether
-* Userspace config can now be disabled by setting the path to nil or removing the declaration
-
-### Deprecations/Changes
-
-* Removed deprecated and broken examples from the examples folder

data/docs-src/content/development/code_of_conduct.md

@@ -1,81 +0,0 @@
----
-title: "Code of Conduct"
-date: 2019-06-20T15:07:21-04:00
-draft: false
-weight: 30
----
-
-__The Contributor Covenant Code of Conduct__
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of experience,
-nationality, personal appearance, race, religion, or sexual identity and
-orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at andrew@blacknex.us. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/

data/docs-src/content/development/contributing.md

@@ -1,88 +0,0 @@
----
-title: "Contribution Guide"
-date: 2019-06-20T15:07:21-04:00
-draft: false
-weight: 10
----
-
-Contributing to RBCli is the same as most open source projects:
-
-1. Fork the repository
-2. Create your own branch
-3. Submit a pull request when ready
-
-That's all there is to it! We've also kept our acceptance criteria pretty simple, as you'll see below. Feel free to submit a pull request even if you don't meet it if you would like your code or feature to be reviewed first; we do want to be mindful of your time and will review submissions before they are polished.
-
-# Develpment Mode
-
- To allow for easy deveopment, Rbcli has a development mode which allows a project to include rbcli from a local folder instead of the default gem path. To use it, add the following to your shell's profile (typically `~/.bash_profile` or `~/.profile`):
-
- ```bash
-export RBCLI_ENV='development'
-export RBCLI_DEVPATH='/path/to/rbcli/lib/rbcli'
-alias rbcli='/path/to/rbcli/exe/rbcli'
-```
-
-# Code Acceptance Criteria
-
-## Tabs, Not Spaces
-
-Please, and thanks. We all like to use different indentation levels and styles, and this will keep us consistent between editors.
-
-For filetypes where tabs are not supported (such as YAML), please stick to using two (2) spaces.
-
-## Documentation for User Features
-
-For any modification that alters the way RBCli is used -- we're talking additional features, options, keyword changes, major behavioral changes, and the like -- the documentation will need to be updated as well. You'll be happy to know we designed it to make the process relatively painless.
-
-RBCli's documentation is essentially a collection of markdown files that have been compiled into a static site using [MkDocs](https://www.mkdocs.org). If you already have python and pip on your system, you can install it by running:
-
-```bash
-pip install mkdocs mkdocs-material
-```
-
-You can find the source markdown files in the `docs-src/docs` folder, and the menu organization in `docs-src/mkdocs.yml`. To preview your changes on a live site, run:
-
-```bash
-mkdocs serve
-```
-
-Also, don't forget to update the __Quick Reference Guide__ in the `README.md` file (the main project one) with information about your changes.
-
-Once you've completed your edits, run the `makesite.sh` command to build the actual HTML pages automatically in the `docs` folder, from where they will be served when live.
-
-## Deprecations
-
-If a feature needs to be deprecated, RBCli has a built-in deprecation message feature. You can leverage it by calling the following code when a deprecated command is called:
-
-```ruby
-Rbcli::DeprecationWarning.new deprecated_command, message, version_when_code_will_be_removed
-```
-
-So, for example:
-
-```ruby
-Rbcli::DeprecationWarning.new 'Rbcli::Configurate.me--first_run', 'Please use `RBCli::Configurate.hooks` as the parent block instead.', '0.3.0'
-```
-
-will display the following message to the user, in red, any any time the application is run:
-
-```text
-DEPRECATION WRNING: The feature `Rbcli::Configurate.me--post_hook` has been deprecated. Please use `RBCli::Configurate.hooks` as the parent block instead. This feature will be removed in version 0.3.0.
-```
-
-Additionally, it will place the same line in the logs using `Rbcli.logger.warn` if logging is enabled.
-
-If a deprecation warning has been added, please remember to mention it in the pull request so that others can update it later.
-
-# Maintainer's Notes
-
-To install this gem onto your local machine from source, run `bundle exec rake install`.
-
-To release a new version, follow theese steps:
-
-1. Update the version number in `version.rb`
-2. Run `bundle exec rake install`, which will update `gemfile.lock` with the correct version and all dependency changes
-3. Run `docs-src/makesite.sh`, which re-compiles the documentation and pulls in the changelog and quick reference automatically
-4. Commit the above changes to master with a commit message of "vX.X.X" (where X.X.X is the version number), but do not push
-5. Run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/docs-src/content/development/license.md

@@ -1,17 +0,0 @@
----
-title: "License Info"
-date: 2019-06-20T15:07:21-04:00
-draft: false
-weight: 20
----
-
-## How RBCli is Licensed
-
-We want to help the developer community build tooling faster and with less work. That's why RBCli was built. And let's face it - most of us aren't lawyers, and don't want to worry about legal fine print when building awesome software. That's why RBCli is released under the __GPLv3 License__. So you're free to use RBCli as you see fit to write free software. If you wish to use RBCli in a commercial offering, please contact me at [andrew@blacknex.us](mailto:andrew@blacknex.us).
-
-
-## The License
-
-You can view the offical license for RBCli [Here](https://github.com/akhoury6/rbcli/blob/master/LICENSE.txt).
-
-For more details about the GPLv3 License, see [Here](https://choosealicense.com/licenses/gplv3/).