tlaw 0.0.2 → 0.1.0.pre

data/examples/experimental/wunderground.rb

@@ -0,0 +1,66 @@
+module TLAW
+  module Examples
+    class WUnderground < TLAW::API
+      define do
+        base 'http://api.wunderground.com/api/{api_key}{/features}{/lang}/q'
+
+        param :api_key, required: true
+        param :lang, format: 'lang:#%s'.method(:%)
+
+        FEATURES = %i[
+          alerts
+          almanac
+          astronomy
+          conditions
+          currenthurricane
+          forecast
+          forecast10day
+          geolookup
+          hourly
+          hourly10day
+          rawtide
+          tide
+          webcams
+          yesterday
+        ].freeze
+
+        ALL_FEATURES = %i[
+          history
+          planner
+        ]
+
+        shared_def :common_params do
+          param :features, Array, format: ->(a) { a.join('/') }
+            #TODO: enum: FEATURES -- doesn't work with Array
+          param :pws, enum: {false => 0, true => 1}
+          param :bestfct, enum: {false => 0, true => 1}
+        end
+
+        post_process { |h|
+          h.key?('response.error.type') and fail h['response.error.type']
+        }
+
+        endpoint :city, '{/country}/{city}.json' do
+          param :city, required: true
+
+          use_def :common_params
+        end
+
+        endpoint :us_zipcode do
+        end
+
+        endpoint :location do
+        end
+
+        endpoint :airport do
+        end
+
+        endpoint :pws do
+        end
+
+        endpoint :geo_ip do
+        end
+      end
+    end
+  end
+end

data/examples/experimental/wunderground_demo.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+require_relative '../demo_base'
+require_relative 'wunderground'
+
+weather = TLAW::Examples::WUnderground.new(api_key: ENV['WUNDERGROUND'])
+
+pp weather.city('Kharkiv', 'Ukraine', features: %i[astronomy tide])

data/examples/forecast_io.rb

@@ -37,6 +37,22 @@ module TLAW
             Return summary properties in the desired language. (2-letters code)
           }
 
+        post_process 'currently.time', &Time.method(:at)
+
+        post_process_items('minutely.data') {
+          post_process 'time', &Time.method(:at)
+        }
+
+        post_process_items('hourly.data') {
+          post_process 'time', &Time.method(:at)
+        }
+
+        post_process_items('daily.data') {
+          post_process 'time', &Time.method(:at)
+          post_process 'sunriseTime', &Time.method(:at)
+          post_process 'sunsetTime', &Time.method(:at)
+        }
+
         endpoint :forecast, '/{lat},{lng}' do
           desc %Q{Forecast for the next week.}
 
@@ -85,22 +101,6 @@ module TLAW
               currently, minutely, hourly, daily, alerts, flags.
             }
         end
-
-        post_process 'currently.time', &Time.method(:at)
-
-        post_process_items('minutely.data') {
-          post_process 'time', &Time.method(:at)
-        }
-
-        post_process_items('hourly.data') {
-          post_process 'time', &Time.method(:at)
-        }
-
-        post_process_items('daily.data') {
-          post_process 'time', &Time.method(:at)
-          post_process 'sunriseTime', &Time.method(:at)
-          post_process 'sunsetTime', &Time.method(:at)
-        }
       end
     end
 

data/examples/giphy.rb

@@ -31,6 +31,10 @@ module TLAW
               desc 'Fetch GIPHY stickers (GIFs with transparent background).'
             end
 
+            post_process_items('data') do
+              post_process(/\.(size|mp4_size|webp_size|width|height|frames)/, &:to_i)
+            end
+
             endpoint :search do
               desc 'Search all GIFs by word or phrase.'
 
@@ -61,10 +65,6 @@ module TLAW
               param :tag
               param :rating, desc: 'Parental advisory rating'
             end
-
-            post_process_items('data') do
-              post_process(/\.(size|mp4_size|webp_size|width|height|frames)/, &:to_i)
-            end
           end
         end
 

data/examples/giphy_demo.rb

@@ -81,7 +81,7 @@ giphy.describe
 #  .stickers()
 #    Fetch GIPHY stickers (GIFs with transparent background).
 
-giphy.namespaces[:gifs].describe
+giphy.namespace(:gifs).describe
 # => .gifs()
 #  Fetch GIPHY GIFs.
 #

data/examples/open_weather_map.rb

@@ -23,6 +23,56 @@ module TLAW
         param :units, enum: %i[standard metric imperial], default: :standard,
           desc: 'Units for temperature and other values. Standard is Kelvin.'
 
+        # OpenWeatherMap reports most of logical errors with HTTP code
+        # 200 and responses like {cod: "500", message: "Error message"}
+        post_process { |h|
+          !h.key?('cod') || (200...400).cover?(h['cod'].to_i) or
+            fail "#{h['cod']}: #{h['message']}"
+        }
+
+        shared_def :lat_lng do
+          param :lat, :to_f, required: true, desc: 'Latitude'
+          param :lng, :to_f, required: true, desc: 'Longitude'
+        end
+
+        shared_def :cluster do
+          param :cluster, enum: {true => 'yes', false: 'no'},
+            default: true,
+            desc: 'Use server clustering of points'
+        end
+
+        WEATHER_POST_PROCESSOR = lambda do |*|
+          # Most of the time there is exactly one weather item...
+          # ...but sometimes there are two. So, flatterning them looks
+          # more reasonable than having DataTable of 1-2 rows.
+          post_process { |h|
+            h['weather2'] = h['weather'].last if h['weather'] && h['weather'].count > 1
+          }
+          post_process('weather', &:first)
+
+          post_process('dt', &Time.method(:at))
+          post_process('dt_txt') { nil } # TODO: we need cleaner way to say "remove this"
+          post_process('sys.sunrise', &Time.method(:at))
+          post_process('sys.sunset', &Time.method(:at))
+
+          # https://github.com/zverok/geo_coord promo here!
+          post_process { |e|
+            e['coord'] = Geo::Coord.new(e['coord.lat'], e['coord.lon']) if e['coord.lat'] && e['coord.lon']
+          }
+          post_process('coord.lat') { nil }
+          post_process('coord.lon') { nil }
+
+          # See http://openweathermap.org/weather-conditions#How-to-get-icon-URL
+          post_process('weather.icon', &'http://openweathermap.org/img/w/%s.png'.method(:%))
+        end
+
+        # For endpoints returning weather in one place
+        instance_eval(&WEATHER_POST_PROCESSOR)
+
+        # For endpoints returning list of weathers (forecast or several
+        # cities).
+        post_process_items('list', &WEATHER_POST_PROCESSOR)
+
         namespace :current, '/weather' do
           desc %Q{
             Allows to obtain current weather at one place, designated
@@ -64,8 +114,7 @@ module TLAW
 
             docs 'http://openweathermap.org/current#geo'
 
-            param :lat, :to_f, required: true, desc: 'Latitude'
-            param :lng, :to_f, required: true, desc: 'Longitude'
+            use_def :lat_lng
           end
 
           endpoint :zip, '?zip={zip}{,country_code}' do
@@ -112,7 +161,7 @@ module TLAW
             param :start_with, required: true, desc: 'Beginning of city name'
             param :country_code, desc: 'ISO 3166 2-letter country code'
 
-            param :cnt, :to_i, range: 1..50, default: 10,
+            param :cnt, :to_i, enum: 1..50, default: 10,
               desc: 'Max number of results to return'
 
             param :accurate, field: :type,
@@ -131,15 +180,12 @@ module TLAW
 
             docs 'http://openweathermap.org/current#cycle'
 
-            param :lat, :to_f, required: true, desc: 'Latitude'
-            param :lng, :to_f, required: true, desc: 'Longitude'
+            use_def :lat_lng
 
-            param :cnt, :to_i, range: 1..50, default: 10,
+            param :cnt, :to_i, enum: 1..50, default: 10,
               desc: 'Max number of results to return'
 
-            param :cluster, enum: {true => 'yes', false: 'no'},
-              default: true,
-              desc: 'Use server clustering of points'
+            use_def :cluster
           end
 
           # Real path is api/bbox/city - not inside /find, but logically
@@ -158,9 +204,7 @@ module TLAW
             param :zoom, :to_i, default: 10, keyword: true,
               desc: 'Map zoom level.'
 
-            param :cluster, enum: {true => 'yes', false: 'no'},
-              default: true,
-              desc: 'Use server clustering of points'
+            use_def :cluster
           end
         end
 
@@ -177,6 +221,13 @@ module TLAW
 
           docs 'http://openweathermap.org/forecast5'
 
+          post_process { |e|
+            e['city.coord'] = Geo::Coord.new(e['city.coord.lat'], e['city.coord.lon']) \
+              if e['city.coord.lat'] && e['city.coord.lon']
+          }
+          post_process('city.coord.lat') { nil }
+          post_process('city.coord.lon') { nil }
+
           endpoint :city, '?q={city}{,country_code}' do
             desc %Q{
               Weather forecast by city name (with optional country code
@@ -210,56 +261,9 @@ module TLAW
 
             docs 'http://openweathermap.org/forecast5#geo5'
 
-            param :lat, :to_f, required: true, desc: 'Latitude'
-            param :lng, :to_f, required: true, desc: 'Longitude'
+            use_def :lat_lng
           end
-
-          post_process { |e|
-            e['city.coord'] = Geo::Coord.new(e['city.coord.lat'], e['city.coord.lon']) \
-              if e['city.coord.lat'] && e['city.coord.lon']
-          }
-          post_process('city.coord.lat') { nil }
-          post_process('city.coord.lon') { nil }
         end
-
-        # OpenWeatherMap reports most of logical errors with HTTP code
-        # 200 and responses like {cod: "500", message: "Error message"}
-        post_process { |h|
-          !h.key?('cod') || (200..400).cover?(h['cod'].to_i) or
-            fail "#{h['cod']}: #{h['message']}"
-        }
-
-        WEATHER_POST_PROCESSOR = lambda do |*|
-          # Most of the time there is exactly one weather item...
-          # ...but sometimes there are two. So, flatterning them looks
-          # more reasonable than having DataTable of 1-2 rows.
-          post_process { |h|
-            h['weather2'] = h['weather'].last if h['weather'] && h['weather'].count > 1
-          }
-          post_process('weather', &:first)
-
-          post_process('dt', &Time.method(:at))
-          post_process('dt_txt') { nil } # TODO: we need cleaner way to say "remove this"
-          post_process('sys.sunrise', &Time.method(:at))
-          post_process('sys.sunset', &Time.method(:at))
-
-          # https://github.com/zverok/geo_coord promo here!
-          post_process { |e|
-            e['coord'] = Geo::Coord.new(e['coord.lat'], e['coord.lon']) if e['coord.lat'] && e['coord.lon']
-          }
-          post_process('coord.lat') { nil }
-          post_process('coord.lon') { nil }
-
-          # See http://openweathermap.org/weather-conditions#How-to-get-icon-URL
-          post_process('weather.icon') { |i| "http://openweathermap.org/img/w/#{i}.png" }
-        end
-
-        # For endpoints returning weather in one place
-        instance_eval(&WEATHER_POST_PROCESSOR)
-
-        # For endpoints returning list of weathers (forecast or several
-        # cities).
-        post_process_items('list', &WEATHER_POST_PROCESSOR)
       end
     end
   end

data/examples/open_weather_map_demo.rb

@@ -53,11 +53,11 @@ p TLAW::Examples::OpenWeatherMap.describe
 # and it is just printed the most convenient way.
 
 # Let's look closer to some of those namespaces:
-p TLAW::Examples::OpenWeatherMap.namespaces[:current]
+p TLAW::Examples::OpenWeatherMap.namespace(:current)
 # => #<TLAW::Examples::OpenWeatherMap::Current: call-sequence: current(); endpoints: city, city_id, location, zip, group; docs: .describe>
 
 # .describe, anyone?
-p TLAW::Examples::OpenWeatherMap.namespaces[:current].describe
+p TLAW::Examples::OpenWeatherMap.namespace(:current).describe
 # .current()
 #   Allows to obtain current weather at one place, designated
 #   by city, location or zip code.
@@ -87,11 +87,11 @@ p TLAW::Examples::OpenWeatherMap.namespaces[:current].describe
 
 # And further:
 p TLAW::Examples::OpenWeatherMap
-  .namespaces[:current].endpoints[:city]
+  .namespace(:current).endpoint(:city)
 # => #<TLAW::Examples::OpenWeatherMap::Current::City: call-sequence: city(city, country_code=nil); docs: .describe>
 
 p TLAW::Examples::OpenWeatherMap
-  .namespaces[:current].endpoints[:city].describe
+  .namespace(:current).endpoint(:city).describe
 # .city(city, country_code=nil)
 #   Current weather by city name (with optional country code
 #   specification).

data/examples/tmdb_demo.rb

@@ -121,7 +121,7 @@ p tmdb.movies.describe
 #
 #   .[](id)
 
-p tmdb.movies.namespaces[:[]].describe
+p tmdb.movies.namespace(:[]).describe
 # .[](id)
 #   @param id
 #

data/examples/urbandictionary_demo.rb

@@ -33,10 +33,10 @@ module TLAW
   module Examples
     class UrbanDictionary < TLAW::API
       define do
-        desc %Q{
+        desc <<~D
           Really small API. Described as "official but undocumented"
           by some.
-        }
+        D
 
         base 'http://api.urbandictionary.com/v0'
 

data/lib/tlaw.rb

@@ -1,20 +1,18 @@
-require 'open-uri'
+# frozen_string_literal: true
+
 require 'json'
+
+require 'backports/2.4.0/string/match'
+require 'backports/2.4.0/hash/compact'
+require 'backports/2.4.0/hash/transform_values'
+
+require 'backports/2.5.0/kernel/yield_self'
+require 'backports/2.5.0/hash/transform_keys'
+require 'backports/2.5.0/enumerable/all'
+
 require 'addressable/uri'
 require 'addressable/template'
 
-# Let no one know! But they in Ruby committee just too long to add
-# something like this to the language.
-#
-# See also https://bugs.ruby-lang.org/issues/12760
-#
-# @private
-class Object
-  def derp
-    yield self
-  end
-end
-
 # TLAW is a framework for creating API wrappers for get-only APIs (like
 # weather, geonames and so on) or subsets of APIs (like getting data from
 # Twitter).
@@ -56,13 +54,14 @@ require_relative 'tlaw/util'
 require_relative 'tlaw/data_table'
 
 require_relative 'tlaw/param'
-require_relative 'tlaw/param_set'
 
 require_relative 'tlaw/api_path'
 require_relative 'tlaw/endpoint'
 require_relative 'tlaw/namespace'
 require_relative 'tlaw/api'
 
-require_relative 'tlaw/response_processor'
+require_relative 'tlaw/formatting'
+
+require_relative 'tlaw/response_processors'
 
 require_relative 'tlaw/dsl'

data/lib/tlaw/api.rb

@@ -1,15 +1,20 @@
+# frozen_string_literal: true
+
 module TLAW
-  # API is just a top-level {Namespace}.
+  # API is a main TLAW class (and the only one you need to use directly).
   #
-  # Basically, you start creating your endpoint by descending from API
-  # and defining namespaces and endpoints through a {DSL} like this:
+  # Basically, you start creating your definition by descending from API and defining namespaces and
+  # endpoints through a {DSL} like this:
   #
   # ```ruby
-  # class MyCoolAPI < TLAW::API
+  # class SomeImagesAPI < TLAW::API
   #   define do
   #     base 'http://api.mycool.com'
   #
-  #     namespace :awesome do
+  #     namespace :gifs do
+  #       endpoint :search do
+  #         param :query
+  #       end
   #       # ...and so on
   #     end
   #   end
@@ -19,40 +24,117 @@ module TLAW
   # And then, you use it:
   #
   # ```ruby
-  # api = MyCoolAPI.new
-  # api.awesome.cool(param: 'value')
+  # api = SomeImagesAPI.new
+  # api.gifs.search(query: 'butterfly')
   # ```
   #
-  # See {DSL} for explanation of API definition, {Namespace} for explanation
-  # of possible usages and {Endpoint} for real calls performing.
+  # See {DSL} for detailed information of API definition, and {Namespace} for explanation about
+  # dynamically generated methods ({API} is also an instance of a {Namespace}).
   #
   class API < Namespace
-    # Thrown when there are an error during call. Contains real URL which
-    # was called at the time of an error.
+    # Thrown when there are an error during call. Contains real URL which was called at the time of
+    # an error.
     class Error < RuntimeError
     end
 
     class << self
+      # @private
+      attr_reader :url_template
+
       # Runs the {DSL} inside your API wrapper class.
       def define(&block)
-        DSL::APIWrapper.new(self).define(&block)
+        self == API and fail '#define should be called on the descendant of the TLAW::API'
+        DSL::ApiBuilder.new(self, &block).finalize
+        self
+      end
+
+      # @private
+      def setup(base_url: nil, **args)
+        if url_template
+          base_url and fail ArgumentError, "API's base_url can't be changed on redefinition"
+        else
+          base_url or fail ArgumentError, "API can't be defined without base_url"
+          self.url_template = base_url
+        end
+        super(symbol: nil, path: '', **args)
       end
 
-      # Returns detailed description of an API, like this:
-      #
-      # ```ruby
-      # MyCoolAPI.describe
-      # # MyCoolAPI.new()
-      # #   This is cool API.
-      # #
-      # #   Namespaces:
-      # #   .awesome()
-      # #     This is awesome.
-      # ```
-      #
-      def describe(*)
-        super.sub(/\A./, '')
+      # @private
+      def is_defined? # rubocop:disable Naming/PredicateName
+        self < API
       end
+
+      protected
+
+      attr_writer :url_template
+
+      private :parent, :parent=
+    end
+
+    private :parent
+
+    # Create an instance of your API descendant.
+    # Params to pass here correspond to `param`s defined at top level of the DSL, e.g.
+    #
+    # ```ruby
+    # # if you defined your API like this...
+    # class MyAPI < TLAW::API
+    #   define do
+    #     param :api_key
+    #     # ....
+    #   end
+    # end
+    #
+    # # the instance should be created like this:
+    # api = MyAPI.new(api_key: '<some-api-key>')
+    # ```
+    #
+    # If the block is passed, it is called with an instance of
+    # [Faraday::Connection](https://www.rubydoc.info/gems/faraday/Faraday/Connection) object which
+    # would be used for API requests, allowing to set up some connection configuration:
+    #
+    # ```ruby
+    # api = MyAPI.new(api_key: '<some-api-key>') { |conn| conn.basic_auth 'login', 'pass' }
+    # ```
+    #
+    # @yield [Faraday::Connection]
+    def initialize(**params, &block)
+      super(nil, **params)
+
+      @client = Faraday.new do |faraday|
+        faraday.use FaradayMiddleware::FollowRedirects
+        faraday.adapter Faraday.default_adapter
+        block&.call(faraday)
+      end
+    end
+
+    # @private
+    def request(url, **params)
+      @client.get(url, **params).tap(&method(:guard_errors!))
+    rescue Error
+      raise # Not catching in the next block
+    rescue StandardError => e
+      raise Error, "#{e.class} at #{url}: #{e.message}"
+    end
+
+    private
+
+    def guard_errors!(response)
+      # TODO: follow redirects
+      return response if (200...400).cover?(response.status)
+
+      fail Error,
+           "HTTP #{response.status} at #{response.env[:url]}" +
+           extract_message(response.body)&.yield_self { |m| ': ' + m }.to_s
+    end
+
+    def extract_message(body)
+      # FIXME: well, that's just awful
+      # ...minimal is at least extract *_message key (TMDB has status_message, for ex.)
+      data = JSON.parse(body) rescue nil
+      return body unless data.is_a?(Hash)
+
+      data.values_at('message', 'error').compact.first || body
     end
   end
 end