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.6.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"]
@@cogy_endpoint =

The endpoint where the Cogy engine is reachable at. For example “www.example.com/cogy”

nil

Class Method Summary collapse

Class Method Details

.bundle_config ⇒ Hash

Generates the bundle config

Returns:

  • (Hash) —

    the bundle config



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

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

    if Cogy.cogy_endpoint
      config["commands"][name]["env_vars"] = {
        "COGY_BACKEND" => Cogy.cogy_endpoint
      }
    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:



157
158
159
 
# File 'lib/cogy.rb', line 157

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



178
179
180
 
# File 'lib/cogy.rb', line 178

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



91
92
93
94
 
# File 'lib/cogy.rb', line 91

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