rbcli 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6123cc2792a91f94903c85d80bb940c0e759dd12c2d54f670ba29c660f522d5c
-  data.tar.gz: 68093975766eb32942a94479bb1048feaa154b21b28781335c9215025bb7f5e6
+  metadata.gz: '091cd6eaa815d90823dbb657bc8307322bc0b272a83cf372eaa68456c65aa504'
+  data.tar.gz: ac8bc103360d5748382020bf796ee11adb1a14c6bb4147158ad15030582b4371
 SHA512:
-  metadata.gz: 124b7849fe7ac522b201bb18f1f9c57ce8776e64300c3c72460f882c77b7fde45e7b673b3d9aeb886dc8f0bab7dee40ab1c134e27d6d799baba27d16c94d9f1d
-  data.tar.gz: b60378421c9a11951be12290562fb02a97901c36f9abe78393178a1f2b1d225655654abf411310b2cd322a1d11b934dcb39c59cd7700aa009d7f2ad5218a21c5
+  metadata.gz: e2229c9330274945480d37d3547faa7c22b5079ebbc89f880f028859b6d906726ce69b1330302fd8e38b88532c73c0d2fffb1c2be97e14f562c2c847bb46cd94
+  data.tar.gz: c3239439910f6f2ea594c426f94889eb18be945ea2ae3a335915200e20e217b61b5c396a3639af42b6737810e75c969c45ee31f1563653dff681e0b6426078b3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rbcli (0.1.2)
+    rbcli (0.1.3)
       colorize (~> 0.8)
       deep_merge (~> 1.2)
 

data/README.md

@@ -10,8 +10,11 @@ Some of its key features include:
 
 * __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.
 
 ## Installation
 
@@ -46,9 +49,10 @@ Note that all options and parameters will have both a short and long version of
 
 ## Getting Started
 
-Creating a new skeleton command is as easy as running `rbcli init <filename>`. It will have three key items:
+Creating a new skeleton command is as easy as running `rbcli init <filename>`. It will have these key items:
 
 * The configuration
+* Storage subsystem configuration (optional)
 * A command declaration
 * The parse command
 
@@ -70,7 +74,7 @@ Rbcli::configurate do
 	config_defaults 'defaults.yml'                                         # (Optional, Multiple) Load a YAML file as part of the default config. This can be called multiple times, and the YAML files will be merged. User config is generated from these
 	config_default :myopt, description: 'Testing this', value: true        # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config
 
-option :name, 'Give me your name', type: :string, default: 'Foo', required: false, permitted: ['Jack', 'Jill']  # (Optional, Multiple) Add a global CLI parameter. Supported types are :string, :boolean, :integer, :float, :date, and :io. Can be called multiple times.
+	option :name, 'Give me your name', type: :string, default: 'Foo', required: false, permitted: ['Jack', 'Jill']  # (Optional, Multiple) Add a global CLI parameter. Supported types are :string, :boolean, :integer, :float, :date, and :io. Can be called multiple times.
 
 	default_action do |opts|                                               # (Optional) The default code to execute when no subcommand is given. If not present, the help is shown (same as -h)
 		puts "Hello, #{opts[:name]}."
@@ -84,6 +88,10 @@ option :name, 'Give me your name', type: :string, default: 'Foo', required: fals
 	post_hook do |opts|                                                    # (Optional) Allows providing a block of code that runs after any command
 		puts 'This is a post-command hook. It executes after the command.'
 	end
+
+	first_run halt_after_running: true do                                  # (Optional) Allows providing a block of code that executes the first time that the application is run on a given system. If `halt_after_running` is set to `true` then parsing will not continue after this code is executed. All subsequent runs will not execute this code.
+		puts "This is the first time the mytool command is run! Don't forget to generate a config file with the `-g` option before continuing."
+	end
 end
 ```
 
@@ -91,10 +99,10 @@ end
 
 For the `option` parameters that you want to create, the following types are supported:
 
-* :string
-* :boolean or :flag
-* :integer
-* :float
+* `:string`
+* `:boolean` or `:flag`
+* `:integer`
+* `:float`
 
 If a default value is not set, it will default to `nil`.
 
@@ -103,6 +111,16 @@ If you want to declare more than one option, you can call it multiple times. The
 Once parsed, options will be placed in a hash where they can be accessed via their names as shown above. You can see this demonstrated in the `default_action`, `pre_hook`, and `post_hook` blocks.
 
 
+### Storage Configuration (optional)
+
+```ruby
+Rbcli::Configurate.storage do
+	local_state '/var/mytool/localstate', force_creation: true, ignore_file_errors: false    # (Optional) Creates a hash that is automatically saved to a file locally for state persistance. It is accessible to all commands at  Rbcli.localstate[:yourkeyhere]
+end
+```
+
+This block configures different storage interfaces. For more details please see the [Storage Subsystems](#storage_subsystems) section below.
+
 ### Command Declaration
 
 Commands are added by subclassing `Rbcli::Command`. There are a few parameters to set for it, which get used by the different components of Rbcli.
@@ -203,6 +221,48 @@ logger:
   log_target: stderr           # STDOUT, STDERR, or a file path
 ```
 
+## <a name="storage_subsystems"></a>Storage Subsystems
+
+```ruby
+Rbcli::Configurate.storage do
+	local_state '/var/mytool/localstate', force_creation: true, ignore_file_errors: false    # (Optional) Creates a hash that is automatically saved to a file locally for state persistance. It is accessible to all commands at  Rbcli.localstate[:yourkeyhere]
+end
+```
+
+### Local State
+
+RBCli's local state storage gives you access to a hash that is automatically persisted to disk when changes are made.
+
+Once configured you can access it with a standard hash syntax:
+
+```ruby
+Rbcli.localstate[:yourkeyhere]
+```
+
+For performance reasons, the only methods available for use are `=` (assignment operator), `delete`, `each`, and `key?`. Also, the `clear` method has been added, which resets the data back to an empty hash. Keys are accessed via either symbols or strings indifferently.
+
+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.
+
+#### Configuration Parameters
+
+```ruby
+Rbcli::Configurate.storage do
+	local_state '/var/mytool/localstate', force_creation: true, ignore_file_errors: false    # (Optional) Creates a hash that is automatically saved to a file locally for state persistance. It is accessible to all commands at  Rbcli.localstate[:yourkeyhere]
+end
+```
+
+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)
+* `ignore_file_errors`
+	* 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 `true`, 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.
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/examples/mytool

@@ -8,7 +8,7 @@ require 'rbcli'
 # This block is where rbcli is configured.
 #########################
 
-Rbcli::configurate do
+Rbcli::Configurate.me do
 	scriptname __FILE__.split('/')[-1]                                     # (Required) This line identifies the tool's executable. You can change it if needed, but this should work for most cases.
 	version '0.1.0'                                                        # (Required) The version number
 	description 'This is my test CLI tool.'                                # (Requierd) A description that will appear when the user looks at the help with -h. This can be as long as needed.
@@ -34,6 +34,20 @@ Rbcli::configurate do
 	post_hook do |opts|                                                    # (Optional) Allows providing a block of code that runs after any command
 		puts 'This is a post-command hook. It executes after the command.'
 	end
+
+	first_run halt_after_running: true do                                  # (Optional) Allows providing a block of code that executes the first time that the application is run on a given system. If `halt_after_running` is set to `true` then parsing will not continue after this code is executed. All subsequent runs will not execute this code.
+		puts "This is the first time the mytool command is run! Don't forget to generate a config file with the `-g` option before continuing."
+	end
+end
+
+###############################
+## State Configuration Block ##
+###############################
+# The state-related componets
+# are configured here.
+###############################
+Rbcli::Configurate.storage do
+	local_state '/var/mytool/localstate', force_creation: true, ignore_file_errors: false    # (Optional) Creates a hash that is automatically saved to a file locally for state persistance. It is accessible to all commands at  Rbcli.localstate[:yourkeyhere]
 end
 
 #########################

data/lib/rbcli/configurate.rb

@@ -1,4 +1,4 @@
-module Rbcli
+module Rbcli::Configurate
 
 	@data = {
 			scriptname: nil,
@@ -9,10 +9,12 @@ module Rbcli
 			options: {},
 			default_action: nil,
 			pre_hook: nil,
-			post_hook: nil
+			post_hook: nil,
+			first_run: nil,
+			halt_after_first_run: false
 	}
 
-	def self.configurate &block
+	def self.me &block
 		@self_before_instance_eval = eval "self", block.binding
 		instance_eval &block
 	end
@@ -84,6 +86,11 @@ module Rbcli
 		@data[:post_hook] = block
 	end
 
+	def self.first_run halt_after_running: false, &block
+		@data[:halt_after_first_run] = halt_after_running
+		@data[:first_run] = block
+	end
+
 	##
 	# Data Retrieval
 	##
@@ -91,4 +98,10 @@ module Rbcli
 		@data
 	end
 
+end
+
+module Rbcli
+	def self.configuration
+		Rbcli::Configurate::configuration
+	end
 end

data/lib/rbcli/engine/parser.rb

@@ -55,18 +55,24 @@ Commands:
 
 	end
 
-	def self.opts
-		@cliopts
-	end
-
-	def self.cmd
-		@cmd
-	end
-
 end
 
 module Rbcli
 	def self.parse
-		Rbcli::Parser::parse
+		if Rbcli.configuration[:first_run]
+			if Rbcli.local_state
+				if Rbcli.local_state.rbclidata.key? :first_run
+					Rbcli::Parser::parse
+				else
+					Rbcli.configuration[:first_run].call
+					Rbcli.local_state.set_rbclidata :first_run, true
+					Rbcli::Parser::parse unless Rbcli.configuration[:halt_after_first_run]
+				end
+			else
+				raise StandardError.new "Error: Can not use `first_run` without also configuring `local_state`."
+			end
+		else
+			Rbcli::Parser::parse
+		end
 	end
 end

data/lib/rbcli/stateful_systems/configuratestorage.rb

@@ -0,0 +1,24 @@
+module Rbcli::Configurate
+	def self.storage &block
+		Rbcli::ConfigurateStorage.configure &block
+	end
+end
+
+
+module Rbcli::ConfigurateStorage
+	@data = {
+			localstate: nil
+	}
+
+	def self.configure &block
+		@self_before_instance_eval = eval "self", block.binding
+		instance_eval &block
+	end
+
+	##
+	# Data Retrieval
+	##
+	def self.data
+		@data
+	end
+end

data/lib/rbcli/stateful_systems/localstorage/localstate.rb

@@ -0,0 +1,124 @@
+require 'fileutils'
+require 'json'
+
+## Configuration Interface
+module Rbcli::ConfigurateStorage
+	@data[:localstate] = nil
+
+	def self.local_state path, force_creation: false, ignore_file_errors: false
+		@data[:localstate] = Rbcli::LocalState.new path, force_creation: force_creation, ignore_file_errors: ignore_file_errors
+	end
+end
+
+## User Interface
+module Rbcli
+	def self.local_state
+		Rbcli::ConfigurateStorage.data[:localstate]
+	end
+end
+
+
+## Local State Class
+class Rbcli::LocalState
+
+	def initialize path, force_creation: false, ignore_file_errors: false
+		@path = File.expand_path path
+		@ignore_file_errors = ignore_file_errors
+
+		base_data = {
+				data: {},
+				rbcli: {}
+		}
+
+		if File.exist? @path
+			load
+		elsif force_creation
+			create_file
+			@data = base_data
+			save
+		else
+			error "File #{@path} does not exist." unless @ignore_file_errors
+			@data = base_data
+		end
+	end
+
+	def []= key, value
+		@data[:data][key.to_sym] = value
+		save
+		@data[:data][key.to_sym]
+	end
+
+	def [] key
+		@data[:data][key.to_sym]
+	end
+
+	def delete key, &block
+		result = @data[:data].delete key.to_sym, block
+		save
+		result
+	end
+
+	def clear
+		@data[:data] = {}
+		save
+	end
+
+	def each &block
+		@data[:data].each &block
+		save
+	end
+
+	def key? key
+		@data[:data].key? key.to_sym
+	end
+
+	def to_h
+		@data[:data]
+	end
+
+	# For internal use
+
+	def rbclidata key = nil
+		return @data[:rbcli][key.to_sym] unless key.nil?
+		@data[:rbcli]
+	end
+
+	def set_rbclidata key, value
+		@data[:rbcli][key.to_sym] = value
+		save
+	end
+
+	private
+
+	def create_file
+		begin
+			FileUtils.mkdir_p File.dirname(@path)
+			FileUtils.touch @path
+		rescue Errno::EACCES => e
+			error "Can not create file #{@path}. Please make sure the directory is writeable." unless @ignore_file_errors
+		end
+	end
+
+	def load
+		begin
+			@data = JSON.parse(File.read(@path)).deep_symbolize!
+		rescue Errno::ENOENT, Errno::EACCES => e
+			error "Can not read from file #{@path}. Please make sure the file exists and is readable." unless @ignore_file_errors
+		end
+	end
+
+	def save
+		begin
+			File.write @path, JSON.dump(@data)
+		rescue Errno::ENOENT, Errno::EACCES => e
+			error "Can not write to file #{@path}. Please make sure the file exists and is writeable." unless @ignore_file_errors
+		end
+	end
+
+	def error text
+		raise Rbcli::LocalStateError.new "Error accessing local state: #{text}"
+	end
+
+end
+
+class Rbcli::LocalStateError < StandardError; end

data/lib/rbcli/version.rb

@@ -1,3 +1,3 @@
 module Rbcli
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/rbcli.rb

@@ -5,6 +5,12 @@ module Rbcli end # Empty module declaration required to declare submodules freel
 require "rbcli/version"
 
 require "rbcli/util"
+
+# STATE TOOLS
+require "rbcli/stateful_systems/configuratestorage"
+require "rbcli/stateful_systems/localstorage/localstate"
+# END STATE TOOLS
+
 require "rbcli/configurate"
 
 require "rbcli/engine/command"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rbcli
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Andrew Khoury
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-25 00:00:00.000000000 Z
+date: 2018-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -105,6 +105,8 @@ files:
 - lib/rbcli/configurate.rb
 - lib/rbcli/engine/command.rb
 - lib/rbcli/engine/parser.rb
+- lib/rbcli/stateful_systems/configuratestorage.rb
+- lib/rbcli/stateful_systems/localstorage/localstate.rb
 - lib/rbcli/util.rb
 - lib/rbcli/util/config.rb
 - lib/rbcli/util/hash_deep_symbolize.rb