arcrest 0.0.0.pre → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4facbf131295458bba59afadece248118b806cf9
-  data.tar.gz: 4453da319fa914ff6a03e9b42caf6fd2c6720b6f
+  metadata.gz: 948887626e3cbf6c38a60ab4d3f3f96f38815a64
+  data.tar.gz: ee36b210de6e5354e2afae62ec6b3ba3bdbb44d4
 SHA512:
-  metadata.gz: 6f78ad5e3bd3d33f9f75da848670163a8a3b1fd07c541046e8125de5f61b99723005b680dc2eaabd55674fc9b5e4c78c611039e75ee63d9f52fac42f27b2ab9a
-  data.tar.gz: e08922265ac4e258c8ba4ac1cdd5e45a98092949f88b9398e9614637aebfc2854cd51cde97b2ccffb3100a890fb440e19dc47bcd11553f1251be8849e093c2a6
+  metadata.gz: a3bfa45f4ea1fa30629e216122fe40783d3519b78e9e592e6e14ea41082b0e88d18bc8e284f101da40a07610ec69154772a99256b9748cf30f62e4905d89edbd
+  data.tar.gz: 736154f7a57441c74bb37234b500a3126c258ce173adc4aa5e0a7b5af2ca2be38f7c55d7aad7952cace2f82337d7529a638538ff238e02cf630b7f578ccf9509

data/.rspec

@@ -1,2 +1,3 @@
 --format documentation
 --color
+--require spec_helper

data/.travis.yml

@@ -2,9 +2,8 @@ sudo: false
 language: ruby
 
 rvm:
-  - 2.3.0
-  - 2.2.0
-  - 2.1
+  - 2.3.1
+  - 2.2.5
 
 before_install: gem install bundler -v 1.12.5
 

data/Guardfile

@@ -0,0 +1,13 @@
+notification :gntp
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^lib/(.+).rb$}) do |m| # watch /lib/ files
+    "spec/#{m[1]}_spec.rb"
+  end
+
+  watch(%r{^spec/(.+).rb$}) do |m| # watch /spec/ files
+    "spec/#{m[1]}.rb"
+  end
+
+  watch('spec/spec_helper.rb') { 'spec' }
+end

data/README.md

@@ -1,19 +1,113 @@
-# Arcrest
+# ArcREST
+[![Build status](https://secure.travis-ci.org/MatzFan/ArcREST.svg)](http://travis-ci.org/MatzFan/ArcREST)
+[![Gem Version](https://badge.fury.io/rb/arcrest.svg)](http://badge.fury.io/rb/arcrest)
+
+Ruby Gem wrapper around the [ArcGIS REST API](http://services.arcgisonline.com/arcgis/sdk/rest/)
+
+## Requirements
+
+bundler
+
+
+## Current Limitations
+
+API FeatureServer query capabilities only at present. Unauthenticated calls only (please raise an issue if you wish this to be supported)
 
-Placeholder for arcrest Ruby Gem
 
 ## Installation
 
+Add this line to your application's Gemfile:
+
+    $ gem 'arcrest'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
     $ gem install arcrest
 
+
 ## Usage
 
-TODO: Write usage instructions here
+The API defines a [resource heirarchy](http://services.arcgisonline.com/arcgis/sdk/rest/#/Resource_hierarchy) which includes a Catalog of Services (MapServer or FeatureServer). Services have one or more Layers and Layers have Features, which may be queried in various ways, including by spatial coordinates.
+
+```ruby
+require 'arcrest'
+
+catalog = ArcREST::Catalog.new('http://rmgsc.cr.usgs.gov/arcgis/rest/services')
+puts catalog.services
+#=> {"name"=>"cwqdr_main", "type"=>"MapServer"}
+#=> {"name"=>"ecosys_Africa", "type"=>"MapServer"}
+#=> {"name"=>"ecosys_SA", "type"=>"MapServer"}
+#=> ...
+
+service = ArcREST::Service.new('http://rmgsc.cr.usgs.gov/arcgis/rest/services/geomac_fires/FeatureServer')
+puts service.layers
+#=> {"id"=>1, "name"=>"Large Fire Points"}
+#=> {"id"=>2, "name"=>"Fire Perimeters"}
+#=> {"id"=>3, "name"=>"MODIS Thermal Satellite"}
+#=> {"id"=>4, "name"=>"Inactive Fire Perimeters"}
+
+layer = ArcREST::Layer.new("#{service.url}/2")
+puts layer.name
+#=> Fire Perimeters
+puts layer.type
+#=> Feature Layer
+puts layer.count
+#=> 14 # count of the layer's features
+puts layer.object_ids.inspect
+#=> [681, 682, 688, 690, 614, 618, 619, 653, 683, 684, 685, 686, 687, 689]
+puts layer.fields
+#=> {"name"=>"objectid", "type"=>"esriFieldTypeOID", "alias"=>"OBJECTID", "domain"=>nil, "editable"=>false, "nullable"=>false}
+#=> {"name"=>"agency", "type"=>"esriFieldTypeString", "alias"=>"agency", "domain"=>nil, "editable"=>true, "nullable"=>true, "length"=>15}
+#=> ...
+```
+
+Once you have a Layer object, you can query it's features. The [documention](http://services.arcgisonline.com/arcgis/sdk/rest/index.html#/Query_Feature_Service_Layer/) shows the possibilities. Here is a very simple example:
+
+```ruby
+features = layer.features(where: "agency='BLM'", returnGeometry: false)
+puts features.count
+#=> 2
+puts features.first
+#=> {"objectid"=>690, "agency"=>"BLM", "comments"=>" ", "active"=>"Y"...
+```
+
+```features``` takes an options hash of API call params. Invalid key values raise an error. Valid params for the server can be listed like this:
+```ruby
+puts layer.valid_opts.inspect
+#=> ["dbVersion", "distance", "geometry", "geometryPrecision"...
+```
+or by consulting the [docs](http://services.arcgisonline.com/arcgis/sdk/rest/index.html#/Query_Feature_Service_Layer/). One default is set: ```outFields: '*'``` - which requests data for all fields.
+
+
+The ```:where``` key is used with any valid SQL to query the layer fields. The default is '1=1' which returns all records (up to the ```@max_record_count``` value, usually 1,000). An InvalidQuery error is raised if the server gives a 400 error of this form:
+```json
+{
+  "error": {
+    "code": 400,
+    "message": "Unable to complete operation.",
+    "details": [
+      "Unable to perform query operation.",
+      "Invalid query"
+    ]
+  }
+}
+```
+
+
+## Specification & Tests
+
+Full specification documentation is available for each build at [Travis](https://travis-ci.org/MatzFan/ArcREST). To run the tests yourself clone this repo and run:
+
+    $ rake spec
 
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/arcrest. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/MatzFan/arcrest
 
 
 ## License

data/arcrest.gemspec

@@ -24,4 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.12'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'guard', '~> 2.14'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+  spec.add_development_dependency 'ruby_gntp', '~> 0.3' # guard notifications
 end

data/lib/arcrest/attributable.rb

@@ -0,0 +1,20 @@
+# adds ability to dynamically set instance vars & accessors
+module Attributable
+  def create_method(name, &block)
+    self.class.send(:define_method, name.to_sym, &block)
+  end
+
+  def create_setter(m)
+    create_method("#{m}=".to_sym) { |v| instance_variable_set("@#{m}", v) }
+  end
+
+  def create_getter(m)
+    create_method(m.to_sym) { instance_variable_get("@#{m}") }
+  end
+
+  def set_attr(method, value)
+    create_setter(method)
+    send "#{method}=".to_sym, value
+    create_getter(method)
+  end
+end

data/lib/arcrest/catalog.rb

@@ -0,0 +1,19 @@
+module ArcREST
+  # a catalog of services
+  class Catalog < Server
+    attr_reader :folders, :services
+
+    def initialize(url)
+      super
+      @services = services
+    end
+
+    def folders
+      @json['folders']
+    end
+
+    def services
+      @json['services']
+    end
+  end
+end

data/lib/arcrest/layer.rb

@@ -0,0 +1,91 @@
+module ArcREST
+  class InvalidOption < StandardError; end
+  class InvalidQuery < StandardError; end
+  # a layer
+  class Layer < Server
+    include Attributable
+
+    ERR = 'error'.freeze
+    ATTRIBUTES = %w(id name type drawing_info fields max_record_count).freeze
+    DEFAULT_PARAMS = { where: '1=1', outFields: '*' }.freeze
+    PARAMS = %w(distance geometry geometryType inSR objectIds
+                outFields outSR relationParam returnDistinceValues
+                returnIdsOnly spatialRel time where).freeze
+    PARAMS_SP1 = %w(returnCountOnly).freeze
+    PARAMS_10_1 = %w(dbVersion geometryPrecision groupByFieldsForStatistics
+                     maxAllowableOffset multiPatchOption orderByFields
+                     outStatistics returnGeometry returnM returnZ).freeze
+    PARAMS_10_3 = %w(returnExtentOnly resultOffset resultRecordCount).freeze
+
+    attr_reader :valid_params # other accessors set in constructor
+
+    def initialize(url)
+      super
+      generate_attributes # dynamically create & assign values to attributes :)
+    end
+
+    def count
+      @version > 10 ? count_only_true : object_ids.count # v10.1 onwards
+    end
+
+    def object_ids # care - must specify outFields to overide default '*'
+      query(outFields: nil, returnIdsOnly: true)['objectIds']
+    end
+
+    def features(options = {})
+      query(options)['features']
+    end
+
+    def valid_opts
+      return PARAMS if @version < 10 || @version == 10.0
+      return (PARAMS + PARAMS_SP1).sort if @version < 10.1
+      return (PARAMS + PARAMS_SP1 + PARAMS_10_1).sort if @version < 10.2
+      (PARAMS + PARAMS_SP1 + PARAMS_10_1 + PARAMS_10_3).sort
+    end
+
+    private
+
+    def generate_attributes
+      ATTRIBUTES.each { |name| set_attr(name, json_value(name)) }
+    end
+
+    def json_value(name)
+      @json[camelify(name)]
+    end
+
+    def camelify(name)
+      words = name.split('_')
+      words[1..-1].map(&:capitalize).unshift(words.first).join
+    end
+
+    def query(options)
+      validate(options.keys.map(&:to_s).sort)
+      valid_resp(build_uri, DEFAULT_PARAMS.merge(options))
+    end
+
+    def valid_resp(uri, opts)
+      raise InvalidQuery, m(opts) if (resp = json(uri, opts)).keys.include? ERR
+      resp
+    end
+
+    def m(options)
+      "The following query parameters resulted in a 400 response:\n#{options}"
+    end
+
+    def validate(keys)
+      keys.all? { |k| raise InvalidOption, msg(k) unless valid_opts.include? k }
+    end
+
+    def msg(key)
+      "'#{key}' is an invalid option, valid query options are:\n#{PARAMS}"
+    end
+
+    def count_only_true
+      query(returnCountOnly: true)['count']
+    end
+
+    def build_uri
+      URI::HTTP.build(host: @uri.host, path: "#{@uri.path}/query")
+    end
+  end
+end

data/lib/arcrest/server.rb

@@ -0,0 +1,48 @@
+require 'net/http'
+require 'json'
+
+module ArcREST
+  # adds metadata method
+  class Server
+    REGEX = %r{^\/arcgis\/rest\/services}i
+    BAD_ENDPOINT = 'Invalid ArcGIS endpoint'.freeze
+
+    attr_reader :url, :json, :version
+
+    def initialize(url)
+      @url = url
+      @uri = uri
+      @server_uri = server_uri
+      @json = json(@uri)
+      @version = version
+    end
+
+    def json(uri, options = {})
+      JSON.parse get(uri, options)
+    end
+
+    def version
+      json(server_uri)['currentVersion'] # subclasses use server uri
+    end
+
+    protected
+
+    def uri
+      raise ArgumentError, BAD_ENDPOINT if (URI(@url).path =~ REGEX) != 0
+      URI @url
+    end
+
+    def server_uri
+      URI::HTTP.build(host: @uri.host, path: '/arcgis/rest/services')
+    end
+
+    def add_json_param_to(hash)
+      { f: 'pjson' }.merge(hash) # 'pjson' guarantees id's unique
+    end
+
+    def get(uri, options = {})
+      uri.query = URI.encode_www_form(add_json_param_to(options))
+      Net::HTTP.get uri
+    end
+  end
+end

data/lib/arcrest/service.rb

@@ -0,0 +1,25 @@
+module ArcREST
+  # a FeatureService or a MapService
+  class Service < Server
+    attr_reader :max_record_count, :capabilities, :layers
+
+    def initialize(url)
+      super
+      @max_record_count = max_record_count # may be nil
+      @capabilities = capabilities # may be empty
+      @layers = layers # may be empty
+    end
+
+    def max_record_count
+      @json['maxRecordCount']
+    end
+
+    def capabilities
+      @json['capabilities'] ? @json['capabilities'].split(',') : nil
+    end
+
+    def layers
+      @json['layers']
+    end
+  end
+end

data/lib/arcrest/version.rb

@@ -1,3 +1,3 @@
 module ArcREST
-  VERSION = '0.0.0.pre'.freeze
+  VERSION = '0.0.1'.freeze
 end

data/lib/arcrest.rb

@@ -1,6 +1,9 @@
+require 'arcrest/attributable' # module
 require 'arcrest/version'
+require 'arcrest/server'
+require 'arcrest/catalog'
+require 'arcrest/service'
+require 'arcrest/layer'
 
 # namespace
-module ArcREST
-  # Your code goes here...
-end
+module ArcRest; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arcrest
 version: !ruby/object:Gem::Version
-  version: 0.0.0.pre
+  version: 0.0.1
 platform: ruby
 authors:
 - Bruce Steedman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-27 00:00:00.000000000 Z
+date: 2016-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: ruby_gntp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 description: Wrapper for ArcGIS REST API
 email:
 - bruce.steedman@gmail.com
@@ -63,6 +105,7 @@ files:
 - ".rspec"
 - ".travis.yml"
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -70,6 +113,11 @@ files:
 - bin/console
 - bin/setup
 - lib/arcrest.rb
+- lib/arcrest/attributable.rb
+- lib/arcrest/catalog.rb
+- lib/arcrest/layer.rb
+- lib/arcrest/server.rb
+- lib/arcrest/service.rb
 - lib/arcrest/version.rb
 homepage: https://github.com/MatzFan/arcrest
 licenses:
@@ -86,12 +134,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.2
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Wrapper for ArcGIS REST API