cogy 0.0.3 → 0.1.0

data/lib/cogy.rb

@@ -1,44 +1,104 @@
 require "cogy/engine"
-require "cogy/handler"
 require "cogy/command"
+require "cogy/context"
 
 module Cogy
+  # The supported Cog bundle config version.
+  #
+  # @see http://docs.operable.io/docs/bundle-configs
   COG_BUNDLE_VERSION = 4
 
-  # Holds all the registered Commands. Not to be messed with.
-  mattr_accessor :commands
+  # Holds all the registered {Command} objects. Not to be messed with.
   @@commands = {}
+  mattr_accessor :commands
 
-  # Bundle config-related stuff
-  mattr_accessor :bundle_name
+  # The Cog bundle name.
+  #
+  # Used by {Cogy.bundle_config}.
   @@bundle_name = "cogy"
+  mattr_accessor :bundle_name
 
-  mattr_accessor :bundle_description
+  # The Cog bundle description.
+  #
+  # Used by {Cogy.bundle_config}.
   @@bundle_description = "Cogy-generated commands"
+  mattr_accessor :bundle_description
 
-  # Can be either a string or an object that responds to `#call` and returns
-  # a string.
+  # The Cog bundle version. Can be either a string or an object that responds
+  # to `#call` and returns a string. Used by {Cogy.bundle_config}.
+  #
+  # Used by {Cogy.bundle_config}.
   #
-  # Must be set explicitly
+  # @example
+  #   bundle_version = -> { rand(2).to_s }
+  @@bundle_version = "0.0.1"
   mattr_accessor :bundle_version
-  @@bundle_version = nil
 
-  # The path in the Cog Relay where the command executable is located.
+  # The path in the Cog Relay where the cogy executable
+  # (ie. https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy) is
+  # located.
   #
-  # Must be set explicitly.
+  # Used by {Cogy.bundle_config}.
+  @@executable_path = "/usr/bin/cogy"
   mattr_accessor :executable_path
-  @@executable_path = nil
 
-  # Paths where the files that define the commands will be searched in
-  mattr_accessor :command_load_paths
+  # Paths where the files that define the commands will be searched in the
+  # host application.
   @@command_load_paths = ["cogy"]
+  mattr_accessor :command_load_paths
 
-  def self.on(cmd_name, opts = {}, &blk)
-    cmd = Command.new(cmd_name, opts)
-    handler = Handler.new(blk)
-    cmd.register!(handler)
+  # Registers a command to Cogy. All the options passed are used solely for
+  # generating the bundle config (ie. {Cogy.bundle_config}). The passed block
+  # is the code that will get executed when the command is invoked.
+  #
+  # The last value of the block is what will get printed as the result of the
+  # command. It should be a string. If you want to return early in a point
+  # inside the block, use `next` instead of `return`.
+  #
+  # Inside the command block, there are the public attributes of {Context}
+  # available.
+  #
+  # @param cmd_name [String, Symbol] the name of the command. This is how the
+  #   command will be invoked in the chat.
+  # @param [Hash] opts the options to create the command with. All these options
+  #   are used solely for generating the bundle config for Cog, thus they map
+  #   directly to Cog's bundle config format.
+  #   See https://cog-book.operable.io/#_the_config_file for more information.
+  # @option opts [Array<Symbol, String>, Symbol, String] :args ([])
+  # @option opts [Hash{Symbol=>Hash}] :opts ({})
+  # @option opts [String] :desc required
+  # @option opts [String] :long_desc (nil)
+  # @option opts [String] :examples (nil)
+  # @option opts [Array] :rules (["allow"])
+  #
+  # @example
+  #   Cogy.on "calc",
+  #     args: [:a, :b],
+  #     opts: { op: { description: "The operation to perform", type: "string" } },
+  #     desc: "Perform an arithmetic operation between two numbers",
+  #     long_desc: "Operations supported are provided with their respective symbols
+  #                 passed as the --op option.",
+  #     examples: "Addition:       !calc --op + 1 2\n" \
+  #               "Subtraction:    !calc --op - 5 3\n" \
+  #               "Multiplication: !calc --op * 2 5\n" \
+  #               "Division:       !calc --op / 3 2\",
+  #     rules: ["allow"] do
+  #     result = args.map(&:to_i).inject(&opts["op"].to_sym)
+  #     "Hello #{user}, the answer is: #{result}"
+  #   end
+  #
+  # @return [void]
+  #
+  # @note If you want to return early in a point inside a command block,
+  #   `next` should be used instead of `return`, due to the way Proc objects
+  #   work in Ruby.
+  def self.on(cmd_name, opts = {}, &handler)
+    cmd = Command.new(cmd_name, handler, opts)
+    cmd.register!
   end
 
+  # Generates the bundle config
+  #
   # @return [Hash]
   def self.bundle_config
     version = if bundle_version.respond_to?(:call)
@@ -52,9 +112,10 @@ module Cogy
       "name" => bundle_name,
       "description" => bundle_description,
       "version" => version,
-      "commands" => {}
     }
 
+    config["commands"] = {} if commands.present?
+
     commands.each do |name, cmd|
       config["commands"][name] = {
         "executable" => executable_path,
@@ -82,7 +143,37 @@ module Cogy
     config
   end
 
+  # Configures Cogy according to the passed block.
+  #
+  # @example
+  #   Cogy.configure do |c|
+  #     c.bundle_name = "foo"
+  #   end
+  #
+  # @yield [self] yields {Cogy}
+  # @return [void]
   def self.configure
     yield self
   end
+
+  # Defines a user helper method that can be used throughout commands.
+  #
+  # @param [Symbol] name the name of the helper
+  # @param [Proc] blk the helper body
+  #
+  # @return [void]
+  #
+  # @note User helpers also have access to the default helpers like `user`, `env`
+  #   etc.
+  #
+  # @example
+  #   Cogy.configure do |c|
+  #     helper(:user) { User.find_by(slack_handle: handle) }
+  #
+  #     # a helper that accepts an argument
+  #     helper(:format) { |answer| answer.titleize }
+  #   end
+  def self.helper(name, &blk)
+    Context.class_eval { define_method(name, blk) }
+  end
 end

data/lib/generators/cogy/config_generator.rb

@@ -0,0 +1,15 @@
+module Cogy
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+
+      desc <<DESC
+Description:
+    Copies Cogy configuration file to your application's initializer directory.
+DESC
+      def copy_config_file
+        template 'cogy_config.rb', 'config/initializers/cogy.rb'
+      end
+    end
+  end
+end

data/lib/generators/cogy/install_generator.rb

@@ -0,0 +1,25 @@
+module Cogy
+  module Generators
+    class Install < Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+
+      desc <<DESC
+Description:
+    Mount the engine, create a sample command and add a configuration file
+DESC
+
+      def run_config_generator
+        generate "cogy:config"
+      end
+
+      def copy_sample_command_and_readme
+        template 'command_file.rb', 'cogy/general.rb'
+        template 'cogy_folder_readme.md', 'cogy/README.md'
+      end
+
+      def mount_engine
+        route 'mount Cogy::Engine, at: "/cogy"'
+      end
+    end
+  end
+end

data/lib/generators/cogy/templates/cogy_config.rb

@@ -0,0 +1,8 @@
+# See https://github.com/skroutz/cogy#configuration
+Cogy.configure do |config|
+  #config.bundle_name = "myapp"
+  #config.bundle_description = "Cog commands generated from myapp"
+  #config.bundle_version = "0.0.1"
+  #config.executable_path = "/usr/bin/cogy"
+  #config.command_load_paths = ["cogy"]
+end

data/lib/generators/cogy/templates/cogy_folder_readme.md

@@ -0,0 +1,4 @@
+Cogy commands live in this directory. If you want to change it, remember
+to update the `command_load_paths` configuration option accordingly.
+
+All Ruby files in here are loaded by Cogy when the application boots.

data/lib/generators/cogy/templates/command_file.rb

@@ -0,0 +1,8 @@
+# This is a sample file generated by Cogy. Feel free to remove it or customize
+# it as needed.
+#
+# See https://github.com/skroutz/cogy
+
+on "foo", desc: "Echoes a foo" do
+  "foo"
+end

data/test/dummy/cogy/foo.rb

@@ -0,0 +1,24 @@
+on "say_foo", desc: "Print a foo" do
+  "foo"
+end
+
+on "raiser", desc: "Raises an exception" do
+  raise "boom"
+end
+
+on "print_env", desc: "Test cogy env access" do
+  env["cogy_foo"]
+end
+
+on "foohelper", desc: "" do
+  foo
+end
+
+on "rails_url_helpers", desc: "" do
+  "#{baz_url(host: "dummy.com")} #{baz_path}"
+end
+
+on "titleize", desc: "" do
+  bar "this should be titleized"
+end
+

data/test/dummy/cogy/fully_fledged.rb

@@ -0,0 +1,14 @@
+on "calc",
+  args: [:a, :b],
+  opts: { op: { description: "The operation to perform", type: "string" } },
+  desc: "Perform an arithmetic operation between two numbers",
+  long_desc: "Operations supported are provided with their respective symbols
+              passed as the --op option.",
+  examples: "Addition:\n\n    !calc --op + 1 2\n\n"       \
+            "Subtraction:\n\n    !calc --op - 5 3\n\n"    \
+            "Multiplication:\n\n    !calc --op * 2 5\n\n" \
+            "Division:\n\n    !calc --op / 30 2\n\n",
+  rules: ["allow"] do
+  result = args.map(&:to_i).inject(&opts["op"].to_sym)
+  "Hello #{handle}, the answer is: #{result}"
+end

data/test/dummy/config/application.rb

@@ -1,6 +1,8 @@
 require File.expand_path('../boot', __FILE__)
 
-require 'rails/all'
+require "action_controller/railtie"
+require "action_view/railtie"
+require "rails/test_unit/railtie"
 
 Bundler.require(*Rails.groups)
 require "cogy"
@@ -18,9 +20,6 @@ module Dummy
     # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
     # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
     # config.i18n.default_locale = :de
-
-    # Do not swallow errors in after_commit/after_rollback callbacks.
-    config.active_record.raise_in_transactional_callbacks = true
   end
 end
 

data/test/dummy/config/environments/development.rb

@@ -14,22 +14,22 @@ Rails.application.configure do
   config.action_controller.perform_caching = false
 
   # Don't care if the mailer can't send.
-  config.action_mailer.raise_delivery_errors = false
+  # config.action_mailer.raise_delivery_errors = false
 
   # Print deprecation notices to the Rails logger.
   config.active_support.deprecation = :log
 
   # Raise an error on page load if there are pending migrations.
-  config.active_record.migration_error = :page_load
+  # config.active_record.migration_error = :page_load
 
   # Debug mode disables concatenation and preprocessing of assets.
   # This option may cause significant delays in view rendering with a large
   # number of complex assets.
-  config.assets.debug = true
+  # config.assets.debug = true
 
   # Asset digests allow you to set far-future HTTP expiration dates on all assets,
   # yet still be able to expire them through the digest params.
-  config.assets.digest = true
+  # config.assets.digest = true
 
   # Adds additional error checking when serving assets at runtime.
   # Checks for improperly declared sprockets dependencies.

data/test/dummy/config/environments/test.rb

@@ -29,7 +29,7 @@ Rails.application.configure do
   # Tell Action Mailer not to deliver emails to the real world.
   # The :test delivery method accumulates sent emails in the
   # ActionMailer::Base.deliveries array.
-  config.action_mailer.delivery_method = :test
+  # config.action_mailer.delivery_method = :test
 
   # Randomize the order test cases are executed.
   config.active_support.test_order = :random

data/test/dummy/config/initializers/cogy.rb

@@ -0,0 +1,10 @@
+Cogy.configure do |c|
+  c.bundle_name = "foo"
+  c.bundle_description = "The bundle you really need"
+  c.bundle_version = "0.0.1"
+  c.executable_path = "/usr/bin/foo"
+  c.command_load_paths = ["cogy"]
+
+  c.helper(:foo) { env["cogy_foo"] }
+  c.helper(:bar) { |text| text.titleize }
+end

data/test/dummy/config/routes.rb

@@ -1,4 +1,5 @@
 Rails.application.routes.draw do
-
   mount Cogy::Engine => "/cogy"
+
+  get "baz" => "cogy#cmd"
 end

data/test/dummy/log/development.log

@@ -0,0 +1,84 @@
+
+
+Started GET "/cogy/inventory" for 127.0.0.1 at 2016-11-10 10:43:03 +0200
+Processing by Cogy::CogyController#inventory as */*
+  Rendered text template (0.0ms)
+Completed 200 OK in 8ms (Views: 6.8ms)
+
+
+Started GET "/cogy/cmd/say_foo" for 127.0.0.1 at 2016-11-10 10:43:08 +0200
+
+ActionController::RoutingError (No route matches [GET] "/cogy/cmd/say_foo"):
+  actionpack (4.2.7.1) lib/action_dispatch/middleware/debug_exceptions.rb:21:in `call'
+  actionpack (4.2.7.1) lib/action_dispatch/middleware/show_exceptions.rb:30:in `call'
+  railties (4.2.7.1) lib/rails/rack/logger.rb:38:in `call_app'
+  railties (4.2.7.1) lib/rails/rack/logger.rb:20:in `block in call'
+  activesupport (4.2.7.1) lib/active_support/tagged_logging.rb:68:in `block in tagged'
+  activesupport (4.2.7.1) lib/active_support/tagged_logging.rb:26:in `tagged'
+  activesupport (4.2.7.1) lib/active_support/tagged_logging.rb:68:in `tagged'
+  railties (4.2.7.1) lib/rails/rack/logger.rb:20:in `call'
+  actionpack (4.2.7.1) lib/action_dispatch/middleware/request_id.rb:21:in `call'
+  rack (1.6.4) lib/rack/methodoverride.rb:22:in `call'
+  rack (1.6.4) lib/rack/runtime.rb:18:in `call'
+  activesupport (4.2.7.1) lib/active_support/cache/strategy/local_cache_middleware.rb:28:in `call'
+  rack (1.6.4) lib/rack/lock.rb:17:in `call'
+  actionpack (4.2.7.1) lib/action_dispatch/middleware/static.rb:120:in `call'
+  rack (1.6.4) lib/rack/sendfile.rb:113:in `call'
+  railties (4.2.7.1) lib/rails/engine.rb:518:in `call'
+  railties (4.2.7.1) lib/rails/application.rb:165:in `call'
+  rack (1.6.4) lib/rack/lock.rb:17:in `call'
+  rack (1.6.4) lib/rack/content_length.rb:15:in `call'
+  rack (1.6.4) lib/rack/handler/webrick.rb:88:in `service'
+  /Users/agis/.rubies/ruby-2.1.9/lib/ruby/2.1.0/webrick/httpserver.rb:138:in `service'
+  /Users/agis/.rubies/ruby-2.1.9/lib/ruby/2.1.0/webrick/httpserver.rb:94:in `run'
+  /Users/agis/.rubies/ruby-2.1.9/lib/ruby/2.1.0/webrick/server.rb:295:in `block in start_thread'
+
+
+  Rendered /Users/agis/.gem/ruby/2.1.9/gems/actionpack-4.2.7.1/lib/action_dispatch/middleware/templates/rescues/_trace.html.erb (1.1ms)
+  Rendered /Users/agis/.gem/ruby/2.1.9/gems/actionpack-4.2.7.1/lib/action_dispatch/middleware/templates/routes/_route.html.erb (0.5ms)
+  Rendered /Users/agis/.gem/ruby/2.1.9/gems/actionpack-4.2.7.1/lib/action_dispatch/middleware/templates/routes/_route.html.erb (0.1ms)
+  Rendered /Users/agis/.gem/ruby/2.1.9/gems/actionpack-4.2.7.1/lib/action_dispatch/middleware/templates/routes/_table.html.erb (9.7ms)
+  Rendered /Users/agis/.gem/ruby/2.1.9/gems/actionpack-4.2.7.1/lib/action_dispatch/middleware/templates/rescues/_request_and_response.html.erb (8.3ms)
+  Rendered /Users/agis/.gem/ruby/2.1.9/gems/actionpack-4.2.7.1/lib/action_dispatch/middleware/templates/rescues/routing_error.html.erb within rescues/layout (40.3ms)
+
+
+Started GET "/cogy/cmd/agis/say_foo" for 127.0.0.1 at 2016-11-10 10:43:25 +0200
+Processing by Cogy::CogyController#command as */*
+  Parameters: {"cmd"=>"agis", "user"=>"say_foo"}
+  Rendered /Users/agis/dev/cogy/app/views/cogy/error.text.erb (0.4ms)
+Completed 200 OK in 4ms (Views: 3.5ms)
+
+
+Started GET "/cogy/cmd/agifdsas/say_foo" for 127.0.0.1 at 2016-11-10 10:44:46 +0200
+Processing by Cogy::CogyController#command as */*
+  Parameters: {"cmd"=>"agifdsas", "user"=>"say_foo"}
+  Rendered /Users/agis/dev/cogy/app/views/cogy/error.text.erb (0.0ms)
+Completed 200 OK in 2ms (Views: 1.7ms)
+
+
+Started GET "/cogy/cmd/calc/agis?cog_opt_op=%2B" for 127.0.0.1 at 2016-11-10 13:14:05 +0200
+Processing by Cogy::CogyController#command as */*
+  Parameters: {"cog_opt_op"=>"+", "cmd"=>"calc", "user"=>"agis"}
+  Rendered text template (0.0ms)
+Completed 200 OK in 38528ms (Views: 11.3ms)
+
+
+Started GET "/cogy/cmd/calc/agis?cog_opt_op=%2B&cog_argv_0=1&cog_argv_1=2" for 127.0.0.1 at 2016-11-10 13:14:50 +0200
+Processing by Cogy::CogyController#command as */*
+  Parameters: {"cog_opt_op"=>"+", "cog_argv_0"=>"1", "cog_argv_1"=>"2", "cmd"=>"calc", "user"=>"agis"}
+  Rendered text template (0.0ms)
+Completed 200 OK in 12746ms (Views: 0.4ms)
+
+
+Started GET "/cogy/cmd/raiser/foo" for ::1 at 2016-11-10 15:26:14 +0200
+Processing by Cogy::CogyController#command as HTML
+  Parameters: {"cmd"=>"raiser", "user"=>"foo"}
+  Rendered /Users/agis/dev/cogy/app/views/cogy/error.text.erb (1.0ms)
+Completed 500 Internal Server Error in 8ms (Views: 7.5ms)
+
+
+Started GET "/cogy/cmd/raiser/foo" for ::1 at 2016-11-10 15:26:20 +0200
+Processing by Cogy::CogyController#command as HTML
+  Parameters: {"cmd"=>"raiser", "user"=>"foo"}
+  Rendered /Users/agis/dev/cogy/app/views/cogy/error.text.erb (0.1ms)
+Completed 500 Internal Server Error in 3ms (Views: 2.1ms)