class Acromine

a client for the Acromine REST service

Constants

DEFAULT_URI: the URL to the Acromine REST service
VERSION: the version of the gem

Public Class Methods

new(uri = DEFAULT_URI) click to toggle source

constructs an Acromine object @param uri [String] the URI to the Acromine REST service

# File lib/acromine/core.rb, line 15
def initialize(uri = DEFAULT_URI)
  self.class.base_uri uri
  self.class.format :json
end

Public Instance Methods

longforms(acronym, opts = {}) click to toggle source

finds the long form(s) of an acronym @param acronym [String] the acronym to expand @param opts [Hash] sort and limit options @return [Array<Acromine::Longform>, []] a list of long forms for the

acronym, or an empty array if the acronym was not found

# File lib/acromine/core.rb, line 25
def longforms(acronym, opts = {})
  # validate our options
  validate_opts(opts)
  # get the acronyms from the webservice
  ret = self.class.get('', query: { sf: acronym })
  # an empty JSON array means the acronym was not found
  return [] if ret.body == "[]\n"
  build_lfs(ret, opts)
end

Private Instance Methods

build_lf(lf) click to toggle source

builds a single Acromine::Longform object @param lf [Hash] a single ‘lf’ entry from the JSON returned by

the webservice

@return [Acromine::Longform] @api private

# File lib/acromine/core.rb, line 139
def build_lf(lf)
  lfobj = Acromine::Longform.new(
    longform: lf['lf'],
    frequency: lf['freq'],
    since: lf['since']
  )
  lf['vars'].each do |var|
    lfobj.variants << build_lfv(var)
  end
  lfobj
end

build_lfs(json, opts = {}) click to toggle source

builds LongForm objects from the JSON returned by the REST service @param json [Array] a list of long forms as described by

http://www.nactem.ac.uk/software/acromine/rest.html

@param opts [Hash] sort and limit options @return [Array<Acromine::Longform>] a list of long form objects @api private

# File lib/acromine/core.rb, line 66
def build_lfs(json, opts = {})
  ret = []
  massage_data(json[0]['lfs'], opts).each do |lf|
    lfobj = build_lf(lf)
    ret << lfobj
  end
  ret
end

build_lfv(var) click to toggle source

builds a single Acromine::LongformVariant object @param var [Hash] a single ‘lf’ variant entry from the JSON returned

by the webservice

@return [Acromine::LongformVariant] @api private

# File lib/acromine/core.rb, line 156
def build_lfv(var)
  Acromine::LongformVariant.new(
    longform: var['lf'],
    frequency: var['freq'],
    since: var['since']
  )
end

build_sort_xforms(sort_spec) click to toggle source

returns a set of lambdas that will extract the correct transformed

elements of a long form based on a sort spec

@param sort_spec [String] how to sort the long forms on frequency

and year.  The spec is one or two two-character pairs joined by
a comma.  The first character of the pair is what to sort - f for
the frequency and y for the year.  The second character of the pair
is how to sort - a for ascending and d for descending

@example sort by frequency descending then year ascending

build_sort_xforms('fd,ya')

@example sort by year descending then frequency descending

build_sort_xforms('yd,fd')

@example sort just by year ascending (i.e. oldest first)

build_sort_xforms('ya')

@return [Array<#call>] a set of transforms from longform JSON data

into a sortable tuple

@api private

# File lib/acromine/core.rb, line 105
def build_sort_xforms(sort_spec)
  xforms = []
  sort_spec.split(',').each do |spec|
    what, how = spec.chars
    xforms << case what
              when 'f'
                case how
                when 'a'
                  ->(x) { x['freq'] }
                when 'd'
                  ->(x) { -x['freq'] }
                end
              when 'y'
                case how
                when 'a'
                  ->(x) { x['since'] }
                when 'd'
                  ->(x) { -x['since'] }
                end
              when 'l'
                case how
                when 'a'
                  ->(x) { x['lf'] }
                end
              end
  end
  xforms
end

massage_data(json, limit: nil, sort_spec: 'fd,ya') click to toggle source

sorts and limits the JSON data returned from the REST service @param json [Array] the ‘lfs’ data from the web service @param limit [Fixnum] how many long forms to return @param sort_spec [String] how to sort on frequency and year @api private

# File lib/acromine/core.rb, line 80
def massage_data(json, limit: nil, sort_spec: 'fd,ya')
  xforms = build_sort_xforms(sort_spec + ',la')
  sorted = json.sort_by do |e|
    xforms.map { |x| x.call(e) }
  end
  # only return the top x if a limit was specified
  limit.nil? ? sorted : sorted.take(limit.to_i)
end

validate_opts(limit: nil, sort_spec: nil) click to toggle source

validates filter and sort options @param limit [Fixnum] how many long forms to return @param sort_spec [String] how to sort the long forms on frequency and year @raise RuntimeError if parameters are invalid

# File lib/acromine/core.rb, line 41
def validate_opts(limit: nil, sort_spec: nil)
  # validate that the limit is a positive integer
  if limit
    begin
      !Float(limit).nil?
    rescue
      raise "invalid limit '#{limit}'"
    end
    fail "invalid limit '#{limit}'" if limit.to_i < 1
  end
  # validate the sort spec(s)
  return unless sort_spec
  specs = sort_spec.split(/,/)
  fail 'too many sort specs (max 2)' if specs.size > 2
  specs.each do|spec|
    fail "invalid sort spec '#{sort_spec}'" unless spec.match(/^[fy][ad]$/)
  end
end