tlaw 0.0.2 → 0.1.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37f3ec860edbe2fac8ea3e85b3e0d2d75392ee15
-  data.tar.gz: b11a83253074b9dfb89c650bd46b155359f4b3f9
+  metadata.gz: '009cee34cd6c91e7fdb5a24914d1b8ffcb7c0639'
+  data.tar.gz: ab895dc56817673f6222f930a59fc525ff72fff3
 SHA512:
-  metadata.gz: e2ad59fcbebd0f0302dbda95365c6c46f15baf8b9333a0bd78c7720540f62785909d6fb3baa07581dd1a504a70527ec047713150c79239ffdcc7566bfa2ba2a1
-  data.tar.gz: e4cddec1d3e1074001a71dfd6a3858c7afdc57e11f5129ce35fd99d91d8635102b381c4f33b56edd53a974393c792bbbe1f357cd992b484877c0a84c39348039
+  metadata.gz: f5e188083216814e176d0c0161a424f9d124272411c8c15ca54b3ed3f7367d1f62e689c61ec80cc8feb22c2231178638dc1c7f066cac199dd383ab4861bbe754
+  data.tar.gz: 78c2c75ba92efde05fdb927198fe4a565da0a5ce53d94dd1142b2592f980edeaca11a9018fe5d2e6ef4bc759a9ee49ffd5f3257b5326ab1b44a3b146744e131f

data/.ruby-version

@@ -0,0 +1 @@
+2.3.0

data/CHANGELOG.md

@@ -1,11 +1,27 @@
 # The Last API Wrapper Changelog
 
-# 0.0.2 (2017-07-31)
+## 0.1.0.pre (2018-12-21)
+
+* `Namespace#children` is an `Array` now, with `Namespace#child_index` being a `Hash` (@marcandre);
+* DSL now can accept strings as a Namespace/Endpoint name (@marcandre);
+* Classes' `.inspect` fixed to match Ruby's conventions (@marcandre);
+* Improved object tree navigation (@marcandre):
+  * `APIPath#parent`, `APIPath.parent` (immediate parent class/object);
+  * `APIPath#parents`, `APIPath.parents` (parent classes/objects all the way up);
+  * `Namespace#traverse` (depth-first children tree enumeration).
+* Lots of refactoring (better call it "rewrite", honestly), internal structure was simplified and
+  decoupled, API and DSL was kept the same (I hope).
+  * I am really thankful to @marcandre and @joelvh for cleaning up job they've done. Sorry, guys,
+    eventually I've rewrote the thing completely :)
+* Added `shared_def`/`use_def` to reuse some common parts of definitions (thanks @marcandre for
+  discussion).
+
+## 0.0.2 (2017-07-31)
 
 * Codebase modernized and rubocopped;
 * Support for redirects;
 * Support for pattern-based (regexp) postprocessors.
 
-# 0.0.1 (2016-09-19)
+## 0.0.1 (2016-09-19)
 
 Initial release.

data/README.md

@@ -4,9 +4,9 @@
 [![Build Status](https://travis-ci.org/molybdenum-99/tlaw.svg?branch=master)](https://travis-ci.org/molybdenum-99/tlaw)
 [![Coverage Status](https://coveralls.io/repos/molybdenum-99/tlaw/badge.svg?branch=master)](https://coveralls.io/r/molybdenum-99/tlaw?branch=master)
 
-**TLAW** (pronounce it like "tea+love"... or whatever) is the last (and
-only) API wrapper framework for _get-only APIes_<sup>[*](#get-only-api)</sup>
-(think weather, search, economical indicators, geonames and so on).
+**TLAW** (pronounce it like "tea+love"... or whatever) is the last (and only)
+API wrapper framework you'll ever need for accessing _GET-only APIs_<sup>[*](#get-only-api)</sup>
+in a consistent way (think weather, search, economical indicators, geonames and so on).
 
 ## Table Of Contents
 
@@ -68,6 +68,9 @@ options:
 TLAW tries to close this gap: provide a base for _breath-easy_ API description
 which produces solid, fast and reliable wrappers.
 
+See also a [showcase blog post](http://zverok.github.io/blog/2017-07-31-giphy-tlaw.html) with on-the-fly
+API wrapper building for GIPHY.
+
 ## Usage
 
 ### URLs and params description
@@ -88,7 +91,7 @@ class Example < TLAW::API
     # Method is still e.bar, though.
 
     # Now, for params definition:
-    endpont :movie do
+    endpoint :movie do
       param :id
     end
     # Method call would be movie(id: '123')
@@ -299,7 +302,7 @@ post_process_items('foo') {
 
 # More realistic examples:
 post_process('meta.count', &:to_i)
-post_process('daily') {
+post_process_items('daily') {
   post_process('date', &Date.method(:parse))
 }
 post_process('auxiliary_value') { nil } # Nil's will be thrown away completely
@@ -311,9 +314,9 @@ See full post-processing features descriptions in
 #### All at once
 
 All described response processing steps are performed in this order:
+
 * parsing and initial flattening of JSON (or XML) hash;
-* applying post-processors (and flatten the response after _each_ of
-  them);
+* applying post-processors (and flatten the response after _each_ of them);
 * make `DataTable`s from arrays of hashes.
 
 ### Documentability

data/examples/demo_base.rb

@@ -1,7 +1,7 @@
-require 'pp'
+$:.unshift File.expand_path('../../lib', __FILE__)
 
-$:.unshift 'lib'
 require 'tlaw'
+require 'pp'
 
 begin
   require 'dotenv'

data/examples/experimental/README.md

@@ -0,0 +1,3 @@
+This folder contains examples of TLAW usage that may or may not be working.
+
+Most of them are semi-ready, some are outdated. The main target of it is having a lot of "real" cases to guide further TLAW design.

data/examples/experimental/afterthedeadline.rb

@@ -0,0 +1,22 @@
+require 'pp'
+
+$:.unshift 'lib'
+require 'tlaw'
+
+#http://docs.themoviedb.apiary.io/#reference/movies/movielatest
+
+class AfterTheDeadline < TLAW::API
+  define do
+    base 'http://service.afterthedeadline.com'
+
+    param :key, required: true
+
+    endpoint :document, '/checkDocument', xml: true do
+      param :data, keyword: false
+    end
+  end
+end
+
+atd = AfterTheDeadline.new(key: 'test-tlaw')
+
+pp atd.document("Isn't it cool and cute and awesme? Yepx it is.")['results.error'].to_a

data/examples/experimental/airvisual.rb

@@ -0,0 +1,14 @@
+require_relative '../demo_base'
+
+class AirVisual < TLAW::API
+  define do
+    base 'http://api.airvisual.com/v1'
+    param :key, required: true
+
+    endpoint :nearest, '/nearest?lat={latitude}&lon={longitude}' do
+    end
+  end
+end
+
+av = AirVisual.new(key: ENV['AIRVISUAL'])
+pp av.nearest(50.004444, 36.231389)

data/examples/experimental/apixu.rb

@@ -0,0 +1,32 @@
+require_relative '../demo_base'
+
+class APIXU < TLAW::API
+  define do
+    docs 'https://www.apixu.com/doc/'
+
+    base 'http://api.apixu.com/v1'
+
+    param :key, required: true
+    param :lang
+
+    namespace :current, '/current.json' do
+      endpoint :city, '?q={city}' do
+        param :city, :to_s, required: true
+      end
+    end
+
+    namespace :forecast, '/forecast.json' do
+      endpoint :city, '?q={city}' do
+        param :city, :to_s, required: true
+        param :days, :to_i
+        param :dt, Date, format: ->(dt) { dt.strftime('%Y-%m-%d') }
+      end
+    end
+  end
+end
+
+apixu = APIXU.new(key: ENV['APIXU'], lang: 'uk')
+pp apixu.current.city('Kharkiv')
+#res = apixu.forecast.city('Odesa', days: 10, dt: Date.parse('2017-07-03'))
+#pp res['forecast.forecastday']['day.mintemp_c']
+#pp res['forecast.forecastday']['day.maxtemp_c']

data/examples/experimental/bing_maps.rb

@@ -0,0 +1,18 @@
+require_relative '../demo_base'
+
+#http://docs.themoviedb.apiary.io/#reference/movies/movielatest
+
+class BingMaps < TLAW::API
+  define do
+    base 'http://dev.virtualearth.net/REST/v1'
+    param :key, required: true
+
+    namespace :locations, '/Locations' do
+      endpoint :query, '?q={q}'
+    end
+  end
+end
+
+maps = BingMaps.new(key: ENV['BING_MAPS'])
+
+pp maps.locations.query('Харків, Олексіівська 33а')['resourceSets'].first

data/examples/experimental/currencylayer.rb

@@ -0,0 +1,25 @@
+require_relative '../demo_base'
+
+class CurrencyLayer < TLAW::API
+  define do
+    base 'http://apilayer.net/api/'
+
+    param :access_key, required: true
+
+    endpoint :live do
+      param :currencies, Array
+    end
+
+    endpoint :historical do
+      param :date, :to_date, required: :true, keyword: false, format: ->(d) { d.strftime('%Y-%m-%d') }
+      param :currencies, Array
+
+      post_process 'date', &Date.method(:parse)
+      post_process 'timestamp', &Time.method(:at)
+    end
+  end
+end
+
+cur = CurrencyLayer.new(access_key: ENV['CURRENCYLAYER'])
+
+pp cur.historical(Date.parse('2016-01-01'), currencies: %w[UAH])

data/examples/experimental/earthquake.rb

@@ -0,0 +1,29 @@
+require 'pp'
+
+$:.unshift 'lib'
+require 'tlaw'
+
+class Earthquake < TLAW::API
+  define do
+    base 'http://earthquake.usgs.gov/fdsnws/event/1'
+
+    endpoint :count, '/count?format=geojson' do
+      param :starttime, Date, format: ->(d) { d.strftime('%Y-%m-%d') }
+      param :endtime, Date, format: ->(d) { d.strftime('%Y-%m-%d') }
+    end
+
+    endpoint :query, '/query?format=geojson' do
+      param :starttime, Date, format: ->(d) { d.strftime('%Y-%m-%d') }
+      param :endtime, Date, format: ->(d) { d.strftime('%Y-%m-%d') }
+      param :minmagnitude, :to_i
+    end
+  end
+end
+
+
+#/query?format=geojson&starttime=2001-01-01&endtime=2014-01-02
+
+e = Earthquake.new
+res = e.query(starttime: Date.parse('2000-01-01'), endtime: Date.parse('2017-01-02'), minmagnitude: 9)
+pp res['features'].count
+pp res['features'].first

data/examples/experimental/freegeoip.rb

@@ -0,0 +1,16 @@
+require 'pp'
+
+$:.unshift 'lib'
+require 'tlaw'
+
+class FreeGeoIP < TLAW::API
+  define do
+    base 'http://freegeoip.net/json/'
+
+    endpoint :here, ''
+    endpoint :at, '/{ip}'
+  end
+end
+
+fgi = FreeGeoIP.new
+pp fgi.here

data/examples/experimental/geonames.rb

@@ -0,0 +1,98 @@
+require_relative '../demo_base'
+require 'geo/coord'
+
+#http://www.geonames.org/export/web-services.html
+#http://www.geonames.org/export/credits.html
+#http://www.geonames.org/export/ws-overview.html
+
+class GeoNames < TLAW::API
+  define do
+    base 'http://api.geonames.org'
+
+    param :username, required: true
+    param :lang
+
+    ERROR_CODES = {
+      10 => 'Authorization Exception',
+      11 => 'record does not exist',
+      12 => 'other error',
+      13 => 'database timeout',
+      14 => 'invalid parameter',
+      15 => 'no result found',
+      16 => 'duplicate exception',
+      17 => 'postal code not found',
+      18 => 'daily limit of credits exceeded',
+      19 => 'hourly limit of credits exceeded',
+      20 => 'weekly limit of credits exceeded',
+      21 => 'invalid input',
+      22 => 'server overloaded exception',
+      23 => 'service not implemented',
+    }
+
+    post_process do |response|
+      if response['status.value']
+        fail "#{ERROR_CODES[response['status.value']]}: #{response['status.message']}"
+      end
+    end
+
+    namespace :search, path: '/searchJSON' do
+      endpoint :query, path: '?q={q}' do
+        param :q, required: true
+        param :country #TODO: country=FR&country=GP
+      end
+
+      endpoint :name, path: '?name={name}' do
+        param :name, required: true
+      end
+
+      endpoint :name_equals, path: '?name_equals={name}' do
+        param :name, required: true
+      end
+    end
+
+    namespace :postal_codes, path: '' do
+      endpoint :countries, path: '/postalCodeCountryInfoJSON'
+    end
+
+    namespace :near, path: '' do
+      param :lat, keyword: false
+      param :lng, keyword: false
+
+      endpoint :ocean, path: '/oceanJSON'
+      endpoint :country, path: '/countryCodeJSON'
+      endpoint :weather, path: '/findNearByWeatherJSON'
+      endpoint :extended, path: '/extendedFindNearby', xml: true do
+        post_process_replace { |res| res['geonames.geoname'] }
+      end
+    end
+
+    namespace :weather, path: '' do
+      endpoint :near, path: '/findNearByWeatherJSON?lat={lat}&lng={lng}'
+    end
+
+    endpoint :earthquakes, path: '/earthquakesJSON' do
+      param :north
+      param :south
+      param :east
+      param :west
+
+      post_process_items 'earthquakes' do
+        post_process 'datetime', &Time.method(:parse)
+        post_process { |h| h['coord'] = Geo::Coord.new(h['lat'], h['lng']) }
+      end
+    end
+  end
+end
+
+gn = GeoNames.new(username: ENV.fetch('GEONAMES'))
+
+#pp gn.search.name_equals('Kharkiv')['geonames'].to_a
+#pp gn.postal_codes.countries['geonames'].detect { |r| r['countryName'].include?('Thai') }
+#pp gn.near(50.004444, 36.231389).country
+#pp gn.near(50.004444, 36.231389).ocean
+pp gn.near(50.004444, 36.231389).extended.to_a
+#pp gn.near(50.004444, 36.231389).weather
+#pp gn.weather.near(50.004444, 36.231389)
+
+#pp gn.earthquakes(north: 44.1, south: -9.9, east: -22.4, west: 55.2)['earthquakes'].to_a
+# => to worldize!

data/examples/experimental/isfdb.rb

@@ -0,0 +1,17 @@
+require 'pp'
+
+$:.unshift 'lib'
+require 'tlaw'
+
+class ISFDB < TLAW::API
+  define do
+    base 'http://www.isfdb.org/cgi-bin/rest'
+
+    endpoint :isbn, '/getpub.cgi?{isbn}', xml: true
+  end
+end
+
+i = ISFDB.new
+
+#pp i.isbn('0399137378')["ISFDB.Publications.Publication"].last
+pp i.isbn('038533348X')["ISFDB.Publications.Publication"].to_a

data/examples/experimental/musicbrainz.rb

@@ -0,0 +1,27 @@
+require 'pp'
+
+$:.unshift 'lib'
+require 'tlaw'
+
+class MusicBrainz < TLAW::API
+  define do
+    base 'http://musicbrainz.org/ws/2'
+
+    endpoint :area, '/area/{id}?fmt=json'
+
+    namespace :artist do
+      endpoint :area, '?area={area_id}&fmt=json'
+      endpoint :get, '/{id}?fmt=json' do
+        param :inc, :to_a, format: ->(a) { a.join('+') }
+      end
+    end
+  end
+end
+
+mb = MusicBrainz.new
+
+#pp mb.area '37572420-4b2c-47e5-bf2b-536c9a50a362'
+#pp mb.artist.area('904768d0-61ca-3c40-93ac-93adc36fef4b')['artists'].first
+res = mb.artist.get('00496bc8-93bf-4284-a3ea-cfd97eb99b2f', inc: %w[recordings releases release-groups works])
+pp res['recordings'].first
+pp res['releases'].first

data/examples/experimental/nominatim.rb

@@ -0,0 +1,52 @@
+require 'pp'
+
+$:.unshift 'lib'
+require 'tlaw'
+
+class Nominatim < TLAW::API
+  define do
+    base 'http://nominatim.openstreetmap.org'
+
+    param :lang, field: 'accept%2Dlanguage'
+
+    namespace :search, '/search?format=json' do
+      endpoint :query, '' do
+        param :query, field: :q, keyword: false
+
+        param :details, field: :addressdetails, enum: {false => 0, true => 1}
+        param :geojson, field: :polygon_geojson, enum: {false => 0, true => 1}
+        param :tags, field: :extratags, enum: {false => 0, true => 1}
+        param :limit
+      end
+
+      endpoint :address, '' do
+        param :city
+        param :country
+        param :street
+        param :postalcode
+        param :details, field: :addressdetails, enum: {false => 0, true => 1}
+        param :geojson, field: :polygon_geojson, enum: {false => 0, true => 1}
+        param :tags, field: :extratags, enum: {false => 0, true => 1}
+      end
+    end
+
+    endpoint :geocode, '/reverse?format=json' do
+      param :lat, :to_f, keyword: false
+      param :lng, :to_f, field: :lon, keyword: false
+    end
+
+    endpoint :lookup, '/lookup?format=json&osm_ids={ids}' do
+      param :ids # , splat: true -- TODO
+    end
+  end
+end
+
+n = Nominatim.new(lang: 'en')
+
+#pp n.search.address(country: 'Ukraine', city: 'Kharkiv', street: '33a Oleksiivska', details: true, geojson: true, tags: true).first
+# pp n.search.query('New York, Times Square', details: true, tags: true, limit: 1).to_a
+#pp n.geocode(50.0403843, 36.203339684)
+#pp n.search.query('Pharmacy, Kharkiv', details: true, tags: true, limit: 100)['address.pharmacy'].compact
+#pp n.geocode(49.9808, 36.2527)
+# pp n.search.address(country: 'Thailand', city: 'Bangkok', details: true, tags: true).to_a
+pp n.search.query('Oleksiivska 33a, Kharkiv, Ukraine').to_a