imap-filter 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bd4508c320978c8e671d778d278acb636f4e53a4
+  data.tar.gz: 2d7b0f4d4002bb82aaaf369e8d4d79b4f7ad6dea
+SHA512:
+  metadata.gz: fdd58ff83f6b8ff66e942bb44f42eb11ebd68d508540fdc24ab25e3bd17658424edfe589cce2a55cb5978e9a43610512617e359f9f6d4858a067f827655f2e14
+  data.tar.gz: 7f7acc334eb004be3eb61c71dd1d9a7c4c06db4816246a8e9097fc18e3ffda81c0fc93d0489e7da8293834e6885299d1709796ca59ebd216a7ee7333030bcd52

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.semver

@@ -0,0 +1,5 @@
+---
+:major: 0
+:minor: 0
+:patch: 2
+:special: ''

data/Gemfile

@@ -0,0 +1,24 @@
+source "https://rubygems.org"
+
+gem "semver", "~> 1"
+gem "awesome_print",  "~> 1"
+gem "text-table",  "~> 1"
+gem "thor", "~> 0"
+gem "colorize", "~> 0"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2"
+  gem "yard", "~> 0"
+  gem "rdoc", "~> 3"
+  gem "bundler", "~> 1"
+  gem "juwelier", "~> 2"
+  gem "simplecov", "~> 0"
+  gem 'pry',            '~> 0'
+  gem 'pry-byebug',     '~> 3'
+  gem 'pry-doc',        '~> 0'
+  gem 'pry-remote',     '~> 0'
+  gem 'pry-rescue',     '~> 1'
+  gem 'pry-stack_explorer', '~> 0'
+end

data/Gemfile.lock

@@ -0,0 +1,122 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.4.0)
+    awesome_print (1.7.0)
+    binding_of_caller (0.7.2)
+      debug_inspector (>= 0.0.1)
+    builder (3.2.2)
+    byebug (9.0.5)
+    coderay (1.1.1)
+    colorize (0.8.1)
+    debug_inspector (0.0.2)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.1.3)
+    docile (1.1.5)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    git (1.3.0)
+    github_api (0.14.5)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      oauth2 (~> 1.0)
+    hashie (3.4.6)
+    highline (1.7.8)
+    interception (0.5)
+    json (1.8.3)
+    juwelier (2.1.2)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+      semver
+    jwt (1.5.6)
+    method_source (0.8.2)
+    mini_portile2 (2.1.0)
+    multi_json (1.12.1)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    nokogiri (1.6.8)
+      mini_portile2 (~> 2.1.0)
+      pkg-config (~> 1.1.7)
+    oauth2 (1.2.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    pkg-config (1.1.7)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pry-byebug (3.4.0)
+      byebug (~> 9.0)
+      pry (~> 0.10)
+    pry-doc (0.9.0)
+      pry (~> 0.9)
+      yard (~> 0.8)
+    pry-remote (0.1.8)
+      pry (~> 0.9)
+      slop (~> 3.0)
+    pry-rescue (1.4.4)
+      interception (>= 0.5)
+      pry
+    pry-stack_explorer (0.4.9.2)
+      binding_of_caller (>= 0.7)
+      pry (>= 0.9.11)
+    rack (2.0.1)
+    rake (11.3.0)
+    rdoc (3.12.2)
+      json (~> 1.4)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    semver (1.0.1)
+    simplecov (0.12.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    slop (3.6.0)
+    text-table (1.2.4)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    yard (0.9.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print (~> 1)
+  bundler (~> 1)
+  colorize (~> 0)
+  juwelier (~> 2)
+  pry (~> 0)
+  pry-byebug (~> 3)
+  pry-doc (~> 0)
+  pry-remote (~> 0)
+  pry-rescue (~> 1)
+  pry-stack_explorer (~> 0)
+  rdoc (~> 3)
+  rspec (~> 2)
+  semver (~> 1)
+  simplecov (~> 0)
+  text-table (~> 1)
+  thor (~> 0)
+  yard (~> 0)
+
+BUNDLED WITH
+   1.12.5

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2016 Fred Mitchell
+
+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.org

@@ -0,0 +1,321 @@
+* imap-filter
+  imap-filter is a Ruby implementation of an IMAP filtering application.
+  it can handle multiple IMAP accounts, and create IMAP folders automatically
+  where none exists.
+
+  The imap-filter DSL makes it easy to filter. You can also do "dry-runs"
+  to make sure what happens is what is expected.
+
+** Installation
+   This is a Ruby CLI application. If you are running Linux, most likely
+   you have Ruby already installed. If you are running MacOSX or Windows,
+   you may have to Install Ruby. We support Ruby 2.2 and later.
+
+   Simply, do:
+
+   #+begin_src bash
+   gem install imap-filter
+   #+end_src
+
+   or if in a Gemfile:
+
+   #+begin_src ruby
+   gem 'imap-filter'
+   #+end_src
+
+   By default, 
+
+** Documentation
+   I think that to make this documenation truly "complete", I would wind up writing 
+   more lines than in the imap-filter code itself!!! I will attempt to be as concise
+   as possible, and besides me writing a thick manual, no one wants to read such either.
+
+*** Tutorial and Examples
+    Let's go though the steps with just one Email account, then we'll add a second
+    account. Then you can look at the sample [[examples/default.imap][default.imap]]
+    file, and go beyond.
+
+    This tutorial assumes you have both a Gmail and a Yahoo account. Please feel free
+    to substitute with your own accounts.
+
+    First, install imap-filter as described in [[#installation][Installation]].
+
+    Next, create a default.imap file with Emacs, vi, nano, or whatever suits your fancy. Place
+    in it the following:
+
+    #+begin_src ruby
+    account :gmail do
+      login 'youruserid@gmail.com', 'yourpassword'
+      serv "imap.gmail.com"
+      auth :plain
+    end
+    #+end_src
+
+    And obviously adjust your userid and password to your own. Now let's try to run
+    your new script:
+
+    #+begin_src basn
+    imap-filter filter default.imap -t
+    #+end_src
+
+    Note that the '-t' is the test flag. It will simply test the connections
+    to your accounts and nothing more.
+
+    And nothing happens. Why not? Very simple. The directive of this file
+    must be activated. Edit your default.imap and add "activate :all" to the very 
+    end:
+
+    #+begin_src ruby
+    account :gmail do
+      login 'youruserid@gmail.com', 'yourpassword'
+      serv "imap.gmail.com"
+      auth :plain
+    end
+
+    activate :all
+    #+end_src
+
+    Now run the command again:
+    #+begin_src basn
+    imap-filter filter default.imap -t
+    #+end_src
+
+    Ah, something happens now! If all goes well, you should see the following:
+
+    #+begin_src bash
+    ====== Test Accounts
+      gmail...SUCCESS, delim /
+    #+end_src
+
+    The "delim" is the mailbox delimiter for your paricular vendor. Most places
+    use the forward slash (/). Some might use a period (.). This lets you know what
+    to use, so make particular note of that.
+
+    If something is wrong with your settings, you might see an error message similar to:
+
+    #+begin_src bash
+    ====== Test Accounts
+      gmail...FAILED: Lookup failed xxxxxxxxxxxxx
+    #+end_src
+    
+    And so check your login line to make sure your userID and password is correct.
+    For some vendors, the userID is your complete email address. For others, it might 
+    just be what procedes the '@'. Please check with your vendor to see what it is for
+    you. Usually, your vendor will have IMAP Client instructions on their website.
+
+    We use ssl connections by default, and it would be extremely insecure not to. But
+    you can turn off the ssl if need be. You can also change your port settings 
+    accordingly, if your vendor uses a non-standard port. For example,
+
+    #+begin_src ruby
+    account :gmail do
+      login 'youruserid@gmail.com', 'yourpassword'
+      serv "imap.gmail.com"
+      auth :plain
+      ssl true
+      port 993
+    end
+
+    activate :all
+    #+end_src
+
+    You may set ssl to "false" or make the port "2001". You have full
+    control over the settings. auth could be :login or :plain, so try
+    :login if :plain doesn't work.
+
+    There are more extensive authenication methods that IMAP can use, but
+    we do not support them at this time. If you have need for that support,
+    please let me know!!!!!
+
+    Now, let's assume you have your settings working. Now what? There are no 
+    filters specified, which is the entire point of this program!!! So let's
+    add one:
+
+    #+begin_src ruby
+    account :gmail do
+      login 'youruserid@gmail.com', 'yourpassword'
+      serv "imap.gmail.com"
+      auth :plain
+    end
+
+    filter :github, 'gmail:INBOX' do
+      search do
+        from 'github.com'
+        unseen
+      end
+  
+      cp 'gmail:test/Github'
+    end
+
+    activate :all
+    #+end_src
+
+    Note that the "actvate :all" is always the last entry. The filter
+    directive is fairly sophisticated, supporing most of what is possible
+    with IMAP search. We will document this more throughly at a later date.
+
+    In this filter example, we are receiving email notifications from github
+    which is cluttering up the Inbox. This filter will copy the "unseen", or
+    unread ones to the "test/Github" mailbox.
+
+    Notice in the string, we also specify the target account label. This is 
+    required, and will allow you to specify alternate accounts very easily.
+
+    The mailbox will automatically be created if it does not exist yet.
+
+    So now, let's run it with the following commands. First, we wish to do a
+    sanity check, so we will do a dry run:
+
+    #+begin_src bash
+    imap-filter filter default.imap -u -v1
+    #+end_src
+
+    The "-u" is the alias for "--dryrun" The "-v1" is the verbosity switch. While
+    doing your setups and debugging your scripts, you will want to use "-v1" or even
+    "-v2" verbosity settings. 
+    
+    If you actually have a match for the search critieria, you may see a list of messages
+    that matched the search scroll by. In my test case:
+
+    #+begin_src bash
+    ...
+    ##Subject: Re: [jekyll/jekyll] jekyll serve can't work (#5216)
+    ##Subject: [jruby/jruby] Fix Socket.tcp connect_timeout option (#4061)
+    ##Subject: Re: [ansible/ansible-modules-core] Add state=empty into file module (#902)
+    ##Subject: [ansible/ansible] Publish modules to Galaxy? (#17027)
+    ##Subject: [ansible/ansible-modules-core] Add support for password aging on Solaris (#4372)
+    ##Subject: Re: [jruby/jruby] Fix Socket.tcp connect_timeout option (#4061)
+    ##Subject: Re: [tmux/tmux] Keeps getting "lost server" in tmux 2.1 and 2.2. Installed using Homebrew (#498)
+    ##Subject: [jekyll/jekyll] Add link to Staticman (#5224)
+    ##Subject: Re: [ansible/ansible] Ansible facts override special variables (#16935)
+    ##Subject: Re: [elixir-lang/elixir] Introduce List.pop_at/3 (#5118)
+    ...
+    #+end_src
+
+    Which are all unread or "unseen" as per our specificaions. Now no modifications
+    were peformed due to the "-u" dry run switch. 
+
+    Now that we are feeling a bit more confident, let's run the same
+    command without the "-u" setting:
+
+    #+begin_src bash
+    imap-filter filter default.imap -v1
+    #+end_src
+
+    And now you will find that the filter actually executed what we wanted. A new
+    test/Gitub mailbox was created, and all the matching messages are now copied there.
+    Neat, huh?
+
+    Well, that's it for the tutorial. Please have a look at the [[examples/default.imap][example]].
+
+    There's a shorthand for the filters that may interest you for the 
+    majority of your cases. For example:
+
+    #+begin_src ruby
+    filter :slashdot, 'gmx:INBOX', from: 'slashdot' do
+      mark :seen
+      cp 'google:INBOX'
+      mv 'gmx:Slashdot'
+    end
+    #+end_src
+
+    Uses the short-hand of "from: 'slashdot'" when all you need
+    to do is search a single field, like in this case, the From
+    field.
+
+    Others are obvios: to:, cc:, subject: will all work here.
+
+*** Environment variables
+    | Variable        | Description                                                       |
+    |-----------------+-------------------------------------------------------------------|
+    | IMAPF_IMAP_FILE | pathname to the default .imap file. The default is ./default.imap |
+
+*** Accessing your Gmail
+    Google may automatically block this application by default.
+    Please visit the follow page to understand how to allow 
+    imap-filter to access your Gmail account.
+
+    https://support.google.com/accounts/answer/6010255
+
+*** Automatic blocks might happen while you are testing your Email accounts
+    Depending on the vendor, while you are setting up your scripts, you will
+    be doing many tests. Some vendors like Yahoo might block the app if it sees 
+    what it consideres to be "too much" activity. If you see this happen, wait about 
+    30 minutes before trying again. Should work in most cases.
+
+*** DSL
+    #+begin_src Ruby
+    account :redbird do
+      login "you@redbird.org", "password"
+      serv "imap.redbird.org"
+      ssl false
+      port 993
+    end
+
+    account :yahoo do
+      login "you@yahoo.com", "password"
+      serv "imap.yahoo.com"
+    end
+
+    account :google do
+      login "you@google.com", "password"
+      serv "imap.google.com"
+    end
+
+    filter :workmail, redbird.inbox, from: 'sally' do
+      cp yahoo.girlfriend
+      mv google.inbox
+    end
+
+    filter :maillist, google.inbox, from: 'github' do
+      mv google.groups.github
+    end
+
+    #+end_src
+
+*** Reference Documents
+    https://tools.ietf.org/html/rfc3501
+    https://www.ietf.org/rfc/rfc2822.txt
+
+** Release Notes and Known Issues
+*** Release Notes
+    | Version | Breif           | Description |
+    |---------+-----------------+-------------|
+    | v0.0.2  | Initial Release |             |
+*** Known Issues
+    |       Date | Description                                                    |
+    |------------+----------------------------------------------------------------|
+    | 2016-09-25 | Remote copy / moves of HTML-based email does not work cleanly. |
+    |            |                                                                |
+
+** Contributing to imap-filter
+
+   - Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.                                                                                                     |
+   - Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.                                                                                                                |
+   - Fork the project.                                                                                                                                                                                                  |
+   - Start a feature/bugfix branch.                                                                                                                                                                                     |
+   - Commit and push until you are happy with your contribution.                                                                                                                                                        |
+   - Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.                                                                                                          |
+   - Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it. |
+
+** Copyright
+
+   Copyright (c) 2016 Fred Mitchell. See LICENSE.txt for
+   further details.
+
+** Scratchpad
+   This section is my personal scratchpad. Should be of
+   no revelance to anyone else. Please ignore what's in
+   this section.
+
+   :Login:
+   imap = Net::IMAP.new('imap.gmail.com', ssl: true) 
+   imap.authenticate('PLAIN', ENV['GOOGLE_EMAIL'], ENV['GOOGLE_PASS'])
+   imap.select('Shelby')
+   seq = imap.search(['ALL'])
+   :END:
+
+   :FETCH:
+   acc.imap.fetch(1..2, 'BODY[TEXT]') -- the entire text, flags as well.
+   acc.imap.fetch(1..2, 'BODY[HEADER.FIELDS (SUBJECT)]')
+   :END: