mediawiktory 0.0.3 → 0.1.0

data/lib/mediawiktory/generator/renderable.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module MediaWiktory
+  class Generator
+    module Renderable
+      def to_h
+        stringify_hash(super, recursive: true)
+      end
+
+      def render_to(path, **vars)
+        FileUtils.mkdir_p File.dirname(path)
+        File.write(path, to_html(**vars))
+      end
+
+      def to_html(**vars)
+        render(vars.fetch(:template, main_template), **vars)
+      end
+
+      def render(template, **vars)
+        # puts "Rendering #{template} with #{self}#{vars}"
+        vars.each { |name, val| instance_variable_set("@#{name}", val) }
+        path = File.expand_path("../templates/#{template}.erb", __FILE__)
+        ERB.new(File.read(path))
+           .tap { |tpl| tpl.filename = path }
+           .result(binding)
+      end
+
+      def partial(template, context = nil)
+        # puts "Rendering #{template} with #{context || self}"
+
+        # Never repeat this at home, dear children.
+        if context
+          instance_variables.each { |var| context.instance_variable_set(var, instance_variable_get(var)) }
+        end
+        path = File.expand_path("../templates/#{template}.erb", __FILE__)
+        ERB.new(File.read(path))
+           .tap { |tpl| tpl.filename = path }
+           .result(context ? context.get_binding : binding)
+      rescue => e
+        puts "#{e} while #{template} with #{context || self}"
+        raise
+      end
+
+      def get_binding # rubocop:disable Style/AccessorMethodName
+        binding
+      end
+
+      private
+
+      def stringify_hash(hash, recursive: false)
+        hash.map { |k, v|
+          [k.to_s, v.is_a?(Hash) && recursive ? stringify_hash(v, recursive: true) : v.to_s]
+        }.to_h
+      end
+    end
+  end
+end

data/lib/mediawiktory/generator/templates/_action_method.erb

@@ -0,0 +1,20 @@
+
+    # <%= description.strip.gsub('#', '  #') %>
+    #
+    # This method creates an instance of {<%= @namespace %>::Actions::<%= class_name %>} action.
+    #
+<% unless params.empty? %>    # Action parameters could be passed or by subsequent
+    # {<%= @namespace %>::Actions::<%= class_name %>} method calls, like
+    #
+    # ```ruby
+    # api.<%= method_name %>.<%= params.first.name %>('value')
+    # ```<% end %>
+    #
+    # See {<%= @namespace %>::Actions::Base} for generic explanation of working with MediaWiki actions and
+    # {<%= @namespace %>::Actions::<%= class_name %>} class for a list of parameters and usage.
+    #
+    # @return [<%= @namespace %>::Actions::<%= class_name %>]
+    #
+    def <%= method_name %>
+      <%= class_name %>.new(client, @defaults)
+    end

data/lib/mediawiktory/generator/templates/_module_in_param_docs.erb

@@ -0,0 +1,2 @@
+<% modules.each do |mod| %>
+      #   * `:<%= mod.name.sub(/^g-/, '') %>` - {<%=@namespace%>::Modules::<%= mod.class_name %>} <%= mod.description %><% end %>

data/lib/mediawiktory/generator/templates/_param_impl_boolean.erb

@@ -0,0 +1 @@
+merge(<%= full_name %>: 'true')

data/lib/mediawiktory/generator/templates/_param_impl_enum.erb

@@ -0,0 +1 @@
+defined?(super) && super || [<%= enum_values %>].include?(value.to_s) && merge(<%= full_name %>: value.to_s<% if list? %>, replace: false<% end %>)

data/lib/mediawiktory/generator/templates/_param_impl_enum_of_modules.erb

@@ -0,0 +1 @@
+<% unless full_name == 'format' %>defined?(super) && super || <% end %>[<%= enum_values %>].include?(value.to_sym) && merge(<%= full_name %>: value.to_s<% if list? %>, replace: false<% end %>).submodule({<%= modules_hash %>}[value.to_sym])

data/lib/mediawiktory/generator/templates/_param_impl_string.erb

@@ -0,0 +1 @@
+merge(<%= full_name %>: value.to_s<% if list? %>, replace: false<% end %>)

data/lib/mediawiktory/generator/templates/_param_impl_timestamp.erb

@@ -0,0 +1 @@
+merge(<%= full_name %>: value.iso8601<% if list? %>, replace: false<% end %>)

data/lib/mediawiktory/generator/templates/_param_method.erb

@@ -0,0 +1,14 @@
+
+      # <%= description %>
+      #
+<% unless param_def.empty? %>      # @param <%= param_def.sub('*', '') %> [<%= ruby_type %>]<%= param_docs %><% if real_type.include?('of modules') %><%= partial '_module_in_param_docs' %><% else %>
+<% end %><% end %>      # @return [self]
+      def <%= method_name %>(<%= param_def %>)
+        <% if list?
+          %>values.inject(self) { |res, val| res._<%= method_name %>(val)<% if impl_type.include?('enum') %> or fail ArgumentError, "Unknown value for <%= method_name %>: #{val}"<% end %> }<%
+          elsif enum? %>_<%= method_name %>(value) or fail ArgumentError, "Unknown value for <%= method_name %>: #{value}"<% end %><% if list? || enum? %>
+      end
+
+      # @private
+      def _<%= method_name %>(value)
+        <%= partial("_param_impl_#{impl_type}") %>      end<% else %><%= partial("_param_impl_#{impl_type}") %>      end<% end %>

data/lib/mediawiktory/generator/templates/action.rb.erb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require_relative '../response'
+
+module <%= @namespace %>
+  module Actions
+    # Global setup methods included into every action through {Base}.
+    module GlobalParams
+<% main.params.each { |param| %><%= partial '_param_method', param %><% } %>
+    end
+
+    # Base class for all {<%= @namespace %>::Api} actions. "Actions" is MediaWiki's term for
+    # different request types. Everything you are doing with your target MediaWiki installation, you
+    # are doing by _performing actions_.
+    #
+    # Typically, you should never instantiate this class or its descendants directly, but rather by
+    # {<%= @namespace %>::Api Api} methods (included from {<%= @namespace %>::Actions Actions}
+    # module).
+    #
+    # The usual workflow with actions is:
+    #
+    # * Create it with `api.action_name`
+    # * Set action params with subsequent `paramname(paramvalue)` calls;
+    # * Perform action with {#perform} (returns row MediaWiki response as a string) or {#response}
+    #   (returns {<%= @namespace %>::Response} class with parsed data and helper methods).
+    #
+    # Note that some of `paramname(value)` calls include new {Modules} into action, which provides
+    # new params & methods. For example:
+    #
+    # ```ruby
+    # api.query.generator(:categorymembers) # includes new methods of GCategorymembers module
+    #    .title('Category:DOS_games')       # one of GCategorymembers methods, adds gcmtitle=Category:DOS_games to URL
+    #    .limit(20)
+    # ```
+    #
+    # Sometimes new modules inclusion can change a sense of already existing methods:
+    #
+    # ```ruby
+    # api.query.titles('Argentina')
+    #   .prop(:revisions)           # .prop method from Query action, adds prop=revisions to URL and includes Revisions module
+    #   .prop(:content)             # .prop method from Revisions module, adds rvprop=content to URL
+    # ```
+    #
+    # Despite of how questionable this practice looks, it provides the most obvious method chains even
+    # for most complicated cases.
+    #
+    # Some setup methods shared between all the actions (like output format and TTL settings of
+    # response) are defined in {GlobalParams}.
+    #
+    # Full action usage example:
+    #
+    # ```ruby
+    # api = MediaWiktory::Wikipedia::Api.new
+    # action = api.new.query.titles('Argentina').prop(:revisions).prop(:content).meta(:siteinfo)
+    # # => #<MediaWiktory::Wikipedia::Actions::Query {"titles"=>"Argentina", "prop"=>"revisions", "rvprop"=>"content", "meta"=>"siteinfo"}>
+    # response = action.response
+    # # => #<MediaWiktory::Wikipedia::Response(query): pages, general>
+    # puts response['pages'].values   # all pages...
+    #   .first['revisions']           # take revisions from first...
+    #   .first['*']                   # take content from first revision...
+    #   .split("\n").first(3)         # and first 3 paragrapahs
+    # # {{other uses}}
+    # # {{pp-semi|small=yes}}
+    # # {{Use dmy dates|date=March 2017}}
+    # response.dig('general', 'sitename')
+    # # => "Wikipedia"
+    # ```
+    #
+    class Base
+      # @private
+      attr_reader :client
+
+      # @private
+      def initialize(client, options = {})
+        @client = client
+        @params = stringify_hash(options)
+        @submodules = []
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} #{to_h}>"
+      end
+
+      # Make new action, with additional params passed as `hash`. No params validations are made.
+      #
+      # @param hash [Hash] Params to merge. All keys and values would be stringified.
+      # @return [Action] Produced action of the same type as current action was, with all passed
+      #   params applied.
+      def merge(hash)
+        replace = hash.fetch(:replace, true)
+        hash.delete(:replace)
+        self.class
+            .new(@client, @params.merge(stringify_hash(hash)) { |_, o, n| replace ? n : [o, n].compact.uniq.join('|') })
+            .tap { |action| @submodules.each { |sm| action.submodule(sm) } }
+      end
+
+      # All action's params in a ready to passing to URL form (string keys & string values).
+      #
+      # @example
+      #    api.query.titles('Argentina', 'Bolivia').format(:json).to_h
+      #    # => {"titles"=>"Argentina|Bolivia", "format"=>"json"}
+      #
+      # @return [Hash{String => String}]
+      def to_h
+        @params.dup
+      end
+
+      # Action's name on MediaWiki API (e.g. "query" for `Query` action, "parsoid-batch" for
+      # `ParsoidBatch` action and so on).
+      #
+      # @return [String]
+      def name
+        # Query # => query
+        # ParsoidBatch # => parsoid-batch
+        self.class.name.split('::').last.gsub(/([a-z])([A-Z])/, '\1-\2').downcase or
+          fail ArgumentError, "Can't guess action name from #{self.class.name}"
+      end
+
+      # All action's params in a ready to passing to URL form (string keys & string values). Unlike
+      # {#to_h}, includes also action name.
+      #
+      # @example
+      #    api.query.titles('Argentina', 'Bolivia').format(:json).to_param
+      #    # => {"titles"=>"Argentina|Bolivia", "format"=>"json", "action"=>"query"}
+      #
+      # @return [Hash{String => String}]
+      def to_param
+        to_h.merge('action' => name)
+      end
+
+      # Full URL for this action invocation.
+      #
+      # @example
+      #    api.query.titles('Argentina', 'Bolivia').format(:json).to_url
+      #    # => "https://en.wikipedia.org/w/api.php?action=query&format=json&titles=Argentina%7CBolivia"
+      #
+      # @return [String]
+      def to_url
+        url = @client.url
+        url.query_values = to_param
+        url.to_s
+      end
+
+      # Performs action (through `GET` or `POST` request, depending on action's type) and returns
+      # raw body of response.
+      #
+      # @return [String]
+      def perform
+        fail NotImplementedError,
+             'Action is abstract, all actions should descend from Actions::Get or Actions::Post'
+      end
+
+      # Performs action (as in {#perform}) and returns an instance of {Response}. It is a thing
+      # wrapper around parsed action's JSON response, which separates "content" and "meta" (paging,
+      # warnings/erros) fields.
+      #
+      # Note, that not all actions return a JSON suitable for parsing into {Response}. For example,
+      # Wikipedia's [opensearch](https://en.wikipedia.org/w/api.php?action=help&modules=opensearch)
+      # action returns absolutely different JSON structure, corresponding to global
+      # [OpenSearch](https://en.wikipedia.org/wiki/OpenSearch) standard.
+      #
+      # Note also, that on erroneous request (when response contains `"error"` key), this method
+      # will raise {Response::Error}.
+      #
+      # @return [Response]
+      def response
+        jsonable = format(:json)
+        Response.parse(jsonable, jsonable.perform)
+      end
+
+      include GlobalParams
+
+      private
+
+      # Not in indepented module to decrease generated files/modules list
+      def stringify_hash(hash, recursive: false)
+        hash.map { |k, v|
+          [k.to_s, v.is_a?(Hash) && recursive ? stringify_hash(v, recursive: true) : v.to_s]
+        }.to_h
+      end
+
+      protected
+
+      def submodule(mod)
+        extend(mod)
+        @submodules << mod
+        self
+      end
+    end
+
+    class Get < Base
+      def perform
+        client.get(to_param)
+      end
+    end
+
+    class Post < Base
+      def perform
+        client.post(to_param)
+      end
+    end
+  end
+end

data/lib/mediawiktory/generator/templates/action_class.rb.erb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module <%= @namespace %>
+  module Actions
+    # <%= description %>
+    #
+    # Usage:
+    #
+<% if params.empty? %>    # ```ruby
+    # api.<%= name %>.perform # returns string with raw output
+    # # or
+    # api.<%= name %>.response # returns output parsed and wrapped into Mash-like object
+    # ```
+    #
+    # This action has no parameters.
+<% else %>    # ```ruby
+    # api.<%= name %>.<%= params.first.name %>(value).perform # returns string with raw output
+    # # or
+    # api.<%= name %>.<%= params.first.name %>(value).response # returns output parsed and wrapped into Response object
+    # ```
+<% end %>    #
+    # See {Base} for generic explanation of working with MediaWiki actions and
+    # {<%= @namespace %>::Response} for working with action responses.
+    #
+    # All action's parameters are documented as its public methods, see below.
+    #
+    class <%= class_name %> < <%=@namespace%>::Actions::<%= http_method %>
+<% params.each { |param| %><%= partial '_param_method', param %><% } %>    end
+  end
+end

data/lib/mediawiktory/generator/templates/actions.rb.erb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative './actions/base'
+
+module <%= @namespace %>
+  # Methods of this module contains all actions that can be used on {Api}.
+  # You use them like this:
+  #
+  # ```ruby
+  # api = <%= @namespace %>::Api.new
+  #
+  # api.query                           # method of Api, returning Actions::Query
+  #    .titles('Argentina', 'Bolivia')  # methods of Actions::Query...
+  #    .prop(:revisions).prop(:content) # ...to set action options
+  #    .response
+  # # => performs action and returns Response instance
+  # ```
+  #
+  # See also:
+  # * {Api} for starting;
+  # * {Actions::Base} for details of working with actions;
+  # * and {Response}.
+  #
+  # Note that for each MediaWiki site the main method for **data extraction** (pages, categories,
+  # meta-information) is {#query}.
+  #
+  module Actions
+<% actions.each { |action| %><%= partial '_action_method', action %><% } %>  end
+end
+
+Dir[File.expand_path('../{actions,modules}/*.rb', __FILE__)].each { |f| require f }

data/lib/mediawiktory/generator/templates/api.rb.erb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative './client'
+require_relative './actions'
+
+# Wrapper for [<%= site.name %>](<%= site.base %>) API.
+#
+# _Generated from <%= @source %> at <%= @friendly_date %> by MediaWiktory <%= @version %>._
+#
+# It also can be used for access to any other MediaWiki site, but some of actions could be
+# non-existent/outdated.
+#
+# See {<%= @namespace %>::Api} for usage.
+#
+module <%= @namespace %>
+  # Base API class for [<%= site.name %>](<%= site.base %>).
+  #
+  # Example of usage:
+  #
+  # ```ruby
+  # # For <%= site.name %>
+  # api = <%= @namespace %>::Api.new
+  # api.some_action.some_param(value).other_param(*more_values).perform
+  # # => returns raw response of MediaWiki API
+  # api.some_action.some_param(value).other_param(*more_values).response
+  # # => returns an instance of Response, parsed from JSON
+  #
+  # # For any other site:
+  # api = <%= @namespace %>::Api.new('https://some.site/w/api.php')
+  # # ...the same as above
+  # ```
+  #
+  # {Actions} module lists all available API actions and refers to corresponding classes and
+  # their options.
+  #
+  # See also {Response} for working with return values and {Actions::Base} for working with actions.
+  #
+  class Api
+    # @private
+    attr_reader :client, :defaults
+
+    # @private
+    CLIENT_OPTIONS = %i[user_agent ua].freeze
+
+    # @param url [String] Source URL for this API, by default "<%= source %>".
+    #   Note that most of MediaWiki installations have source URL at `/w/api.php`, but some are
+    #   just `/api.php`, others use `/wiki/api.php` and so on.
+    #
+    # @param defaults [Hash] Default options for all API queries. Default param values also can be
+    #   set by subsequent {Actions::Base} methods, like `api.some_action.json(callback: 'mycallbackname')...`
+    # @option defaults [Symbol] user_agent User-Agent header for underlying client.
+<% main.params.each do |param| %>    # @option defaults [<%= param.ruby_type %>] <%= param.name %> <%= param.description %><%=param.param_docs%> See {Actions::Base#<%=param.name%>}
+<% end %>    #
+    def initialize(url = '<%= @source %>', **defaults)
+      client_options, @defaults = defaults.partition { |k, _| CLIENT_OPTIONS.include?(k) }.map(&:to_h)
+      @client = Client.new(url, **client_options)
+    end
+
+    def inspect
+      "#<#{self.class.name}(#{@client.url})>"
+    end
+
+    include <%= @namespace %>::Actions
+  end
+end