rbcli 0.3.2 → 0.4.0

data/docs-src/content/tutorial/40-options_parameters_and_arguments.md

@@ -1,282 +0,0 @@
----
-title: "Options, Parameters, and Arguments"
-date: 2019-06-20T15:07:21-04:00
-draft: false
-pre: "<b>4. </b>"
-weight: 40
----
-
-If you're already an experienced coder, you can jump to the last section of this document, the [Simplified Reference (TLDR)](#simplified-reference-tldr)
-
-## Command Line Structure
-
-In the previous section, you saw two parts of the RBCli command line structure - the executable followed by the command. However, RBCli is capable of more complex interaction. The structure is as follows:
-
-```
-toolname [options] command [parameters] argument1 argument2...
-```
-
-* __Options__ are command line parameters such as `-f`, or `--force`. These are available globally to every command. You can create your own, though several are already built-in and reserved for RBCli:
-	* `--config-file=<filename>` allows specifying a config file location manually.
-	* `--generate-config` generates a config file for the user by writing out the defaults to a YAML file. This option will only appear if a config file has been set. The location is configurable, with more on that in the documentation on [User Config Files][user_config_documentation]).
-	* `-v / --version` shows the version.
-	* `-h / --help` shows the help.
-* __Command__ represents the subcommands that you will create, such as `list`, `test`, or `apply`.
-* __Parameters__ are the same as options, but only apply to the specific subcommand being executed. In this case only the `-h / --help` parameter is provided automatically.
-* __Arguments__ are strings that don't begin with a '-', and are passed to the command's code as an array. These can be used as subcommands or additional parameters for your command. 
-
-So a valid command could look something like these:
-
-```shell
-mytool -n load --filename=foo.txt
-mytool parse foo.txt
-mytool show -l
-```
-
-Note that all options and parameters will have both a short and long version of the parameter available for use.
-
-So let's take a look at how we define them.
-
-
-## Options
-
-You can find the options declarations under `application/options.rb`.  You'll see the example in the code:
-
-```ruby
-option :name, 'Give me your name', short: 'n', type: :string, default: 'Jack', required: false, permitted: ['Jack', 'Jill']
-```
-
-This won't do for our tool, so let's change it. Remember that these options will be applicable to all of our commands, so lets make it something appropriate:
-
-```ruby
-option :color, 'Enable color output', short: 'c', type: :boolean, default: false
-```
-
-So now, let's take advantage of this flag in our `list` command. Let's change our block to:
-
-```ruby
-	action do |params, args, global_opts, config|
-		Dir.glob "./*" do |filename|
-			outname = filename.split('/')[1]
-			outname += '/' if File.directory? filename
-
-			# We change the color based on the kind of file shown
-			if global_opts[:color]
-				if File.directory? filename
-					outname = outname.light_blue
-				elsif File.executable? filename
-					outname = outname.light_green
-				end
-			end
-			
-			puts outname
-		end
-	end
-```
-
-Notice how we referenced the value by using `global_opts[:color]`. It's that simple. To see it in action, run:
-
-```bash
-mytool -c list
-```
-
-## Parameters
-
-Parameters work the same way as options, but they are localized to only the selected command. They are declared - as you probably guessed by now - in the command's class. So let's add the following lines to our list command within the class declaration:
-
-```ruby
-parameter :sort, 'Sort output alphabetically', type: :boolean, default: false
-parameter :all, 'Show hidden files', type: :boolean, default: false
-parameter :directoriesfirst, 'Show directories on top', type: :boolean, default: false
-```
-
-And let's modify our action block to utilize them:
-
-```ruby
-	action do |params, args, global_opts, config|
-		filelist = []
-
-		# We include dotfiles if specified
-		include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0
-		
-		# We store a list of the files in an array, including dotfiles if specified
-		Dir.glob "./*", include_dotfiles do |filename|
-			outname = filename.split('/')[1]
-			outname += '/' if File.directory? filename
-			filelist.append outname
-		end
-
-		# Sort alphabetically if specified
-		filelist.sort! if params[:sort]
-
-		# Put directories first if specified
-		if params[:directoriesfirst]
-			files = []; dirs = []
-			filelist.each do |filename|
-				if File.directory? filename
-					dirs.append(filename)
-				else
-					files.append(filename)
-				end
-			end
-			filelist = dirs + files
-		end
-		
-		# Apply color. We do this at the end now because color codes can alter the sorting.
-		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
-```
-
-You should be able to run it now:
-
-```bash
-mytool -c list -asd
-```
-
-Note how the parameters come after the `list` command in the syntax above. As you create more commands, each will have its own unique set of parameters, while the options remain _before_ the command and are available to all of them.
-
-### User Prompting
-
-There is an additional option when declaring parameters to prompt the user for a value if not entered on the command line. This can be done with the `prompt:` keyword. Let's change one of our parameters to utilize it:
-
-```ruby
-parameter :sort, 'Sort output alphabetically', type: :boolean, default: false, prompt: "Sort output alphabetically?"
-```
-
-Now, let's run the tool while omitting the `--sort` parameter, as such:
-
-```bash
-mytool -c list -ad
-```
-
-This should give you the prompt:
-
-```
-Sort output alphabetically? (y/N):
-```
-
-Because we set the parameter to default to `false` the default here is `N`, which is used if the user hits enter without entering a letter. If the default was set to `true`, then the `Y` would be capitalized and be the default.
-
-For more information, see the documentation on [Interactive Commands][interactive_commands].
-
-## Arguments
-
-Lastly on the command line, there are arguments. Arguments are simply strings without the `-` character in front, and automatically get passed into an array in your applicaiton. Let's take a look at how we can use them.
-
-Unlike options and parameters, arguments require no setup. So let's assume that we want any arguments passed to the `list` command to be filenames that you want to display, and that you can pass multiple ones. Since arguments aren't listed automatically by the help function, this is a good example of what to put in your usage text. Let's take a look at what our class looks like now:
-
-```ruby
-class List < Rbcli::Command
-	description %q{List files in current directory}
-	usage <<-EOF
-To list only specific files, you can enter filenames as arguments
-
-	mytool list filename1 filename2...
-EOF
-	parameter :sort, 'Sort output alphabetically', type: :boolean, default: false
-	parameter :all, 'Show hidden files', type: :boolean, default: false
-	parameter :directoriesfirst, 'Show directories on top', type: :boolean, default: false
-
-	action do |params, args, global_opts, config|
-		filelist = []
-
-		# We include dotfiles if specified
-		include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0
-		
-		# We store a list of the files in an array, including dotfiles if specified
-		Dir.glob "./*", include_dotfiles do |filename|
-			outname = filename.split('/')[1]
-			next unless args.include? outname if args.length > 0
-			outname += '/' if File.directory? filename
-			filelist.append outname
-		end
-
-		# Sort alphabetically if specified
-		filelist.sort! if params[:sort]
-
-		# Put directories first if specified
-		if params[:directoriesfirst]
-			files = []; dirs = []
-			filelist.each do |filename|
-				if File.directory? filename
-					dirs.append(filename)
-				else
-					files.append(filename)
-				end
-			end
-			filelist = dirs + files
-		end
-		
-		# Apply color. We do this at the end because color codes can alter the sorting
-		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
-```
-
-
-
-## Simplified Reference (TLDR)
-
-RBCli enforces a CLI structure of:
-
-```
-toolname [options] command [parameters] argument1 argument2...
-```
-
-__Options__ are declared in `application/options.rb` file.
-
-__Parameters__ are declared in the respective command's class declaration.
-
-__Arguments__ don't need to be declared, and are passed in as an array to your commands. It is helpful to describe the argument purpose in the `usage` text declaration so that the user can see what to do in the help.
-
-__Options__ and __parameters__ both use the same format:
-
-```ruby
-option    :<name>, "<description_string>", short: '<character>', type: <variable_type>, default: <default_value>, permitted: [<array_of_permitted_values]
-
-parameter :<name>, "<description_string>", short: '<character>', type: <variable_type>, default: <default_value>, permitted: [<array_of_permitted_values]
-```
-
-* `name`
-	* (Required) The long name of the option, as a symbol. This will be represented as `--name` on the command line
-* `description_string`
-	* (Required) A short description of the command that will appear in the help text for the user
-* `type`
-	* (Required) The following types are supported: `:string`, `:boolean` or `:flag`, `:integer`, and `:float`
-* `default`
-	* (Optional) A default value for the option if one isn't entered (default: nil)
-* `short`
-	* (Optional) A letter that acts as a shortcut for the option. This will allow users to apply the command as `-n`
-	* To not have a short value, set this to :none (default: the first letter of the long name)
-* `required`
-	* (Optional) Specify whether the option is required from the user (default: false)
-* `permitted`
-	* (Optional) An array of whitelisted values for the option (default: nil)
-
-## Next Steps
-
-Next, we're going to take a quick look at how to publish and distribute your application, both publicly and within your organization.
-
-[user_config_documentation]: {{< ref "advanced/user_config_files" >}}
-[regex_explanation]: https://medium.com/factory-mind/regex-tutorial-a-simple-cheatsheet-by-examples-649dc1c3f285
-[interactive_commands]: {{< ref "advanced/interactive_commands" >}}

data/docs-src/content/tutorial/50-publishing.md

@@ -1,53 +0,0 @@
----
-title: "Publishing Your Application"
-date: 2019-06-20T15:07:21-04:00
-draft: false
-pre: "<b>5. </b>"
-weight: 50
----
-
-RBCli creates projects designed to be easily distributed via either source control or as a gem. We'll go over both methods.
-
-## Common Tasks
-
-Regardless of where you are publishing, certain tasks need to be accomplished. Namely, preparing the gemspec and the README.
-
-In both files the items that need changing are pretty obvious -- you'll need to fill out your name, email, etc, and replace the placeholder text in the README with something useful to your users.
-
-Then, for every release, you'll need to update the version number in `config/version.rb`. This number is automatically used by the `gemspec` when versioning the gem in the system, and by RBCli when displaying help to the user and checking for automatic updates if you enable that feature (see [Automatic Updates][automatic_update_documentation] for more information).
-
-## Source Control Distribution
-
-With Source Control distribution your users will be cloning the source code directly from your repository, and building and installing the gem locally. Thankfully, the process is pretty simple:
-
-```bash
-git clone <your_repo_here>
-gem build mytool.gemspec
-gem install mytool-*.gem
-```
-
-Note that he README's placeholder text has these commands already listed for your users, which you can leave as instructions.
-
-When using this method, we highly recommend using a git flow where you only merge to master when you are ready to release, this way your users don't inadvertently download a buggy commit.
-
-## Rubygems.org Distribution
-
-If you're distributing as a gem via Rubygems.org, you'll need to follow a specific release process.
-
-1. Update the version number in `config/version.rb`
-2. Commit the change locally
-3. Run `bundle exec rake release`
-
-This will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Recommended Platforms
-
-As far as RBCli is concerned, all Git hosts and gem platforms work equally well, and as long as the code reaches your users in one piece it's all the same. That said, if you'd like to take advantage of automatic update notifications for your users, please see the documentation for [Automatic Updates][automatic_update_documentation] for a list of supported platforms for that feature. 
-
-## Next Steps
-
-Congratulations! You've completed the tutorial on RBCli and should be able to make all sorts of CLI applications and tools with what you learned. That said, there are still many features in RBCli that we didn't explore, which you can find in the __Advanced__ section of this site. If you aren't sure where to start, we recommend looking at [User Config Files][user_config_files_documentation] and going from there.
-
-
-[automatic_update_documentation]: {{< ref "advanced/automatic_updates" >}}
-[user_config_files_documentation]: {{< ref "advanced/user_config_files" >}}

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

@@ -1,11 +0,0 @@
-+++
-title = "Tutorial"
-date = 2019-06-20T15:08:08-04:00
-weight = 10
-chapter = true
-#pre = "<b>X. </b>"
-+++
-
-# Tutorial
-
-Get yourself started with RBCli. This section alone won't make you a Ninja, but you'll be able to cut a tool from scratch pretty quickly.

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

@@ -1,34 +0,0 @@
-+++
-title = "My Letter To You"
-#menuTitle = "whoami"
-date = 2019-06-20T15:46:52-04:00
-weight = 40
-chapter = false
-#pre = "<b>X. </b>"
-+++
-
-My Fellow Coder,
-
-I'm glad to see you are interested in RBCli. I'd like to introduce myself. My name is Andrew, and I've been a technologist since 1992 when my father bought our first family computer -- a 486DX2 which ran at 66Mhz (33Mhz if you turned off the 'turbo' button) and came with MS DOS 5.0, [QBasic](https://en.wikipedia.org/wiki/QBasic), and a game already coded in it called [Nibbles](https://classicreload.com/qbasic-nibbles.html) (if you care to see the code, die 5 times and don't play again). I didn't like that the game forced my name to be "Sammy", and thought, "hey, if I can see the code, can't I change it?". So I did what any annoyed child would do and learned to code so I could do just that. I'd tell you what I changed it to, but I was so proud of myself for this simple feat that I changed it every 30 seconds and couldn't settle on just one name. Then I performed my first ever hack, and figured out how to go through walls without dying. All of a sudden the world seemed limitless.
-
-I was only a child at the time, but on that day I learned that every "rule" in computing was an artifical construct and could be changed to suit your needs. Thus began my career in tech and my obsession to change the world with it. This is why RBCli was born.
-
-RBCli started as a collection of code that I would copy-paste between projects, until one day when I wondered if I could just find a framework that suited me. I couldn't - in case you hadn't guessed - so I decided to build my own and give it to the world. I would not have accomplished even half of what I have without the open source community, and this is to be the first of hopefully many contributions back.
-
-The features in RBCli have been chosen from over 25 years of experience writing applications, building features that 3rd parties left out, managing large scale infrastructure, designing embedded systems, integrating enterprise systems, automating CI/CD, scripting my own computers, and so much more. I hope that you can find as much use out of it as I have.
-
-If you'd like to get in touch with me at any time, feel free to email me at [akhoury@live.com](mailto:akhoury@live.com).
-
-All the best,
-
-_Andrew_
-
-
-P.S.: If you really liked RBCli and want to support it, any amount you can help out with goes a long way.
-
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----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-----END PKCS7-----">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
-</form>

data/docs-src/layouts/partials/logo.html

@@ -1,3 +0,0 @@
-<a id="logo" href="{{ .Site.BaseURL }}" style="font-size: 40px">
-  <span class="fas fa-terminal"></span>&nbsp;𝚁𝙱𝙲𝚕𝚒
-</a>

data/docs-src/makesite.sh

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-
-if ! which hugo &> /dev/null; then
-	echo "Hugo not found. Installing..."
-	brew install hugo
-fi
-
-DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"
-
-# Changelog
-_chlog_src="${DIR}/../CHANGELOG.md"
-_chlog_target="${DIR}/content/development/changelog.md"
-cat << EOF > ${_chlog_target}
----
-title: "Changelog"
-date: 2019-06-20T15:07:21-04:00
-draft: false
-weight: 100
----
-
-EOF
-cat ${_chlog_src} | tail -n +2 >> ${_chlog_target}
-
-
-# Quick Reference
-_qref_src="${DIR}/../README.md"
-_qref_target="${DIR}/content/quick_reference/_index.md"
-cat << EOF > ${_qref_target}
-+++
-title = "Quick Reference"
-date = 2019-06-20T15:49:49-04:00
-weight = 1
-chapter = false
-draft = false
-+++
-
-EOF
-sed -n '/Quick Reference/,$p' ${_qref_src} | tail -n +2 >> ${_qref_target}
-
-hugo -d "${DIR}/../docs"

data/docs-src/runsite.sh

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-
-if ! which hugo &> /dev/null; then
-	echo "Hugo not found. Installing..."
-	brew install hugo
-fi
-
-hugo server -D

data/docs-src/themes/hugo-theme-learn/.editorconfig

@@ -1,16 +0,0 @@
-# https://editorconfig.org
-
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_size = 2
-indent_style = space
-trim_trailing_whitespace = true
-
-[*.js]
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false

data/docs-src/themes/hugo-theme-learn/.gitignore

@@ -1,3 +0,0 @@
-.DS_Store
-public/
-exampleSite/public

data/docs-src/themes/hugo-theme-learn/.grenrc.yml

@@ -1,25 +0,0 @@
----
-  dataSource: "prs"
-  prefix: "v"
-  onlyMilestones: false
-  changelogFilename: "CHANGELOG.md"
-  includeMessages: "all"
-  ignoreIssuesWith:
-    - "support"
-  ignoreLabels:
-    - "duplicate"
-    - "invalid"
-    - "wontfix"
-  groupBy:
-    New features:
-      - "feature"
-    Bug Fixes:
-      - "bug"
-    Enhancements:
-      - "enhancement"
-    Internationalisation:
-      - "i18n"
-    Theme Meta:
-      - "meta"
-    Uncategorised:
-      - "closed"