swot 0.2.10 → 0.2.11

data/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to Swot
+
+#### Data Contributions
+
+* All of the school data is stored in a simple filesystem data structure under `lib/domains`.
+* Every directory name in here is a [TLD](http://en.wikipedia.org/wiki/Top-level_domain) (Top Level Domain) e.g. `edu`.
+* Every file in these directories is named after the school's [SLD](http://en.wikipedia.org/wiki/Second-level_domain) (Second Level Domain) e.g `stanford`.
+* The contents of that file are simply the school name e.g. `Stanford University`.
+* The [working example for Stanford University](https://github.com/leereilly/swot/blob/master/lib/domains/edu/stanford) :eyes:
+* Here's what the data structure looks like:
+
+```
+[-] lib
+    [-] domains
+        [-] ac.uk
+            [+] strath
+        [-] edu
+            [+] harvard
+            [+] stanford
+
+```
+
+##### Adding a School
+
+Let's say you want to add the [University of Strathclyde](http://www.strath.ac.uk/). We know the TLD is `ac.uk` and the SLD is `strath`. We'd simply create a file at `lib/domains/ac.uk/strath` containing the text `University of Strathcylde`. You can safely ignores subdomain like `www`, `cis`, whatever. You can see the actual file [here](https://github.com/leereilly/swot/blob/master/lib/domains/ac.uk/strath).
+
+#### Updating a School Name
+
+Change the file contents of the appropriate file.
+
+#### Deleting a School Name
+
+A simple `git rm` on the approriate file will do the trick.
+
+#### Code Contributions
+
+This was literally my first Ruby gem, so please keep that in mind when you're looking at the code :trollface:
+
+* Check out the latest [master](https://github.com/leereilly/swot/tree/master).
+* Take a look through the [open pull requests](https://github.com/leereilly/swot/issues) in case someone else has already contributed something similar.
+* Fork the project.
+* Start a topic branch of your own.
+* Commit and push away. Don't forget the tests!
+* Submit a pull request.
+* :boom: You've contributed to open source!
+
+```
+     ____________________________________________________
+    |.==================================================,|
+    ||  I WILL MERGE AND REVIEW PULL REQUESTS QUICKLY   ||
+    ||  I WILL MERGE AND REVIEW PULL REQUESTS QUICKLY   ||
+    ||  I WILL MERGE AND REVIEW PULL REQUESTS QUICKLY   ||
+    ||  I .----.ERG,                                    ||
+    ||   / ><   \  /                                    ||
+    ||  |        |/\                                    ||
+    ||   \______//\/                                    ||
+    ||   _(____)/ /                                     ||
+    ||__/ ,_ _  _/______________________________________||
+    '===\___\_) |========================================'
+         |______|
+         |  ||  |
+         |__||__|
+         (__)(__)
+```

data/LICENSE.txt

@@ -1,7 +1,21 @@
+The MIT License (MIT)
+
 Copyright (c) 2013 Lee Reilly
 
-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:
+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 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.
+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

@@ -1,68 +1,102 @@
-Swot allows you to identify whether a particular email address or domain
-is associated with an academic institution providing higher education in
-tertiary, quaternary or post-secondary education in any country in the
-world.
+# Swot :apple:
 
-# Why would you want to do that?
+If you have a product or service and offer **academic discounts**, there's a good chance there's some manual component to the approval process. Perhaps `.edu` email addresses are automatically approved because, for the most part at least, they're associated with American post-secondary educational institutions. Perhaps `.ac.uk` email addresses are automatically approved because they're guaranteed to belong to British universities and colleges. Unfortunately, not every country has an education-specific TLD (Top Level Domain) and plenty of schools use `.com` or `.net`.
 
-Student discounts baby. A growing number of companies offer discounts on their products/services to those in academia. It's not a hard problem to solve in America or the UK, but other countries don't have domain name restrictions.
+Swot is a community-driven or crowdsourced library for verifying that domain names and email addresses are tied to a legitimate university of college - more specifically, an academic institution providing higher education in tertiary, quaternary or any other kind of post-secondary education in any country in the world.
 
-## Pop quiz
+**Pop quiz:** Which of the following domain names should be eligible for an academic discount? `stanford.edu`, `america.edu`, `duep.edu`, `gla.ac.uk`, `wunizar.es`, `usask.ca`, `hil.no`, `unze.ba`, `fu-berlin.de`, `ecla.de`, `bvb.de`, `lsmu.com`. Answers at the foot of the page.
 
-How many of the following email addresses are associated with a university? Answers at the bottom.
+### Installation
 
-nigel@stanford.edu, bawbag@cs.strath.ac.uk, lee@wunizar.es, terrence@ubishops.ca, philip@usask.ca, hans@hil.no, mila@unze.ba
+Swot is a Ruby gem, so you'll need a little Ruby-fu to get it working. Simply
 
-# Usage
+`gem install swot`
+
+Or add this to your `Gemfile` before doing a `bundle install`:
+
+`gem 'swot'`
+
+### Usage
+
+#### Verify Email Addresses
 
-## Verify Email Addresses
 ```ruby
-    Swot::is_academic?('lreilly@stanford.edu')           # true
-    Swot::is_academic?('lreilly@slac.stanford.edu')      # true
-    Swot::is_academic?('lreilly@strath.ac.uk')           # true
-    Swot::is_academic?('lreilly@soft-eng.strath.ac.uk')  # true
-    Swot::is_academic?('lee@ugr.es')                     # true
-    Swot::is_academic?('lee@uottawa.ca')                 # true
-    Swot::is_academic?('lee@leerilly.net')               # false
-    Swot::is_academic?('lee@gmail.com')                  # false
-    Swot::is_academic?('lee@stanford.edu.com')           # false
-    Swot::is_academic?('lee@strath.ac.uk.com')           # false
+Swot::is_academic? 'lreilly@stanford.edu'           # true
+Swot::is_academic? 'lreilly@strath.ac.uk'           # true
+Swot::is_academic? 'lreilly@soft-eng.strath.ac.uk'  # true
+Swot::is_academic? 'pedro@ugr.es'                   # true
+Swot::is_academic? 'lee@uottawa.ca'                 # true
+Swot::is_academic? 'lee@leerilly.net'               # false
 ```
-## Verify Domain Names
+
+#### Verify Domain Names
+
 ```ruby
-    Swot::is_academic?('harvard.edu')                    # true
-    Swot::is_academic?('www.harvard.edu')                # true
-    Swot::is_academic?('http://www.harvard.edu')         # true
-    Swot::is_academic?('http://www.github.com')          # false
-    Swot::is_academic?('http://www.rangers.co.uk')       # false
+Swot::is_academic? 'harvard.edu'              # true
+Swot::is_academic? 'www.harvard.edu'          # true
+Swot::is_academic? 'http://www.harvard.edu'   # true
+Swot::is_academic? 'http://www.github.com'    # false
+Swot::is_academic? 'http://www.rangers.co.uk' # false
 ```
-# What is a swot?
 
-[UrbanDictionary will fill you in](http://www.urbandictionary.com/define.php?term=swot) ಠ_ಠ
+#### Find School Names
+
+```ruby
+Swot::school_name 'lreilly@cs.strath.ac.uk'
+# => "University of Strathclyde"
+
+Swot::school_name 'http://www.stanford.edu'
+# => "Stanford University"
+```
 
-# Contributing to Swot
+### Contributing to Swot
 
-* 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.
+Contributions welcome! Please see the [contribution guidelines](CONTRIBUTING.md) for details on how to add, update, or delete schools. Code contributions welcome too. Ports to different languages welcome too.
 
-# Known Issues / Bugs / "Features"
+**Thanks** to the following people for their contributions:
+@blutack, @captn3m0, @johndbritton, @johnotander, @pborreli, @rcurtis, @vikhyat,.
+
+**Special thanks** to @weppos for the [public_suffix](https://github.com/weppos/publicsuffix-ruby) gem :metal:
+
+### Known Issues
 
 * You can search by email and domain names only. You cannot search by IP.
-* You don't know if the email address belongs to a student, faculty, staff member, etc.
-* There may be a few false positives, missing institutions... maybe even a couple of typos.
+* You don't know if the email address belongs to a student, faculty, staff member, alumni, or a contractor.
+* There may be a few false positives, missing institutions... maybe even a couple of typos. Contributions welcome!
+
+**Please note:** just because someone has verified that they own `lreilly@stanford.edu` does *not* mean that they're a student. They could be faculty, staff, alumnni, or maybe even an external contractor. If you're suddenly getting a lot of traffic from websites like [FatWallet](http://www.fatwallet.com) or [SlickDeals](http://www.slickdeals.net), you might want to find out why. If you're suddenly getting a lot of requests from a particular school, you should look into that too. It may be good business, word of mouth, or someone may have found a loophole. Swot gives you a *high confidence level* - not a guarantee. I recommend putting some controls in place or at least monitor how it's doing from time to time.
+
+### What is a swot?
+
+According to [UrbanDictionary](http://www.urbandictionary.com/define.php?term=swot) :blue_book:
+
+> A word used by morons to insult a person of superior academic abilities.
+
+or
+
+> [verb] To Swot; Revision undertaken preceding an examination.
+
+or
 
-![](http://i.imgur.com/K8vsw.gif)
+> [anagram] Stupid Waste of Time
 
-# Copyright
+### Pop Quiz Answers
 
-Copyright (c) 2012 Lee Reilly. See LICENSE.txt for
-further details.
+Hopefully, you'll be surprised by some of this:
 
-# Pop Quiz Answers
+| Domain | Academic? | Comments |
+|--------|-----------|----------|
+|`stanford.edu`|:heavy_check_mark:|OK, this was an easy one so you could get at least *one* right|
+|`america.edu`|:heavy_multiplication_x:| Prior to October 29th 2001, anyone could register a `.edu` domain name ([details](http://en.wikipedia.org/wiki/.edu#Grandfathered_uses)) |
+|`duep.edu`|:heavy_check_mark:| Alfred Nobel University is a *Ukranian* University *in the Ukraine* i.e. not in the USA :us: |
+|`gla.ac.uk`|:heavy_check_mark:|Glasgow University in Scotland|
+|`unizar.es`|:heavy_check_mark:|The University of Zaragoza in Spain|
+|`usask.ca`|:heavy_check_mark:|The University of Saskatchewan in Canada|
+|`hil.no`|:heavy_check_mark:|Lillehammer University College in Norway|
+|`unze.ba`|:heavy_check_mark:|University of Zenica in Bosnia and Herzegovina|
+|`fu-berlin.de`|:heavy_check_mark:|Free University of Berlin in Germany|
+|`ecla.de`|:heavy_check_mark:|ECLA of Bard is a state recognized liberal arts university in Berlin, Germany |
+|`bvb.de`|:heavy_multiplication_x:|It's a soccer team from Germany|
+|`lsmu.com`|:heavy_check_mark:| Lugansk State Medical University in the Ukraine |
 
-All of 'em.
+If you verified this by visiting all of the websites, how long did it take you? Did you have fun? Imagine you had to do this 10 - 100 times every day. Now you know a little something about the inspiration for Swot. Swot can verify them all in a fraction of a second and remove a :poop: part of someone's job.

data/VERSION

@@ -1 +1 @@
-0.2.10
+0.2.11

data/lib/domains/ac.uk/manchester

@@ -0,0 +1 @@
+University of Manchester

data/lib/domains/edu/ggc

@@ -0,0 +1 @@
+Georgia Gwinnett College

data/lib/swot.rb

@@ -4,124 +4,124 @@ module Swot
   VERSION = "0.1.0"
 
   # These top-level domains are guaranteed to be academic institutions.
-  ACADEMIC_TLDS = [
-    'ac.ae',
-    'ac.at',
-    'ac.bd',
-    'ac.be',
-    'ac.cr',
-    'ac.cy',
-    'ac.fj',
-    'ac.id',
-    'ac.il',
-    'ac.ir',
-    'ac.jp',
-    'ac.ke',
-    'ac.kr',
-    'ac.ma',
-    'ac.mu',
-    'ac.mw',
-    'ac.mz',
-    'ac.nz',
-    'ac.pa',
-    'ac.pg',
-    'ac.rs',
-    'ac.ru',
-    'ac.rw',
-    'ac.th',
-    'ac.tz',
-    'ac.ug',
-    'ac.uk',
-    'ac.yu',
-    'ac.za',
-    'ac.zm',
-    'ac.zw',
-    'edu',
-    'edu.af',
-    'edu.al',
-    'edu.ar',
-    'edu.au',
-    'edu.az',
-    'edu.ba',
-    'edu.bb',
-    'edu.bd',
-    'edu.bh',
-    'edu.bi',
-    'edu.bn',
-    'edu.bo',
-    'edu.br',
-    'edu.bs',
-    'edu.bt',
-    'edu.bz',
-    'edu.co',
-    'edu.cu',
-    'edu.do',
-    'edu.dz',
-    'edu.ec',
-    'edu.ee',
-    'edu.eg',
-    'edu.er',
-    'edu.es',
-    'edu.et',
-    'edu.ge',
-    'edu.gh',
-    'edu.gr',
-    'edu.gt',
-    'edu.hk',
-    'edu.hn',
-    'edu.ht',
-    'edu.iq',
-    'edu.jm',
-    'edu.jo',
-    'edu.kg',
-    'edu.kh',
-    'edu.kn',
-    'edu.kw',
-    'edu.ky',
-    'edu.kz',
-    'edu.la',
-    'edu.lb',
-    'edu.lv',
-    'edu.ly',
-    'edu.mk',
-    'edu.mm',
-    'edu.mn',
-    'edu.mo',
-    'edu.mt',
-    'edu.mx',
-    'edu.my',
-    'edu.ni',
-    'edu.np',
-    'edu.om',
-    'edu.pa',
-    'edu.pe',
-    'edu.ph',
-    'edu.pk',
-    'edu.pl',
-    'edu.pr',
-    'edu.ps',
-    'edu.pt',
-    'edu.py',
-    'edu.qa',
-    'edu.rs',
-    'edu.ru',
-    'edu.sa',
-    'edu.sd',
-    'edu.sg',
-    'edu.sv',
-    'edu.sy',
-    'edu.tr',
-    'edu.tt',
-    'edu.tw',
-    'edu.ua',
-    'edu.uy',
-    'edu.ve',
-    'edu.vn',
-    'edu.ws',
-    'edu.ye',
-    'edu.zm',
-    'vic.edu.au'
-    ]
+  ACADEMIC_TLDS = {
+    'ac.ae' => 1,
+    'ac.at' => 1,
+    'ac.bd' => 1,
+    'ac.be' => 1,
+    'ac.cr' => 1,
+    'ac.cy' => 1,
+    'ac.fj' => 1,
+    'ac.id' => 1,
+    'ac.il' => 1,
+    'ac.ir' => 1,
+    'ac.jp' => 1,
+    'ac.ke' => 1,
+    'ac.kr' => 1,
+    'ac.ma' => 1,
+    'ac.mu' => 1,
+    'ac.mw' => 1,
+    'ac.mz' => 1,
+    'ac.nz' => 1,
+    'ac.pa' => 1,
+    'ac.pg' => 1,
+    'ac.rs' => 1,
+    'ac.ru' => 1,
+    'ac.rw' => 1,
+    'ac.th' => 1,
+    'ac.tz' => 1,
+    'ac.ug' => 1,
+    'ac.uk' => 1,
+    'ac.yu' => 1,
+    'ac.za' => 1,
+    'ac.zm' => 1,
+    'ac.zw' => 1,
+    'edu' => 1,
+    'edu.af' => 1,
+    'edu.al' => 1,
+    'edu.ar' => 1,
+    'edu.au' => 1,
+    'edu.az' => 1,
+    'edu.ba' => 1,
+    'edu.bb' => 1,
+    'edu.bd' => 1,
+    'edu.bh' => 1,
+    'edu.bi' => 1,
+    'edu.bn' => 1,
+    'edu.bo' => 1,
+    'edu.br' => 1,
+    'edu.bs' => 1,
+    'edu.bt' => 1,
+    'edu.bz' => 1,
+    'edu.co' => 1,
+    'edu.cu' => 1,
+    'edu.do' => 1,
+    'edu.dz' => 1,
+    'edu.ec' => 1,
+    'edu.ee' => 1,
+    'edu.eg' => 1,
+    'edu.er' => 1,
+    'edu.es' => 1,
+    'edu.et' => 1,
+    'edu.ge' => 1,
+    'edu.gh' => 1,
+    'edu.gr' => 1,
+    'edu.gt' => 1,
+    'edu.hk' => 1,
+    'edu.hn' => 1,
+    'edu.ht' => 1,
+    'edu.iq' => 1,
+    'edu.jm' => 1,
+    'edu.jo' => 1,
+    'edu.kg' => 1,
+    'edu.kh' => 1,
+    'edu.kn' => 1,
+    'edu.kw' => 1,
+    'edu.ky' => 1,
+    'edu.kz' => 1,
+    'edu.la' => 1,
+    'edu.lb' => 1,
+    'edu.lv' => 1,
+    'edu.ly' => 1,
+    'edu.mk' => 1,
+    'edu.mm' => 1,
+    'edu.mn' => 1,
+    'edu.mo' => 1,
+    'edu.mt' => 1,
+    'edu.mx' => 1,
+    'edu.my' => 1,
+    'edu.ni' => 1,
+    'edu.np' => 1,
+    'edu.om' => 1,
+    'edu.pa' => 1,
+    'edu.pe' => 1,
+    'edu.ph' => 1,
+    'edu.pk' => 1,
+    'edu.pl' => 1,
+    'edu.pr' => 1,
+    'edu.ps' => 1,
+    'edu.pt' => 1,
+    'edu.py' => 1,
+    'edu.qa' => 1,
+    'edu.rs' => 1,
+    'edu.ru' => 1,
+    'edu.sa' => 1,
+    'edu.sd' => 1,
+    'edu.sg' => 1,
+    'edu.sv' => 1,
+    'edu.sy' => 1,
+    'edu.tr' => 1,
+    'edu.tt' => 1,
+    'edu.tw' => 1,
+    'edu.ua' => 1,
+    'edu.uy' => 1,
+    'edu.ve' => 1,
+    'edu.vn' => 1,
+    'edu.ws' => 1,
+    'edu.ye' => 1,
+    'edu.zm' => 1,
+    'vic.edu.au' => 1,
+  }
 
   class << self
 
@@ -136,7 +136,7 @@ module Swot
         domain = get_domain(text)
         return false if domain.nil?
 
-        if ACADEMIC_TLDS.include?(domain.tld)
+        if ACADEMIC_TLDS[domain.tld]
           true
         elsif match_academic_domain?(domain)
           true
@@ -151,6 +151,7 @@ module Swot
         return false
       end
     end
+    alias_method :academic?, :is_academic?
 
     # Figure out the institution name based on the email address/domain.
     #
@@ -162,6 +163,7 @@ module Swot
       domain = PublicSuffix.parse(text)
       name_from_academic_domain(domain)
     end
+    alias_method :school_name, :get_institution_name
 
     # Figure out if a domain name is a know academic institution.
     #