Module: Cogy

Defined in:
lib/cogy.rb,
lib/cogy/engine.rb,
lib/cogy/command.rb,
lib/cogy/context.rb,
lib/cogy/version.rb,
lib/cogy/invocation.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.

See Also:

4
VERSION = 
"0.1.0"
@@commands =

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

{}
@@bundle_name =

The Cog bundle name.

Used by bundle_config.

"cogy"
@@bundle_description =

The Cog bundle description.

Used by bundle_config.

"Cogy-generated commands"
@@bundle_version =

The Cog bundle version. Can be either a string or an object that responds to ‘#call` and returns a string. Used by bundle_config.

Used by bundle_config.

Examples:

bundle_version = -> { rand(2).to_s }
"0.0.1"
@@executable_path =

The path in the Cog Relay where the cogy executable (ie. github.com/skroutz/cogy-bundle/blob/master/commands/cogy) is located.

Used by bundle_config.

"/usr/bin/cogy"
@@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) 


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
138
139
140
141
142
143
144
 
# File 'lib/cogy.rb', line 103

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" => executable_path,
      "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
end

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

This method returns an undefined value.

Configures Cogy according to the passed block.

Examples:

Cogy.configure do |c|
  c.bundle_name = "foo"
end

Yields:

  • (self) —

    yields Cogy



155
156
157
 
# File 'lib/cogy.rb', line 155

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



176
177
178
 
# File 'lib/cogy.rb', line 176

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

.on(cmd_name, opts = {}, &handler) ⇒ 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.

This method returns an undefined value.

Registers a command to Cogy. All the options passed are used solely for generating the bundle config (ie. 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.

Examples:

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

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.

Options Hash (opts):

  • :args (Array<Symbol, String>, Symbol, String) — default: []
  • :opts (Hash{Symbol=>Hash}) — default: {}
  • :desc (String) —

    required

  • :long_desc (String) — default: nil
  • :examples (String) — default: nil
  • :rules (Array) — default: ["allow"] 


95
96
97
98
 
# File 'lib/cogy.rb', line 95

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