pug-bot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 130e63accf84439db61edd3da1f0745878a35bf5
+  data.tar.gz: e655cfbcd864bc561b128b0248798a1c8371b62c
+SHA512:
+  metadata.gz: 360bc1589c908f872b249c7e0388b87d50dcbdc0df9e791d84b431f7e3136e0589b37f4632212e3fecdfed8b3f1b8b51ae562729028f0b776f844aa191a5d26d
+  data.tar.gz: d6bfc6fef76beabd1e7ee82ac1df9e9368910138e6cd81e4d81ca415fa69be583050d56ad8ce305efa9027b8f2fc319bd2345392142e5d2beca8804a254b7741

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Alex Figueroa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# pug-bot
+
+An automation framework for repetitive dev tasks
+
+# Installation
+
+Add the following to your `Gemfile` and then run `bundle install`
+
+```
+gem 'pug-bot'
+```
+
+# Usage
+
+Before you can interact with pug-bot, you need to give it something to do via `Action`s
+
+## Action
+
+An `Action` is an abstract representation of a task. This could be anything from
+transforming RGB colors in the form: `66, 134, 244` to `4286f4` or pulling reports from
+an API to display stock prices.
+
+To define your own action, you need to create a new class which subclasses `Pug::Interfaces::Action` as follows
+
+```ruby
+# actions/hello_world_action.rb
+require 'pug'
+
+class HelloWorldAction < Pug::Interfaces::Action
+end
+```
+
+There are a few methods you **must** override specifically `name`, `requires_input?`, and `execute`.
+  - `name` helps to identify your `Action`
+  - `requires_input?` determines if input is required for your `Action`
+  - `execute` is what happens when the `Action` is ran
+
+```ruby
+# actions/hello_world_action.rb
+require 'pug'
+
+class HelloWorldAction < Pug::Interfaces::Action
+  def name
+    'Hello, World'
+  end
+
+  def requires_input?
+    true
+  end
+
+  def execute(input)
+    "Hello, #{input}"
+  end
+end
+```
+
+Once you've defined your action you just need a way to interact with it.
+There are two ways to interact with pug-bot: Telegram and Terminal.
+
+### Telegram Bot Setup
+
+To use Telegram we need to first setup a Telegram Bot. Thankfully, Telegram makes this a nice experience. Skip this and the next section if you want to just use Terminal.
+
+Assuming you already have Telegram installed, you'll need to perform the following steps:
+1. Start a new conversation with `@botfather` on Telegram
+2. Type `/newbot` and follow its steps to create a new Bot
+3. Grab the token for the HTTP API, this is your Telegram API token
+4. Start a new conversation with your newly created Bot
+5. Visit `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates` with `YOUR_BOT_TOKEN` replaced with the token from Step 3.
+6. Look for the `id` field in the `chat` body, this is your Telegram Chat ID
+
+## Telegram
+
+To setup Telegram, ensure you have an API token and Chat ID.
+Replace `YOUR_TELEGRAM_TOKEN` and `YOUR_TELEGRAM_CHAT_ID` with the token and chat_id for your Bot.
+
+```ruby
+require 'pug'
+require_relative './actions/hello_world_action'
+
+Pug.configure do |config|
+  config.type = Pug::Configuration::TELEGRAM
+  config.token = 'YOUR_TELEGRAM_TOKEN'
+  config.chat_id = 'YOUR_TELEGRAM_CHAT_ID'
+  config.actions = [HelloWorldAction.new]
+end
+
+Pug::Bot.run
+```
+
+## Terminal
+
+To setup Terminal, you just need to specify the type as Terminal
+
+```ruby
+require 'pug'
+require_relative './actions/hello_world_action'
+
+Pug.configure do |config|
+  config.type = Pug::Configuration::TERMINAL
+  config.actions = [HelloWorldAction.new]
+end
+
+Pug::Bot.run
+```
+
+# Interactions
+
+Every `Action` that pug-bot handles is enumerated. To call your command, you just need to type in the number that it corresponds to.
+For the `HelloWorldAction`, that would be `0` as shown below:
+
+## Telegram
+
+<img src="assets/telegram_example.png" width=60% height=60%>
+
+## Terminal
+
+<img src="assets/terminal_example.png" width=60% height=60%>
+
+# Hints
+
+Hints can be provided via entering: `help` or `list`.
+
+<img src="assets/terminal_hints.png" width=60% height=60%>
+
+
+# Motivation
+
+There were a lot of tasks that I found myself repeating during my dev work.
+I wanted to use something that was device/editor agnostic and could handle multiline arguments with no hassle.
+After playing around with the Telegram API, I hacked together a quick Bot to start this automation.
+This is the result of a few weeks of tinkering in hopes of making something more extensible.
+
+If this helps at least one other person work faster then I'll be content.
+Also, I come from an iOS background so forgive my not-so idomatic Ruby.

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true.
+
+require 'pug/version'
+require 'yard'
+
+desc 'Prepares and installs gem'
+task :prepare do
+  sh %{ gem build pug-bot.gemspec }
+  sh %{ gem install pug-bot-#{Pug::VERSION}.gem }
+end
+
+desc 'Run tests for the gem'
+task :test do
+  sh %{ rspec spec }
+end
+
+desc 'Run Rubocop check for the gem'
+task :cop do
+  sh %{ rubocop }
+end
+
+desc 'Verify everything is good before merge'
+task :flightcheck => [:cop, :test] do
+end
+
+desc 'Generate documentation'
+task :document do
+  sh %{ yardoc 'lib/**/*.rb' }
+end

data/lib/pug/action/controller.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Pug
+  module Action
+    # Controls the execution of an Action serially
+    class Controller
+      # @param actions [Array<Pug::Interfaces::Action>] The actions to manage
+      def initialize(actions)
+        @current_action = nil
+        @actions = actions || []
+      end
+
+      # Indicates if there are any actions to manage
+      # @return [Boolean] If there are any actions
+      def actions?
+        !@actions.empty?
+      end
+
+      # Indicates if there is a currently running Action
+      # @return [Boolean] if there is an action currently running
+      def running_action?
+        !@current_action.nil?
+      end
+
+      # Provides information about the Action's input requirements
+      # @return [Input] describing the requirements
+      def action_input
+        raise Strings.no_action_running unless running_action?
+        input_required = @current_action.requires_input?
+        Input.new(@current_action.name, input_required)
+      end
+
+      # Determines if an Action can start for a given index
+      # @param index [Integer] the index of the Action in actions
+      # @return [Boolean] indicating if an Action can be started at this index
+      # @note This will return false if there is a currently running action
+      def can_start_action?(index)
+        return false if index.negative? || index >= @actions.length
+        !running_action?
+      end
+
+      # Starts up the Action at the given index if possible
+      # @param index [Integer] the index of the Action in actions
+      def start_action(index)
+        return unless can_start_action?(index)
+
+        action = @actions[index]
+        @current_action = action
+      end
+
+      # Runs the Action prepared by #start_action with provided input
+      # @param input [String] the input to pass to the Action
+      # @return [Pug::Types::Result] indicating the execution result
+      def run_action(input)
+        return Results.no_action_running unless running_action?
+
+        requires_input = @current_action.requires_input?
+        result = @current_action.execute(requires_input ? input : nil)
+        output = Output.new(@current_action.name, result || '')
+        @current_action = nil
+        Types::Result.success(output)
+      end
+    end
+  end
+end

data/lib/pug/action/enumerator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pug
+  module Action
+    # Formats actions to an enumerated text representation
+    class Enumerator
+      # Enumerates Action names with an optional description
+      # @param actions [Array<Interfaces::Action>] Action names to enumerate
+      # @param show_description [Boolean] optional flag that adds descriptions
+      # @return [Array<String>] enumerated names with optional description
+      def names(actions, show_description = false)
+        return [] if actions.nil?
+        actions.each_with_index.map do |action, index|
+          if show_description && !action.description.to_s.empty?
+            "#{index}: #{action.name} # #{action.description}"
+          else
+            "#{index}: #{action.name}"
+          end
+        end
+      end
+
+      # Enumerates and groups Action names into a 2D array
+      # @param actions [Array<Interfaces::Action>] Action names to enumerate
+      # @param group_size [Integer] optional count indicating subarray size
+      # @return [Array<Array<String>>] enumerated and grouped names
+      # @note This does not support descriptions at the moment
+      def grouped_names(actions, group_size = 2)
+        return [] if group_size <= 0
+        names(actions).each_slice(group_size).to_a
+      end
+    end
+  end
+end

data/lib/pug/action/input.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Pug
+  module Action
+    # Defines input requirements for an Action
+    # @!attribute action_name
+    #   @return [String] the name of the Action
+    # @!attribute required
+    #   @return [Boolean] if Action requires input
+    class Input
+      attr_reader :action_name, :required
+
+      # @param action_name [String] The name of the Action
+      # @param required [Boolean] if Action requires input
+      def initialize(action_name, required)
+        @action_name = action_name
+        @required = required
+      end
+
+      # @return [Boolean] if Action requires input
+      def required?
+        @required
+      end
+    end
+  end
+end

data/lib/pug/action/output.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pug
+  module Action
+    # Defines output of running an Action
+    # @!attribute action_name
+    #   @return [String] the name of the Action
+    # @!attribute value
+    #   @return [String] the output of the Action
+    class Output
+      attr_reader :action_name, :value
+
+      # @param action_name [String] the name of the Action
+      # @param value [String] the output of the Action
+      def initialize(action_name, value)
+        @action_name = action_name
+        @value = value
+      end
+    end
+  end
+end

data/lib/pug/bot.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pug
+  # Coordinates the Client with the provided Actions
+  class Bot
+    # Convenience method used to setup the Bot
+    # with the user defined Configuration
+    # @return [Bot] A new instance of Bot.
+    # @see Configuration
+    def self.run
+      config = Pug.configuration
+      config.validate
+      client = Clients::Factory.client_for_config(config)
+      Bot.new(client, config.actions).start
+    end
+
+    # @param client [Interfaces::Client] used to interact with User
+    # @param actions [Array<Interfaces::Action>] available actions
+    def initialize(client, actions)
+      @client = client
+      @handler = MessageHandler.default(actions)
+    end
+
+    # Starts the handling all messages received via the Client
+    # @return [void]
+    def start
+      @client.listen do |message|
+        handle(message)
+      end
+    end
+
+    private
+
+    def handle(message)
+      result = @handler.handle(message)
+      output = output_from_result(result)
+      @client.send_message(output) unless output.to_s.empty?
+      return if result.type != Types::Result::SUCCESS
+      action_name = result.value.action_name
+      @client.send_message(Strings.finished_running(action_name))
+    end
+
+    def output_from_result(result)
+      if result.type == Types::Result::SUCCESS
+        result.value.value
+      elsif result.type == Types::Result::INFO
+        result.value
+      else
+        result.error
+      end
+    end
+  end
+end

data/lib/pug/clients/factory.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pug
+  module Clients
+    # Factory for building Clients based on a configuration
+    class Factory
+      # Builds a Client for the given config
+      # @param config [Configuration] parameters to build Client from
+      # @return [Interfaces::Client] The client from the config parameters
+      def self.client_for_config(config)
+        if !config.nil? && config.type == Configuration::TELEGRAM
+          enumerator = Action::Enumerator.new
+          markup = enumerator.grouped_names(config.actions)
+          client = TelegramClient.new(config.token, config.chat_id)
+          client.configure_keyboard(markup)
+          client
+        else
+          TerminalClient.new
+        end
+      end
+    end
+  end
+end

data/lib/pug/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Pug
+  # Defines parameters used to setup Pug
+  # @!attribute type
+  #   @return [Integer] the type of client to setup
+  #   @see Configuration::TERMINAL
+  #   @see Configuration::TELEGRAM
+  # @!attribute token
+  #   @return [String] the API token for Telegram
+  #   @note This is optional if type is TERMINAL
+  # @!attribute chat_id
+  #   @return [String] the chat_id for Telegram
+  #   @note This is optional if type is TERMINAL
+  # @!attribute actions
+  #   @return [Array<Interfaces::Action>] user defined actions
+  class Configuration
+    attr_accessor :type, :token, :chat_id, :actions
+
+    # @!group Client Types
+    TERMINAL = 0
+    TELEGRAM = 1
+    # @!endgroup
+
+    # @param type [Integer] type of client to setup
+    def initialize(type = TERMINAL)
+      @type = type
+    end
+
+    # Validates if attributes are correctly setup for Pug
+    # @raise RuntimeError if type is not a valid Client type
+    # @raise RuntimeError if Telegram client and no token & chat_id
+    # @raise RuntimeError if provided actions are nil
+    # @return [void]
+    def validate
+      valid_type = [TERMINAL, TELEGRAM].include?(type)
+      raise 'Invalid client type' unless valid_type
+      bad_config = @token.nil? || @chat_id.nil?
+      raise 'Invalid Telegram config' if @type == TELEGRAM && bad_config
+      raise 'No actions provided' if @actions.nil?
+    end
+  end
+end

data/lib/pug/interfaces/action.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Pug
+  module Interfaces
+    # Abstract interface representing an Action
+    class Action
+      # The human readable name for the Action
+      # @return [String] Action name
+      def name
+        raise NoMethodError
+      end
+
+      # Optional description for the action
+      # @return [String] Action description
+      def description
+        ''
+      end
+
+      # Indicates if the action requires an input
+      # @return [Boolean] if input is required
+      # @note Defaults to false
+      def requires_input?
+        false
+      end
+
+      # Entry point for Action with provided input if any
+      # @param input [String] The optional input for the Action
+      # @return [String] The output of running the Action
+      # @note This can return nil if there is no output
+      def execute(input) # rubocop:disable UnusedMethodArgument
+        raise NoMethodError
+      end
+    end
+  end
+end

data/lib/pug/interfaces/client.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pug
+  module Interfaces
+    # Abstract interface for a Client that Pug can talk to
+    # such as Telegram or Terminal
+    class Client
+      # Listens for and passes text via a block
+      # @yieldparam [String] text
+      def listen
+        raise NoMethodError
+      end
+
+      # Sends a message to the User via the Client
+      # @param message [String] the message to send
+      # @return [void]
+      def send_message(message) # rubocop:disable UnusedMethodArgument
+        raise NoMethodError
+      end
+    end
+  end
+end

data/lib/pug/keyword_handler.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Pug
+  # Responds to keywords that provide hints to the User
+  class KeywordHandler
+    # @!group Keywords
+    HELP = 'help'
+    LIST = 'list'
+    # @!endgroup
+
+    # @param actions [Array<Interfaces::Action>]
+    #   user provided actions
+    def initialize(actions)
+      @actions = actions
+      @keywords = Set[HELP, LIST]
+      @enumerator = Action::Enumerator.new
+    end
+
+    # Determines if a given text is a keyword
+    # @param text [String] text to test
+    # @return [Boolean] if text is a keyword
+    def keyword?(text)
+      @keywords.include?(text)
+    end
+
+    # Runs the command corresponding to text
+    # if it is a keyword
+    # @param text [String] text to run command for
+    # @return [String, nil] output of command or nil
+    def run_command_for_keyword(text)
+      return nil unless keyword?(text)
+      map_keyword_to_command(text)
+    end
+
+    private
+
+    def keywords_excluding_help
+      @keywords.to_a.reject { |keyword| keyword == HELP }
+    end
+
+    def map_keyword_to_command(keyword)
+      return help_response if keyword == HELP
+      return list_response if keyword == LIST
+      nil
+    end
+
+    def help_response
+      commands = keywords_excluding_help.join("\n")
+      Strings.help(commands)
+    end
+
+    def list_response
+      return Strings.no_actions if @actions.empty?
+      @enumerator.names(@actions, true).join("\n")
+    end
+  end
+end

data/lib/pug/message_handler.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Pug
+  # Coordinates between messages provided from Bot
+  # to actions via the Controller
+  class MessageHandler
+    # A convenice initializer for provided actions
+    # @param actions [Array<Interfaces::Action>] actions to coordinate
+    # @return [MessageHandler] A new instance of MessageHandler
+    def self.default(actions)
+      controller = Action::Controller.new(actions)
+      keyword_handler = KeywordHandler.new(actions)
+      MessageHandler.new(controller, NumberParser.new, keyword_handler)
+    end
+
+    # @param controller [Action::Controller] to control Action flow
+    # @param parser [NumberParser] to parse numeric text
+    # @param keyword_handler [KeywordHandler] to handle keywords
+    def initialize(controller, parser, keyword_handler)
+      @controller = controller
+      @parser = parser
+      @keyword_handler = keyword_handler
+    end
+
+    # Parses and coordinates the given message with the Controller
+    # @param message [String] message to handle
+    # @return [Types::Result] result of handling message
+    def handle(message)
+      return Results.missing_actions unless @controller.actions?
+      return Results.unknown_input if message.to_s.empty?
+      if @controller.running_action?
+        run_action_with_inputs(message)
+      elsif @keyword_handler.keyword?(message)
+        handle_keyword(message)
+      else
+        parse_message_for_index(message)
+      end
+    end
+
+    private
+
+    def can_start_action?(index)
+      @controller.can_start_action?(index)
+    end
+
+    def run_action_with_inputs(inputs = nil)
+      @controller.run_action(inputs || '')
+    end
+
+    def parse_message_for_index(message)
+      index = @parser.number_from_text(message)
+      return Results.unknown_input if index.nil?
+      return Results.invalid_index(index) unless can_start_action?(index)
+
+      @controller.start_action(index)
+      request_input_if_needed(message)
+    end
+
+    def request_input_if_needed(message)
+      input = @controller.action_input
+      if input.required?
+        Results.enter_inputs(input.action_name)
+      else
+        run_action_with_inputs(message)
+      end
+    rescue RuntimeError => ex
+      Types::Result.error(ex)
+    end
+
+    def handle_keyword(keyword)
+      response = @keyword_handler.run_command_for_keyword(keyword)
+      return Results.unknown_input if response.nil?
+      Types::Result.info(response)
+    end
+  end
+end

data/lib/pug/number_parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pug
+  # Parses numeric values from text
+  class NumberParser
+    # Indicates if a text starts with a number
+    # @param text [String] text to test
+    # @return [Boolean] if text starts with numeric text
+    def starts_with_numeric_text?(text)
+      text.to_i.positive? || text.strip.start_with?('0')
+    end
+
+    # Extracts number from text if it starts with
+    # a number
+    # @param text [String] text to extract number from
+    # @return [Integer, nil] number from text or nil
+    def number_from_text(text)
+      return nil unless starts_with_numeric_text?(text)
+      text.to_i
+    end
+  end
+end