elephrame 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 898b60769d6d1b3e6cb144017948786c46b39a7afcde1a73da8858f91d8ae425
-  data.tar.gz: fc7e8caf3197c2a4634b325c0535f8d9a05c01e17cc05bc0d13a2ffc35f0ffc5
+  metadata.gz: 9bacbf531fa6368eb2e401e3492192eb9ae230966edc62f3971f3566430b64f5
+  data.tar.gz: 8a09ce7796b7acd043f73195fd7511eda01cd8f5abf6de2aa081f17aec1fa46c
 SHA512:
-  metadata.gz: 70f4e752ecb1eb3dfc24304539c1c291b7b00a8052a4356858105fc305e83895306f5ae2ca449bccccdd64b26aeafbfe044b69fe78c34a02bb620e0d609fef37
-  data.tar.gz: e94ab3417ab4f45bca3b4e63ba62077932611191fa3eaab634c79fee7981575388dabb3f1b24974fe5a6c9ba5d95b4000c36bcf59aecfd16091ddf640b82f257
+  metadata.gz: f836c9f830ea5a24a52f8e708b96a6e26ecfff5c03182b0ccbf98787442f9ab4b9508bdd2ff9a340cd318723d265f97bd07506725048d2b2313bd86cd5451e99
+  data.tar.gz: 356c31e481d1d7892759fed57dbc41610364624e60725c23ff53f788a2245e66e5a6843f88ab4cf7295065dcfcf193a8f252167f57f9c89195482714543a548d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    elephrame (0.2.0)
+    elephrame (0.3.2)
       moostodon (~> 0.2.0)
       rufus-scheduler
 

data/README.md

@@ -1,8 +1,13 @@
 # Elephrame
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/elephrame`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Gem Version](https://badge.fury.io/rb/elephrame.svg)](https://badge.fury.io/rb/elephrame)
+[RubyDoc](https://www.rubydoc.info/github/theZacAttacks/elephrame/)
 
-TODO: Delete this and the text above, and describe your gem
+Elephant-Framework
+
+A framework that helps simplify the creation of bots for mastodon/pleroma
+
+Uses [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) in the backend
 
 ## Installation
 
@@ -20,20 +25,63 @@ Or install it yourself as:
 
     $ gem install elephrame
 
+## Quickstart
+
+bot that posts "i'm gay" every three hours:
+
+```ruby
+require 'elephrame'
+
+my_bot = Elephrame::Bots::Periodic.new '3h'
+
+my_bot.run { |bot|
+  bot.post("i'm gay")
+}
+```
+
+	$ INSTANCE="https://mastodon.social" TOKEN="your_access_token" ruby bot.rb
+
+Check the [examples](https://github.com/theZacAttacks/elephrame/tree/master/examples) directory for more example bots
+
+### Bot Types
+
+So far the framework support 4 bot types: Periodic, Interact, PeroidInteract, Reply
+
+- `Periodic` supports posting on a set schedule
+- `Interact` supports callbacks for each type of interaction (favorites, boosts, replies, follows)
+- `PeriodInteract` supports both of the above (I know, this isn't a good name)
+- `Reply` only supports replying to mentions
+
+The string passed to `Periodic` and `PeroidInteract` must be either a 'Duration' string or a 'Cron' string, as parsable by [fugit](https://github.com/floraison/fugit)
+
 ## Usage
 
-TODO: Write usage instructions here
+All the documentation is over at [RubyDoc](https://www.rubydoc.info/github/theZacAttacks/elephrame/)!
+
+Every place that accepts a block provides access to the bot object. This allows for easy access to some provided helper methods, as well as the actual mastodon access object.
+
+Exposed methods from bot object:
+
+- `client` this is the underlying mastodon rest client we use in the backend. use this to make custom calls to the api for which we don't provide a helper
+- `username` the name of the bot as fetched by verify_credentials
+- `strip_html` (defaults to true) if set, the framework will automatically strip all html symbols from the post content
+- `post(content, visibility: 'unlisted', spoiler: '', reply_id: '', media: [])` this provides an easy way to post statuses from inside code blocks
+- `reply(content)` a shorthand method to reply to the last mention (Note: doesn't automatically @ the other user/s)
+- `find_ancestor(id, depth = 10, stop_at = 1)` looks backwards through reply chains for the most recent post the bot made starting at post `id` until it hits `depth` number of posts, or finds `stop_at` number of it's own posts
+- `no_bot?(account_id)` returns true if user with `account_id` has some form of "#NoBot" in their bio 
+
+(See RubyDocs for source code documentation)
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. 
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/elephrame. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/theZacAttacks/elephrame. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## Code of Conduct
 
-Everyone interacting in the Elephrame project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/elephrame/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Elephrame project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/theZacAttacks/elephrame/blob/master/CODE_OF_CONDUCT.md).

data/examples/README.md

@@ -0,0 +1,5 @@
+# Elephrame Examples
+
+Follow the gem installation from the [main README](https://github.com/theZacAttacks/elephrame/tree/master/README.md) and then do the following, where `[file]` is one of the example ruby scripts
+
+	$ INSTANCE="https://mastodon.social" TOKEN="your_token_here" ruby [file] 

data/examples/interact.rb

@@ -3,8 +3,12 @@ require 'elephrame'
 interacter = Elephrame::Bots::Interact.new
 
 interacter.on_reply { |bot, post|
-  bot.post("@#{post.account.acct} Thanks for helping me test stuff :3",
-           reply_id: post.id, visibility: post.visibility)
+
+  #bot.post("@#{post.account.acct} Thanks for helping me test stuff :3",
+  #           reply_id: post.id, visibility: post.visibility)
+  
+  ## this can be simplified to one line
+  bot.reply("@#{post.account.acct} Thanks for helping me test stuff :3")
 }
 
 interacter.on_fave { |bot, notif|

data/examples/reply.rb

@@ -3,6 +3,5 @@ require 'elephrame'
 replier = Elephrame::Bots::Reply.new
 
 replier.run { |bot, mention|
-  bot.post("@#{mention.account.acct} hey!", reply_id: mention.id,
-           visibility: mention.visibility)
+  bot.reply("@#{mention.account.acct} hey!")
 }

data/lib/elephrame/bot.rb

@@ -1,19 +1,39 @@
 module Elephrame  
   module Bots
-    
+
+    ##
     # a superclass for other bots
-    # holds common functions and the rest api client
+    # holds common functions and variables
+    
     class BaseBot
-      attr_reader :client
+      attr_reader :client, :username
+      attr_accessor :strip_html
 
+      ##
+      # Sets up our REST client, gets and saves our username, sets default
+      # value for strip_html (true)
+      #
+      # @return [Elephrame::Bots::BaseBot]
+      
       def initialize
         @client = Mastodon::REST::Client.new(base_url: ENV['INSTANCE'],
                                              bearer_token: ENV['TOKEN'])
+        @username = @client.verify_credentials().acct
+        @strip_html = true
       end
+
+      ##
+      # Creates a post, uploading media if need be
+      #
+      # @param text [String] text to post
+      # @param visibility [String] visibility level
+      # @param spoiler [String] text to use as content warning
+      # @param reply_id [String] id of post to reply to
+      # @param media [Array<String>] array of file paths
       
       def post(text, visibility: 'unlisted', spoiler: '', reply_id: '', media: [])
         
-        if not media.empty?
+        unless media.empty?
           media.collect! {|m|
             @client.upload_media(m).id
           }
@@ -28,8 +48,43 @@ module Elephrame
         
         @client.create_status text, options
       end
-    end
 
+      
+      ##
+      # Finds most recent post by bot in the ancestors of a provided post
+      #
+      # @param id [String] post to base search off of
+      # @param depth [Integer] max number of posts to search
+      # @param stop_at [Integer] defines which ancestor to stop at
+      #
+      # @return [Mastodon::Status]
+      
+      def find_ancestor(id, depth = 10, stop_at = 1)
+        depth.each {
+          post = @client.status(id) unless id.nil?
+          id = post.id
+
+          stop_at -= 1 if post.account.acct == @username
+
+          return post if stop_at.zero?
+        }
+
+        return nil
+      end
+
+      ##
+      # Checks to see if a user has some form of "#NoBot" in their bio
+      # (so we can make make friendly bots easier!)
+      #
+      # @param account_id [String] id of account to check bio
+      #
+      # @return [Bool]
+
+      def no_bot? account_id
+        @client.account(account_id).note =~ /#?NoBot/i
+      end
+      
+    end
   end
 end
 

data/lib/elephrame/mix/bots.rb

@@ -4,11 +4,24 @@ require_relative '../bot'
 
 module Elephrame
   module Bots
-    # a bot that posts things on an interval
-    # but can also respond to interactions
+    
+    ##
+    # a bot that posts things on an interval but can also respond
+    # to interactions
+    #
+    # requires on_* variables to be set before running, otherwise the bot
+    # won't react to interactions
+    
     class PeriodInteract < BaseBot
       include Elephrame::Scheduler
       include Elephrame::AllInteractions
+
+      ##
+      # creates a new PeriodInteract bot
+      #
+      # @param intv [String] string specifying interval to post
+      #
+      # @return [Elephrame::Bots::PeriodInteract]
       
       def initialize intv
         super()
@@ -16,6 +29,11 @@ module Elephrame
         setup_scheduler intv
         setup_streaming
       end
+
+      ##
+      # Runs the bot. requires a block for periodic post logic, but relies on
+      # on_* functions for interaction logic. See Elephrame::AllInteractions
+      # for more details.
       
       def run
         run_scheduled &Proc.new

data/lib/elephrame/rest/bots.rb

@@ -3,10 +3,23 @@ require_relative '../bot'
 
 module Elephrame
   module Bots
+
+    ##
     # a bot that runs commands based off of
     # an interval or a cron string
+
     class Periodic < BaseBot
       include Elephrame::Scheduler
+
+      ##
+      # creates a new Periodic bot
+      #
+      # @param intv [String] string specifying interval to post.
+      #        ex: '3h' (every 3 hours) '20m' (every 20 minutes)
+      #       '00 12 * * *' (every day at 12:00)
+      #       '00 00 25 12 *' (midnight on christmas)
+      #
+      # @return [Elephrame::Bots::Periodic]
       
       def initialize intv
         super()

data/lib/elephrame/rest/rest.rb

@@ -2,7 +2,11 @@ module Elephrame
   module Scheduler
     attr :scheduler, :interval
     attr_reader :schedule
-    
+
+    ##
+    # Creates a new scheduler
+    #
+    # @param intv [String] string specifying interval to post
     def setup_scheduler intv
       require 'rufus-scheduler'
       
@@ -10,6 +14,9 @@ module Elephrame
       @interval = intv
       @scheduler = Rufus::Scheduler.new
     end
+
+    ##
+    # Runs the schedule. Requires a block to be passed to it.
     
     def run_scheduled
       @scheduler.repeat @interval do |j|

data/lib/elephrame/streaming/bots.rb

@@ -4,7 +4,12 @@ require_relative '../bot'
 module Elephrame
   module Bots
     
+    ##
     # a bot that can respond to all interactions
+    #
+    # Call on_fave, on_follow, on_reply, or on_boost with a block
+    # before calling run. Otherwise bot will do nothing.
+    
     class Interact < BaseBot
       include Elephrame::Streaming
       include Elephrame::AllInteractions
@@ -16,9 +21,13 @@ module Elephrame
       end
     end
 
+
+    ##
     # a bot that only replies when mentioned
+    #
     # run accepts a block, but also supports
-    # use of on_reply
+    # use of on_reply (See Elephrame::AllInteractions for more details)
+    
     class Reply < BaseBot
       include Elephrame::Streaming
       include Elephrame::Reply

data/lib/elephrame/streaming/streaming.rb

@@ -2,23 +2,69 @@ module Elephrame
   module Streaming
     attr :streamer
 
+    ##
+    # Creates the stream client
+    
     def setup_streaming
       @streamer = Mastodon::Streaming::Client.new(base_url: ENV['INSTANCE'],
                                                   bearer_token: ENV['TOKEN'])
     end
+
   end
-    
+
+  
   module Reply
-    attr :on_reply
+    attr :on_reply, :mention_data
 
+    ##
+    # Sets on_reply equal to +block+
+    
     def on_reply &block
       @on_reply = block
     end
 
+    ##
+    # Replies to the last mention the bot recieved using the mention's
+    # visibility and spoiler with +text+
+    #
+    # *DOES NOT AUTOMATICALLY INCLUDE @'S*
+    #
+    # @param text [String] text to post as a reply
+    
+    def reply(text)
+
+      # maybe also @ everyone from the mention? idk that seems like a bad idea tbh
+      post(text, @mention_data[:vis], @mention_data[:spoiler],
+           @mention_data[:id])
+    end
+
+    ##
+    # Stores select data about a post into a hash for later use
+    #
+    # @param mention [Mastodon::Status] the most recent mention the bot received
+
+    def store_mention_data(mention)
+      @mention_data = {
+        id: mention.id,
+        vis: mention.visibility,
+        spoiler: mention.spoiler_text,
+        mentions: mention.mentions
+      }
+    end
+
+    ##
+    # Starts a loop that checks for mentions from the authenticated user account
+    # running a supplied block or, if a block is not provided, on_reply
+    
     def run_reply
       @streamer.user do |update|
         next unless update.kind_of? Mastodon::Notification and update.type == 'mention'
 
+        # this makes it so .content calls strip instead 
+        update.status.class.module_eval { alias_method :content, :strip } if @strip_html
+
+        store_mention_data update.status
+        
         if block_given?
           yield(self, update.status)
         else
@@ -30,21 +76,35 @@ module Elephrame
     alias_method :run, :run_reply
   end
   
+
   module AllInteractions
     include Elephrame::Reply
     attr :on_fave, :on_boost, :on_follow
+
+    ##
+    # Sets on_fave equal to +block+
     
     def on_fave &block
       @on_fave = block
     end
+
+    ##
+    # Sets on_boost to +block+
     
     def on_boost &block
       @on_boost = block
     end
+
+    ##
+    # Sets on_follow to +block+
     
     def on_follow &block
       @on_follow = block
     end
+
+    ##
+    # Starts a loop that checks for any notifications for the authenticated
+    # user, running the appropriate stored proc when needed
     
     def run_interact
       @streamer.user do |update|
@@ -53,6 +113,10 @@ module Elephrame
           case update.type
               
           when 'mention'
+
+            # this makes it so .content calls strip instead 
+            update.status.class.module_eval { alias_method :content, :strip } if @strip_html
+            store_mention_data update.status
             @on_reply.call(self, update.status) unless @on_reply.nil?
             
           when 'reblog'

data/lib/elephrame/util/status.rb

@@ -0,0 +1,16 @@
+module Mastodon
+  class Status
+    alias_method :rcontent, :content
+    
+    ##
+    # Strips all html tags out of +content+
+    #
+    # @return [String]
+    
+    def strip
+      rcontent.gsub(/<\/p><p>/, "\n")
+        .gsub(/<("[^"]*"|'[^']*'|[^'">])*>/, '')
+    end
+  end
+end
+      

data/lib/elephrame/version.rb

@@ -1,3 +1,3 @@
 module Elephrame
-  VERSION = "0.2.0"
+  VERSION = "0.3.2"
 end

data/lib/elephrame.rb

@@ -1,5 +1,8 @@
 require 'moostodon'
-require_relative  'elephrame/version'
+require_relative 'elephrame/util/status'
+
+require_relative 'elephrame/version'
 require_relative 'elephrame/streaming/bots'
 require_relative 'elephrame/rest/bots'
 require_relative 'elephrame/mix/bots'
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elephrame
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Zac
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-29 00:00:00.000000000 Z
+date: 2018-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,6 +98,7 @@ files:
 - bin/console
 - bin/setup
 - elephrame.gemspec
+- examples/README.md
 - examples/combined.rb
 - examples/interact.rb
 - examples/periodic.rb
@@ -109,6 +110,7 @@ files:
 - lib/elephrame/rest/rest.rb
 - lib/elephrame/streaming/bots.rb
 - lib/elephrame/streaming/streaming.rb
+- lib/elephrame/util/status.rb
 - lib/elephrame/version.rb
 homepage: https://github.com/theZacAttacks/elephrame
 licenses: