openaustralia 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="ruby-1.9.2-p290"
+
+#
+# Uncomment following line if you want options to be set only for given project.
+#
+# PROJECT_JRUBY_OPTS=( --1.9 )
+
+#
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+
+  if [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]]
+  then
+    . "${rvm_path:-$HOME/.rvm}/hooks/after_use"
+  fi
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  if ! rvm --create  "$environment_id"
+  then
+    echo "Failed to create RVM environment '${environment_id}'."
+    exit 1
+  fi
+fi
+
+#
+# If you use an RVM gemset file to install a list of gems (*.gems), you can have
+# it be automatically loaded. Uncomment the following and adjust the filename if
+# necessary.
+#
+# filename=".gems"
+# if [[ -s "$filename" ]]
+# then
+#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+# fi
+
+# If you use bundler, this might be useful to you:
+# if command -v bundle && [[ -s Gemfile ]]
+# then
+#   bundle install
+# fi
+
+

data/CHANGES.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.0.0 - 2012-07-13
+
+* Major overhaul to bring gem up to date
+** Most significant change for users is the gem has been renamed from 'open-australia' to 'openaustralia'
+** Fixed `get_divisions`
+
+## 0.0.1 - 2009-12-08
+
+* Initial release:
+** API methods wrapped
+** parses correctly on selective canned data

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in openaustralia.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,23 @@
+Copyright (c) 2009 Alex Cooper
+Copyright (c) 2012 Henare Degan
+
+MIT License
+
+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 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

@@ -0,0 +1,49 @@
+# OpenAustralia
+
+A Ruby wrapper for the [OpenAustralia API](http://www.openaustralia.org/api/).
+
+## Requirements
+
+* An account on openaustralia.org
+* An API key obtained from http://openaustralia.org/api
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'openaustralia'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install openaustralia
+
+## Features/problems
+
+* Wraps the current API calls
+* So far no validation on validity of parameters or search terms
+
+## Usage
+
+    # spit out excerpts of what's been said
+    # about the emissions trading scheme
+
+    require 'openaustralia'
+
+    api = OpenAustralia::Api.new 'YOUR-API-KEY-HERE'
+
+    search = api.get_hansard :search => 'emissions trading'
+    search.results.each do |result|
+      puts result.body
+    end
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/openaustralia.rb

@@ -0,0 +1,6 @@
+require "openaustralia/version"
+require "openaustralia/api"
+
+module OpenAustralia
+  # Your code goes here...
+end

data/lib/openaustralia/api.rb

@@ -0,0 +1,248 @@
+require 'open-uri'
+require 'cgi'
+require 'xml/mapping'
+require 'rexml/document'
+
+require 'openaustralia/divisions'
+require 'openaustralia/representatives'
+require 'openaustralia/senators'
+require 'openaustralia/debates'
+require 'openaustralia/hansard'
+require 'openaustralia/search_info'
+require 'openaustralia/comments'
+
+module OpenAustralia
+
+  # Ruby wrapper for the openaustralia.org API
+  #
+  # You'll need an API key: get one at http://openaustralia.org/api
+  #
+  class Api
+
+    # create an API instance with the specified key
+    # Get your key from http://openaustralia.org/api
+    def initialize(key)
+      @key = key
+      @xml_getter = XmlGetter.new #replaced for unit tests
+    end
+
+    # get_divisions returns a list of electoral divisions
+    #
+    # supported search parameters:
+    #  postcode (optional)
+    #    Fetch the list of electoral divisions that are within the given
+    #    postcode (there can be more than one)
+    #  date (optional)
+    #    Fetch the list of electoral divisions as it was on this date.
+    #  search (optional)
+    #    Fetch the list of electoral divisions that match this search string.
+    #
+    # example:
+    #  get_disivions :postcode => 3022
+    #
+    # NB: at the time of writing, only the postcode parameter seems
+    # to actually work.
+    def get_divisions(search_params = {})
+      xml = do_request('getDivisions', search_params)
+      DivisionResult.load_from_xml xml
+    end
+
+    # Fetch a particular member of the House of Representatives.
+    # 
+    # Arguments
+    #
+    # id (optional)
+    #     If you know the person ID for the member you want (returned from
+    #     getRepresentatives or elsewhere), this will return data for
+    #     that person.
+    # division (optional)
+    #     The name of an electoral division; we will try and work it out from
+    #     whatever you give us. :)
+    # always_return (optional)
+    #     For the division option, sets whether to always try and return a
+    #     Representative, even if the seat is currently vacant.
+    #
+    # example:
+    #     get_representative :id => 10001
+    #
+    def get_representative(search_params = {})
+      xml = do_request('getRepresentative', search_params)
+      result = RepresentativeResult.load_from_xml xml
+      result.matches.first
+    end
+
+    #Fetch a list of members of the House of Representatives.
+    #Arguments
+    #
+    #postcode (optional)
+    #    Fetch the list of Representatives whose electoral division lies within
+    #    the postcode (there may be more than one)
+    #date (optional)
+    #    Fetch the list of members of the House of Representatives as it was on
+    #    this date.
+    #party (optional)
+    #    Fetch the list of Representatives from the given party.
+    #search (optional)
+    #    Fetch the list of Representatives that match this search string in
+    #    their name.
+    #
+    #example
+    #    api.get_representatives :postcode => 2000
+    #
+    #NB: if more than one representative is returned, then the 'office' array
+    #    will be empty.
+    def get_representatives(search_params = {})
+      xml = do_request('getRepresentatives', search_params)
+      result = RepresentativeResult.load_from_xml xml
+      result.matches
+    end
+
+    #Fetch a particular Senator.
+    #Arguments
+    #
+    #id (required)
+    #    If you know the person ID for the Senator you want, this will return data for that person.
+    #
+    #example
+    #    api.get_senator :id => 10214
+    def get_senator(search_params = {})
+      xml = do_request('getSenator', search_params)
+      result = SenatorResult.load_from_xml xml
+      result.matches.first
+    end
+
+    #Fetch a list of Senators.
+    #Arguments
+    #
+    #date (optional)
+    #    Fetch the list of Senators as it was on this date.
+    #party (optional)
+    #    Fetch the list of Senators from the given party.
+    #state (optional)
+    #    Fetch the list of Senators from the given state.
+    #search (optional)
+    #    Fetch the list of Senators that match this search string in their name.
+    #
+    #example
+    #    api.get_senators :search => 'brown'
+    #
+    def get_senators(search_params = {})
+      xml = do_request('getSenators', search_params)
+      result = SenatorSearchResult.load_from_xml xml
+      result.matches
+    end
+    
+    #Fetch Debates.
+    #
+    #This includes Oral Questions.
+    #Arguments
+    #
+    #Note you can only supply one of the following search terms at present.
+    #
+    #type (required)
+    #    One of "representatives" or "senate". 
+    #date
+    #    Fetch the debates for this date.
+    #search
+    #    Fetch the debates that contain this term.
+    #person
+    #    Fetch the debates by a particular person ID.
+    #gid
+    #    Fetch the speech or debate that matches this GID.
+    #order (optional, when using search or person)
+    #    d for date ordering, r for relevance ordering.
+    #page (optional, when using search or person)
+    #    Page of results to return.
+    #num (optional, when using search or person)
+    #    Number of results to return.
+    def get_debates(search_params = {})
+      xml = do_request('getDebates', search_params)
+      DebateSearch.load_from_xml xml.root
+    end
+
+    #Fetch all Hansard.
+    #Arguments
+    #
+    #Note you can only supply one of the following at present.
+    #
+    #search
+    #    Fetch the data that contain this term.
+    #person
+    #    Fetch the data by a particular person ID.
+    #order (optional, when using search or person, defaults to date)
+    #    d for date ordering, r for relevance ordering, p for use by person.
+    #page (optional, when using search or person)
+    #    Page of results to return.
+    #num (optional, when using search or person)
+    #    Number of results to return.
+    #
+    def get_hansard(search_params = {})
+      xml = do_request('getHansard', search_params)
+      HansardSearch.load_from_xml xml.root
+    end
+
+    #Fetch comments left on OpenAustralia.
+    #
+    #With no arguments, returns most recent comments in reverse date order.
+    #Arguments
+    #
+    #date (optional)
+    #    Fetch the comments for this date.
+    #search (optional)
+    #    Fetch the comments that contain this term.
+    #user_id (optional)
+    #    Fetch the comments by a particular user ID.
+    #pid
+    #    Fetch the comments made on a particular person ID (Representative/Senator).
+    #page (optional)
+    #    Page of results to return.
+    #num (optional)
+    #    Number of results to return.
+    def get_comments(search_params = {})
+      xml = do_request('getComments', search_params)
+      CommentsSearch.load_from_xml xml
+    end
+
+    private
+
+    # process the specified API request,
+    # returning XML
+    def do_request(command, params)
+      url = request_url(command, params)
+      @xml_getter.fetch url
+    end
+
+    # replace the XML getter with a different one
+    # (used by unit tests
+    def xml_getter=(getter)
+      @xml_getter = getter
+    end
+
+    # the URL for the given request
+    def request_url(command, params)
+      url = "http://www.openaustralia.org/api/#{command}?key=#{@key}&output=xml"
+      params.each do |k,v|
+        key = CGI::escape(k.to_s)
+        value = CGI::escape(v.to_s)
+        url += "&#{key}=#{value}"
+      end
+      url
+    end
+  end
+
+  # XmlGetter is a dependency for fetching a URL
+  # and parsing it as XML. We're using a separate
+  # dependency so we can inject a different one
+  # for unit testing
+  class XmlGetter
+
+    # fetch the specified URL and parse
+    # into a REXML document
+    def fetch(url)
+      open(url) do |f|
+        return REXML::Document.new f
+      end
+    end
+    
+  end
+end

data/lib/openaustralia/comments.rb

@@ -0,0 +1,28 @@
+require 'xml/mapping'
+
+module OpenAustralia
+
+  # comments
+  class Comments
+    include XML::Mapping
+
+    numeric_node :comment_id, 'comment_id'
+    numeric_node :user_id, 'user_id'
+    text_node :body, 'body'
+    text_node :posted, 'posted'
+    numeric_node :major, 'major'
+    text_node :gid, 'gid'
+    text_node :firstname, 'firstname'
+    text_node :lastname, 'lastname'
+    text_node :url, 'url'
+  end
+  
+  # search results from a comments search
+  class CommentsSearch # :nodoc:
+    include XML::Mapping
+
+    array_node :results, 'comments', 'match', :class => Comments,
+      :default_value => []
+  end
+
+end