lolcommits-sample_plugin 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34f1c14597a028bb747539c372b30e1bc8da36854d4cd2890753644ccab75047
-  data.tar.gz: 0c23c1efba939a7f17ce784b96ee21b603f82e494e33d204b5d11e3dabd0774f
+  metadata.gz: 9e4b2d304835ff46c9606931301a5fe8a1f9908602b524f09f36a032efa57bdb
+  data.tar.gz: eca9268aa5043e05b5d597f23d7e8246410d052417d2d777ff4c105036dd3254
 SHA512:
-  metadata.gz: 99903cf451eb212ca063ed151841c9ba7d29c308735c59b35f5e0f92c94d967389b50d0c0af46c3a4d79c1f9bcc7e0505348f992ee153a24d15ccb49763e1c83
-  data.tar.gz: 1a88c98c1426d59801a143922906d5004396ba340494846ee5e289cbca01e1b395cfeb218e7ce3caf7458cb02eaada65676227480e85bee0363909419f2ebbbb
+  metadata.gz: 60889f0a52a762046e7847c842eceab9bb518befc3148c859d615053d23604d16a01fc8d21cda74ba5a3670de62e57143e397f3b596d17515cfa461aa0138cd3
+  data.tar.gz: c7bf6610a544b54dd99ab627ebb1b9a7c19bea318e69d8367dffda38a094ea108a1142c5190b932db1a5ffc17939f84429820c1f170979051bed5988e3dd2781

data/README.md

@@ -10,12 +10,13 @@
 every time you git commit code, and archives a lolcat style image with it. Git
 blame has never been so much fun!
 
-Lolcommit plugins are automatically loaded before the capturing process starts.
-The flexible class design allows developers to add features by running code
-before or after snapshots are taken.
+Lolcommit plugins allow developers to add features by running code before or
+after snapshots are taken. Installed plugin gems are automatically loaded before
+the capturing process starts.
 
 This gem showcases an example plugin. It prints short messages to the screen
-before and after every lolcommit. Something like this;
+before and after every lolcommit. After configuring the plugin to be enabled,
+you'll see something like this for a capture:
 
     ✨  Say cheese 😁 !
     *** Preserving this moment in history.
@@ -23,90 +24,98 @@ before and after every lolcommit. Something like this;
     ✨  wow! 9e6303c is your best looking commit yet! 😘  💻
 
 Use this repo to jump-start development on your own plugin. It has tests, docs
-and integration with useful tools (Travis, CodeClimate, Rdoc etc.) See below for
-more information on how to get started.
+and hooks with useful tools; Travis, CodeClimate, Rdoc etc.
 
 ## Developing your own plugin
 
-First, there are some things your gem *must* do to be loaded and executed
-correctly. At the very least:
+First, there are some things your gem *must* do to be loaded and executed:
 
-* Name your gem with the `lolcommits-` prefix.
+* The gem name must have a `lolcommits-` prefix.
+* Require `lolcommits` in your `gemspec` file as a development dependency.
 * Include a class that inherits from `Lolcommits::Plugin::Base` (this will be
   the entry point to your plugin from the lolcommits gem).
 * This main plugin class must meet the requirements explained below.
-* Require `lolcommits` in your gem spec as a development dependency.
 
 ### Your Plugin Class
 
 You plugin class must have a namespace and path that matches your gem name and
-be in the `LOAD_PATH` (required) with the gem for example:
+be in the gem's `LOAD_PATH`.
 
-    # a gem named: lolcommits-zapier
-    # should have a plugin class inheriting from Base like so:
+    # for a gem named lolcommits-zapier you should have a plugin class:
     class Lolcommits::Plugin::Zapier < Lolcommits::Plugin::Base
       ...
     end
     # at lib/lolcommits/plugin/zapier.rb
     # required in a file at lib/lolcommits/zapier.rb
 
-    # or a gem named: lolcommits-super_awesome
-    # should have a plugin class
+    # or a gem named lolcommits-super_awesome should have a plugin class:
     class Lolcommits::Plugin::SuperAwesome < Lolcommits::Plugin::Base
       ...
     end
+    # at lib/lolcommits/plugin/super_awesome.rb
     # required in a file at lib/lolcommits/super_awesome.rb
 
-You **should** override the following methods in this class:
+The following methods can be overridden to execute code during the capture
+process:
 
-* `def self.name` - identifies the plugin to lolcommits and users, keep things
-  simple and choose a name that matches your gem name.
-* `def self.runner_order` - return the hooks this plugin should run at during
-  the capture process (`:pre_capture`, `:post_capture` and/or `:capture_ready`).
-* `def run_pre_capture`, `def run_post_capture` and/or `def run_capture_ready` -
-  override with your plugin's behaviour.
-
-Three hooks points are available during the lolcommits capture process.
-
-* `:pre_capture` - called before the camera starts capturing, at this point you
+* `run_pre_capture` - executes before the capture starts, at this point you
   could alter the commit message/sha text.
-* `:post_capture` - called immediately after the camera snaps the raw image (or
-  video for gif captures) use this hook to alter the image, other plugins may
-  hook here to modify the image too.
-  `:capture_ready` - called after all `:post_capture` plugins have ran, at this
-  point the capture should be ready for exporting or sharing.
+* `run_post_capture` - executes immediately after the camera captures, use this
+  hook to manipulate the image (e.g. resize, apply filters, annotate).
+* `run_capture_ready` - executes after all `run_post_capture` hooks have ran, at
+  this point we consider the capture to be ready for exporting or sharing.
 
 ### Plugin configuration
 
-The `Base` class initializer defines an `@options` instance var, with an array
-of setting names that the user can configure. By default, the only option is
-`enabled` and plugins *must* be configured as `enabled = true` to run.
+Available options can be defined in an Array (`@options` instance var) and/or a
+Hash (by overriding the `default_options` method).
+
+By default (on initialize), `@options` will be set to `[:enabled]`. This option
+is mandatory since `enabled?` checks `configuration[:enabled] == true` before
+any capture hooks can run.
 
-A plugin can be configured by the lolcommits gem with;
+Using a Hash to define default options allows you to:
 
-    lolcommits --config
-    # or
-    lolcommits --config -p plugin-name
+- fall back to default values (or nil) if the user enters nothing when prompted
+- define nested options (the user is prompted for each nested option key)
 
-Use the `configuration` method in your plugin class to read these options.
-Plugin methods you may want to override with custom configuration code include:
+`configure_option_hash` will iterate over all options prompting the user for
+input while building the configuration Hash.
 
-* `def enabled?` - usually checks `configuration['enabled']` to determine if the
-  plugin should run.
-* `def configure_options!` - prompts the user for configuration (based on the
-  `@options`) returns a hash that will be persisted.
-* `def configured?` - checks the persisted config hash is present.
-* `def valid_configuration?`- checks the persisted config hash has valid data.
+Lolcommits will save this Hash to a YAML file. During the capture process the
+configuration is loaded, parsed and available in the plugin class as
+`configuration`. Or if you want to fall back to default values, you should use
+the `config_option` method to dig into the Hash.
 
-If your plugin requires no configuration, you could override the `enabled?`
-method to always return `true`. Users could disable your plugin by uninstalling
-the gem.
+Alternatively you can override these methods to fully customise the
+configuration process.
+
+* `def configure_options!` - by default this prompts the user for option values
+  (based on option names in the `@options` array and/or `default_options`) and
+  returns a Hash that will be persisted.
+* `def enabled?` - by default checks if `configuration[:enabled] == true` to
+  determine if the plugin should run.
+* `def configured?` - checks the persisted config Hash is present.
+* `def valid_configuration?`- checks the persisted config Hash is valid.
 
 By default a plugin will only run it's capture hooks if:
 
 * `valid_configuration?` returns true
 * `enabled?` returns true
 
+A `parse_user_input` method is available to help parse strings from STDIN to
+Ruby objects (e.g. boolean, integer or nil).
+
+During plugin configuration, your plugin class will be initialized with the
+optional `config` argument (and no runner). This allows you to read the existing
+saved options during configuration. E.g. to show existing options back to the
+user, allowing you to ask if they want to keep or change an option if
+reconfiguring.
+
+__NOTE__: If your plugin does not require configuration and should be enabled by
+default (on gem install) you could override the `enabled?` method to always
+return `true`. Simply uninstalling the gem will disable the plugin.
+
 For more help, check out [the
 documentation](http://www.rubydoc.info/github/lolcommits/lolcommits-sample_plugin/Lolcommits/Plugin/SamplePlugin)
 for this plugin, or take a look at [other
@@ -115,43 +124,36 @@ for this plugin, or take a look at [other
 ### The Lolcommits 'runner'
 
 The only required argument for your plugin class initializer is a
-`Lolcommits::Runner` instance. By default, the base plugin initializer will set
-this in the `runner` instance var.
-
-Use these runner methods to access the commit, repo and configuration:
+[Lolcommits::Runner](https://github.com/mroth/lolcommits/blob/master/lib/lolcommits/runner.rb)
+instance. By default, the base plugin initializer will set this in the `runner`
+instance var for use in your plugin's code.
 
-* `runner.message` - the git commit message.
-* `runner.sha` - the git sha for the current commit.
+* `runner.message` - the commit message
+* `runner.sha` - the sha for the current commit
 * `runner.vcs_info` - a reference to the
   [Lolcommits::VCSInfo](https://github.com/mroth/lolcommits/blob/master/lib/lolcommits/vcs_info.rb)
-  instance.
+  instance
 * `runner.config` - a reference to the
   [Lolcommits::Configuration](https://github.com/mroth/lolcommits/blob/master/lib/lolcommits/configuration.rb)
-  instance.
+  instance
 
-After the capturing process has completed, (i.e. in the `run_post_capture` or
-`run_capture_ready` hooks) these methods will reveal the captured snapshot file.
+After the capturing process completes, (i.e. in `run_post_capture` or
+`run_capture_ready` hooks) use these methods for the captured snapshot file.
 
-* `runner.snapshot_loc` - the raw image file.
+* `runner.snapshot_loc` - the raw image file
 * `runner.main_image` - the processed image file, resized, with text overlay
-  applied (or any other effects from other plugins).
+  applied (or any other post_capture effects)
 
-During plugin configuration, your plugin class will be initialized with the
-optional `config` argument (and no runner). This allows you to read the existing
-saved options during configuration. E.g. to show the existing options back to
-the user.
-
-Take a look at the
+Take a look at
 [Lolcommits::Runner](https://github.com/mroth/lolcommits/blob/master/lib/lolcommits/runner.rb)
 for more details.
 
 ### Testing your plugin
 
-It's a good idea to include tests with your gem. To make this easier for you,
-the main lolcommits gem provides helpers to work with IO and Git repos in
-test.
+To make test setup easier, the lolcommits gem includes these helpers to work
+with command line IO and Git.
 
-    # add one or both of these to your plugin's test_helper file
+    # add one (or both) of these to your plugin's test_helper file
     require 'lolcommits/test_helpers/git_repo'
     require 'lolcommits/test_helpers/fake_io'
 
@@ -161,44 +163,30 @@ test.
 
 Use the following methods to manage a test repo:
 
-    setup_repo                 # create the test repo
-    commit_repo_with_message   # perform a git commit in the test repo
-    last_commit                # git commit info for the last commit in the test repo
-    teardown_repo              # destroy the test repo
-    in_repo(&block)            # run lolcommits within the test repo
+    setup_repo                # create the test repo
+    commit_repo_with_message  # perform a git commit in the test repo
+    last_commit               # commit info for the last test repo commit
+    teardown_repo             # destroy the test repo
+    in_repo(&block)           # run lolcommits within the test repo
 
-For submitting and capturing IO use the `fake_io_capture` method. E.g. to
-capture the output of the `configure_options` method, while sending the string
-input 'true' (followed by a carriage return) when prompted on STDIN:
+For STDIN and capturing IO use the `fake_io_capture` method.
 
+    # capture the output of the `configure_options` method, sending the
+    # string input 'true' (followed by a carriage return) to STDIN:
     output = fake_io_capture(inputs: %w(true)) do
       configured_plugin_options = plugin.configure_options!
     end
 
 For more examples take a look at the [tests in this
-repo](https://github.com/lolcommits/lolcommits-sample_plugin/blob/master/test/lolcommits/plugin/sample_plugin_test.rb)
-(MiniTest).
+repo](https://github.com/lolcommits/lolcommits-sample_plugin/blob/master/test/lolcommits/plugin/sample_plugin_test.rb).
 
 ### General advice
 
-Use this gem as a starting point, renaming files, classes and references. Or
-build a new plugin gem from scratch with:
-
-    bundle gem lolcommits-my-plugin
-
-For more examples, take a look at other published [lolcommit
+* Use this gem as a starting point, renaming files, classes etc.
+* For more examples, take a look at other published [lolcommit
 plugins](https://github.com/lolcommits).
-
-If you feel something is missing (or out of date) in this short guide. Please
-create a new
-[issue](https://github.com/lolcommits/lolcommits-sample_plugin/issues).
-
-## History
-
-Until recently, all plugins lived inside the main lolcommits gem. We are in the
-process of extracting them to individual gems, loaded with the new plugin
-manager. Ruby gem versioning will take care of managing dependencies and
-compatibility with the main gem.
+* If you feel something is missing (or out of date) in this guide. Post an
+  [issue](https://github.com/lolcommits/lolcommits-sample_plugin/issues).
 
 ---
 
@@ -219,9 +207,9 @@ lolcommits first. Then run the following:
 Next configure and enable this plugin with:
 
     $ lolcommits --config -p sample_plugin
-    # set enabled to `true`
+    # set enabled to `true` and configure other options as you like
 
-That's it! Every lolcommit now comes with it's own short (emoji themed) message!
+That's it! Every lolcommit now comes with it's own emoji themed commentary!
 
 ## Development
 
@@ -247,8 +235,8 @@ Generate docs for this gem with:
 ## Troubles?
 
 If you think something is broken or missing, please raise a new
-[issue](https://github.com/lolcommits/lolcommits-sample_plugin/issues). Take
-a moment to check it hasn't been raised in the past (and possibly closed).
+[issue](https://github.com/lolcommits/lolcommits-sample_plugin/issues). Take a
+moment to check it hasn't been raised in the past (and possibly closed).
 
 ## Contributing
 

data/lib/lolcommits/plugin/sample_plugin.rb

@@ -5,9 +5,10 @@ module Lolcommits
     class SamplePlugin < Base
 
       ##
-      # Plugin initializer
+      # Initializer
       #
-      # @param runner [Lolcommits::Runner] an instance of a lolcommits runner
+      # @param runner [Lolcommits::Runner] an instance of a Lolcommits runner
+      # @param name [String] name for this plugin, usually set from Gem name
       # @param config [Hash] plugin config hash (parsed from saved config YAML)
       #
       # The default superclass method sets @runner and @configuration instance
@@ -15,28 +16,11 @@ module Lolcommits
       #
       # Override this method to change the default configurable option names
       #
-      def initialize(runner: nil, config: nil)
+      def initialize(runner: nil, name: nil, config: nil)
         super
       end
 
       ##
-      # Returns position(s) of when this plugin should run during the capture
-      # process.
-      #
-      # Defines when the plugin will execute in the capture process. This must
-      # be defined, if the method returns nil, or [] the plugin will never run.
-      # Three hook positions exist, your plugin code can execute in one or more
-      # of these.
-      #
-      # @return [Array] the position(s) (:pre_capture, :post_capture,
-      # :capture_ready)
-      #
-      def self.runner_order
-        [:pre_capture, :post_capture, :capture_ready]
-      end
-
-      ##
-      #
       # Pre-capture hook, runs before lolcommits captures a snapshot.
       #
       # Override this method to execute plugin code before the lolcommit
@@ -49,7 +33,6 @@ module Lolcommits
       end
 
       ##
-      #
       # Post-capture hook, run after lolcommits captures a snapshot.
       #
       # Override this method to execute plugin code after the lolcommit snapshot
@@ -63,7 +46,6 @@ module Lolcommits
       end
 
       ##
-      #
       # Capture ready hook, runs after lolcommits captures a snapshot.
       #
       # Override this method to execute plugin code after the lolcommit snapshot
@@ -91,7 +73,7 @@ module Lolcommits
       #
       # Note: a `valid_configuration?` method also exists and is checked before
       # any plugin hooks execute. Use that to check individual config option
-      # values.
+      # values are valid.
       #
       # @return [Boolean] true/false indicating if plugin is enabled
       #
@@ -132,6 +114,12 @@ module Lolcommits
         super
       end
 
+      ##
+      # Returns a hash of default options to be presented to the user when
+      # configuring (with `configure_options!`.
+      #
+      # @return [Hash] with the default option names (keys) and values
+      #
       def default_options
         {
           ask_for_cheese: true,

data/lib/lolcommits/sample_plugin/version.rb

@@ -1,5 +1,5 @@
 module Lolcommits
   module SamplePlugin
-    VERSION = "0.0.3".freeze
+    VERSION = "0.1.0".freeze
   end
 end

data/lolcommits-plugin-sample.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 2.1"
 
-  spec.add_development_dependency "lolcommits", ">= 0.11.0"
+  spec.add_development_dependency "lolcommits", ">= 0.12.0"
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest"

data/test/lolcommits/plugin/sample_plugin_test.rb

@@ -5,12 +5,6 @@ describe Lolcommits::Plugin::SamplePlugin do
   include Lolcommits::TestHelpers::GitRepo
   include Lolcommits::TestHelpers::FakeIO
 
-  it 'should run on pre_capture and capture_ready' do
-    ::Lolcommits::Plugin::SamplePlugin.runner_order.must_equal [
-      :pre_capture, :post_capture, :capture_ready
-    ]
-  end
-
   describe 'with a runner' do
     def runner
       # a simple lolcommits runner with an empty configuration Hash
@@ -36,7 +30,7 @@ describe Lolcommits::Plugin::SamplePlugin do
     describe '#run_pre_capture' do
       before { commit_repo_with_message }
 
-      it 'should output a message to stdout' do
+      it 'outputs a message to stdout' do
         in_repo do
           Proc.new { plugin.run_pre_capture }.
             must_output "✨  Say cheese 😁 !\n"
@@ -46,11 +40,24 @@ describe Lolcommits::Plugin::SamplePlugin do
       after { teardown_repo }
     end
 
+    describe '#run_post_capture' do
+      before { commit_repo_with_message }
+
+      it 'outputs a message to stdout' do
+        plugin.configuration = valid_enabled_config
+        in_repo do
+          Proc.new { plugin.run_post_capture }.must_output "📸  📸  📸  📸  📸  Snap!\n"
+        end
+      end
+
+      after { teardown_repo }
+    end
+
     describe '#run_capture_ready' do
 
       before { commit_repo_with_message }
 
-      it 'should output a message to stdout' do
+      it 'outputs a message to stdout' do
         in_repo do
           Proc.new { plugin.run_capture_ready }.
             must_output "✨  wow! #{last_commit.sha[0..10]} is your best looking commit yet! 😘  💻\n"
@@ -61,18 +68,18 @@ describe Lolcommits::Plugin::SamplePlugin do
     end
 
     describe '#enabled?' do
-      it 'should be false by default' do
+      it 'returns be false by default' do
         plugin.enabled?.must_equal false
       end
 
-      it 'should true when configured' do
+      it 'returns true when configured' do
         plugin.configuration = valid_enabled_config
         plugin.enabled?.must_equal true
       end
     end
 
     describe 'configuration' do
-      it 'should allow plugin options to be configured' do
+      it 'allows plugin options to be configured' do
         configured_plugin_options = {}
 
         fake_io_capture(inputs: %w(true false true true 5)) do
@@ -83,11 +90,11 @@ describe Lolcommits::Plugin::SamplePlugin do
       end
 
       describe '#valid_configuration?' do
-        it 'should be false without config set' do
+        it 'returns false without config set' do
           plugin.valid_configuration?.must_equal(false)
         end
 
-        it 'should be true for a valid configuration' do
+        it 'returns true for a valid configuration' do
           plugin.configuration = valid_enabled_config
           plugin.valid_configuration?.must_equal true
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lolcommits-sample_plugin
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Matthew Hutchinson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-05 00:00:00.000000000 Z
+date: 2018-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lolcommits
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.12.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.12.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement