Module: Cogy

Defined in:
lib/cogy.rb,
lib/cogy/engine.rb,
lib/cogy/command.rb,
lib/cogy/context.rb,
lib/cogy/version.rb,
app/controllers/cogy/cogy_controller.rb,
lib/generators/cogy/config_generator.rb,
lib/generators/cogy/install_generator.rb,
app/controllers/cogy/application_controller.rb

Defined Under Namespace

Modules: Generators Classes: ApplicationController, CogyController, Command, Context, Engine

Constant Summary collapse

COG_BUNDLE_VERSION =

The supported Cog bundle config version.

4
VERSION = 
"0.4.0".freeze
@@commands =

Holds all the registered Command objects. Not to be messed with.

{}
@@bundle =

Configuration related to the Cog bundle. Used in bundle_config.

See Also:

{
  # The bundle name
  name: "myapp",
   # The bundle description
  description: "Cog commands generated from Cogy",
   # The bundle version.
  #
  # Can also be an object that responds to `#call` and returns a string. For
  # example:
  #
  #   -> { rand(1).to_s }
  #
  version: "0.0.1",
   # The path in the Cog Relay where the cogy executable
  # (ie. https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy) is
  # located.
  cogy_executable: "/usr/bin/cogy"
}
@@templates =

The Cog templates. Used in bundle_config.

{}
@@command_load_paths =

Paths where the files that define the commands will be searched in the host application.

["cogy"]

Class Method Summary collapse

Class Method Details

.bundle_config ⇒ Hash

Generates the bundle config

Returns:

  • (Hash) —

    the bundle config



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/cogy.rb', line 94

def self.bundle_config
  version = if bundle[:version].respond_to?(:call)
              bundle[:version].call
            else
              bundle[:version]
            end

  config = {
    "cog_bundle_version" => COG_BUNDLE_VERSION,
    "name" => bundle[:name],
    "description" => bundle[:description],
    "version" => version
  }

  config["commands"] = {} if commands.present?

  commands.each do |name, cmd|
    config["commands"][name] = {
      "executable" => bundle[:cogy_executable],
      "description" => cmd.desc,
      "rules" => cmd.rules
    }

    if !cmd.args.empty?
      config["commands"][name]["arguments"] = cmd.formatted_args
    end

    if !cmd.opts.empty?
      config["commands"][name]["options"] = cmd.formatted_opts
    end

    if cmd.long_desc
      config["commands"][name]["long_description"] = cmd.long_desc
    end

    if cmd.examples
      config["commands"][name]["examples"] = cmd.examples
    end
  end

  config["templates"] = templates if !templates.empty?

  config
end

.configure {|self| ... } ⇒ void

This method returns an undefined value.

Configures Cogy according to the passed block.

Yields:

  • (self) —

    yields Cogy

See Also:



146
147
148
 
# File 'lib/cogy.rb', line 146

def self.configure
  yield self
end

.helper(name, &blk) ⇒ void

Note:

User helpers also have access to the default helpers like ‘user`, `env` etc.

This method returns an undefined value.

Defines a user helper method that can be used throughout commands.

Examples:

Cogy.configure do |c|
  helper(:user) { User.find_by(slack_handle: handle) }

  # a helper that accepts an argument
  helper(:format) { |answer| answer.titleize }
end

Parameters:

  • name (Symbol) —

    the name of the helper

  • blk (Proc) —

    the helper body



167
168
169
 
# File 'lib/cogy.rb', line 167

def self.helper(name, &blk)
  Context.class_eval { define_method(name, blk) }
end

.on(cmd_name, opts = {}, &handler) ⇒ Command

Note:

to return early inside a command block, ‘next` should be used instead of `return` due to the way Proc objects work in Ruby.

Initializes a new Command and registers it. All the options passed are used when generating the bundle config in bundle_config.

The given block is the code that will execute when the command is invoked. The return value of that block is what will get returned as a result back to Cog.

Inside the command block the public attributes of Context are available in addition to any user-defined handlers.

Examples:

Cogy.on "calc",
  args: [:a, :b],
  opts: { op: { description: "The operation to perform", type: "string", required: true } },
  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

Parameters:

  • cmd_name (String, Symbol) —

    the name of the command. This is how the command will be invoked in the chat.

  • opts (Hash) (defaults to: {}) —

    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 cog-book.operable.io/#_the_config_file for more information. For documentation on what’s supported right now see Cogy::Command#initialize.

Returns:

  • (Command) —

    the created command



86
87
88
89
 
# File 'lib/cogy.rb', line 86

def self.on(cmd_name, opts = {}, &handler)
  cmd = Command.new(cmd_name, handler, opts)
  cmd.register!
end