retscli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 64bb6b1cc5838d8be49673141144e7273b4bfb7c
-  data.tar.gz: 1d8b9c3f187d02e7de06d7a2f69be987adb4c57b
+  metadata.gz: 9d3f0be17b3b7a93c8f2d63263c5b15c41fb33ac
+  data.tar.gz: 9a33fb19a66b9376b92daa6bf978ef6799a7fb26
 SHA512:
-  metadata.gz: f4f290c630981363f30220c14b11a9213fbb367f03ef87b5aa7c32f709a9b71e26acb800c39cefacc4ab18034446fc4e5132de29a19ff7667b83ab39a11a5625
-  data.tar.gz: 9349b62d0c680a86903829081fd1d43150f38894853449c8661e150946ef56f97975e107c57848959bdcdd4343ccd59d2bc5cf3717c372c184cb304015ce28b6
+  metadata.gz: 57050020e021497315530ff16078dd6bcf8fe306210250ed0df42ba317b7816bfcb4eb9196778de91adc68456a77fcce5c530edcf56c7a4a0396230fef29ddba
+  data.tar.gz: 935757b2d9d36faca77457689fe7e715a766221b24ca85ea0b0dcf868db9bbca3199f9adff22da9b2fa59e1d10afc966ed81e0101afb960be0210d94dffd6006

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
+before_install: gem install bundler -v 1.11

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 0.2.0
+- Ability to search resources
+- Better error handling
+- Debug mode
+- Ability to login inside console incase session becomes invalid
+- Fix user agent password flag

data/README.md

@@ -1,16 +1,28 @@
-# Retscli
+# retscli
+
+[![Gem Version](https://badge.fury.io/rb/retscli.svg)](https://badge.fury.io/rb/retscli)
+[![Build Status](https://travis-ci.org/summera/retscli.svg?branch=master)](https://travis-ci.org/summera/retscli)
+
 CLI for querying RETS servers and searching metadata.
 
 This gem is built on top of the [rets](http://github.com/estately/rets) gem, which handles the actual querying and parsing of the RETS server requests. Big thanks to the [Estately](http://www.estately.com) team for their work!
 
-![retscli gif](https://github.com/summera/gifs/blob/master/retscli/retscli.gif?raw=true)
+![retscli gif](https://github.com/summera/gifs/blob/master/retscli/search_metadata_cropped.gif?raw=true)
+![retscli png](https://github.com/summera/gifs/blob/master/retscli/search.png?raw=true)
 
 ## Installation
     $ gem install retscli
 
+## Features
+- Search metadata for keywords. Results are highlighted for readability.
+- Search resources. Results are displayed in a nicely formatted ascii table.
+- Open command results in your editor of choice.
+- Debug RETS requests and queries in debug mode.
+- Command results are paged using less by default.
+
 ## Usage
 
-#### Shell Commands
+#### CLI Commands
 ```bash
 $ retscli help
 Commands:
@@ -28,15 +40,20 @@ Usage:
   retscli console [LOGIN URL]
 
 Options:
-  -u, [--username=USERNAME]
-  -p, [--password=PASSWORD]
-  -v, [--version=VERSION]
-  -a, [--agent=AGENT]
-  -ap, [--ua-password=UA_PASSWORD]
+  -u, [--username=USERNAME]        # Username
+  -p, [--password=PASSWORD]        # Password
+  -v, [--version=VERSION]          # Rets version
+                                   # Default: RETS/1.7.2
+  -a, [--agent=AGENT]              # User agent
+  -t, [--ua-password=UA_PASSWORD]  # User agent password
+  -d, [--debug], [--no-debug]      # Debug mode
 
 Start rets console
 ```
 
+#### Debug Mode
+To view requests being made to the RETS server, enable debug mode with the `-d` flag. Once enabled, helpful info will be logged to `$stdout`. This is helpful to debug errors thrown by the RETS server and to adjust queries.
+
 #### Rets Console Commands
 After dropping into the RETS console, you get a bunch of useful commands for searching and exploring the RETS server
 
@@ -45,15 +62,17 @@ $ retscli console http://rets.server.com -u summera -p password
 
 summera@rets.server.com > help
 Commands:
-  capabilities               # Display capabilities for rets server
-  classes [RESOURCE]         # List available classes for resource
-  help [COMMAND]             # Describe available commands or one specific command
-  metadata                   # View metadata
-  objects [RESOURCE]         # List available objects for resource
-  resources                  # List available resources
-  search-metadata            # Search metadata tables
-  tables [RESOURCE] [CLASS]  # List available tables for class of resource
-  timezone-offset            # System timezone offset
+  capabilities                       # Display capabilities for rets server
+  classes [RESOURCE]                 # List available classes for resource
+  help [COMMAND]                     # Describe available commands or one specific command
+  login                              # Re-Login to RETS server. Use if session is no longer valid
+  metadata                           # View metadata
+  objects [RESOURCE]                 # List available objects for resource
+  resources                          # List available resources
+  search [RESOURCE] [CLASS] [QUERY]  # Search resources, e.g. properties, open houses, etc.
+  search-metadata                    # Search metadata tables
+  tables [RESOURCE] [CLASS]          # List available tables for class of resource
+  timezone-offset                    # System timezone offset
 ```
 
 Again, to see available flags/options, run help on the command. Many of the commands have an `editor` option if you feel the need to get down and dirty in your editor of choice.
@@ -75,11 +94,12 @@ Search metadata tables
 ## Notes
 - When opening output in your editor, retscli will check the `$EDITOR` environment variable. If this is not set, it falls back to nano.
 - Much of the output is piped through `less` by default to allow for easy paging. If you'd like to change this, set your preferred pager in the `$PAGER` environment variable.
-- Retscli uses the ruby readline module for the rets console
+- Retscli uses the ruby readline module for the rets console.
+- If any arguments and/or options have spaces in them, you will need to wrap them in quotes so that retscli does not split on the spaces.
 
 ## Contributing
 
-1. Fork it ( https://github.com/ianks/octodown/fork )
+1. Fork it ( https://github.com/summera/retscli/fork )
 1. Create your feature branch (`git checkout -b my-new-feature`)
 1. Commit your changes (`git commit -am 'Add some feature'`)
 1. Run the test suite (`bundle exec rake`)

data/lib/retscli.rb

@@ -9,11 +9,12 @@ module Retscli
   class Cli < Thor
 
     desc 'validate [LOGIN URL]', 'Validate rets credentials'
-    method_option :username, aliases: '-u'
-    method_option :password, aliases: '-p'
-    method_option :version, aliases: '-v'
-    method_option :agent, aliases: '-a'
-    method_option :ua_password, aliases: '-ap'
+    method_option :username, aliases: '-u', :desc => 'Username'
+    method_option :password, aliases: '-p', :desc => 'Password'
+    method_option :version, aliases: '-v', :desc => 'Rets version', :default => 'RETS/1.7.2'
+    method_option :agent, aliases: '-a', :desc => 'User agent'
+    method_option :ua_password, aliases: '-t', :desc => 'User agent password'
+    method_option :debug, :aliases => '-d', :desc => 'Debug mode', :type => :boolean, :default => false
     def validate(url)
       client = rets_client(url, options)
 
@@ -29,11 +30,12 @@ module Retscli
     end
 
     desc 'capabilities [LOGIN URL]', 'Display capabilities for rets server'
-    method_option :username, aliases: '-u'
-    method_option :password, aliases: '-p'
-    method_option :version, aliases: '-v'
-    method_option :agent, aliases: '-a'
-    method_option :ua_password, aliases: '-ap'
+    method_option :username, aliases: '-u', :desc => 'Username'
+    method_option :password, aliases: '-p', :desc => 'Password'
+    method_option :version, aliases: '-v', :desc => 'Rets version', :default => 'RETS/1.7.2'
+    method_option :agent, aliases: '-a', :desc => 'User agent'
+    method_option :ua_password, aliases: '-t', :desc => 'User agent password'
+    method_option :debug, :aliases => '-d', :desc => 'Debug mode', :type => :boolean, :default => false
     def capabilities(url)
       client = rets_client(url, options)
 
@@ -48,25 +50,29 @@ module Retscli
     end
 
     desc 'console [LOGIN URL]', 'Start rets console'
-    method_option :username, aliases: '-u'
-    method_option :password, aliases: '-p'
-    method_option :version, aliases: '-v'
-    method_option :agent, aliases: '-a'
-    method_option :ua_password, aliases: '-ap'
+    method_option :username, aliases: '-u', :desc => 'Username'
+    method_option :password, aliases: '-p', :desc => 'Password'
+    method_option :version, aliases: '-v', :desc => 'Rets version', :default => 'RETS/1.7.2'
+    method_option :agent, aliases: '-a', :desc => 'User agent'
+    method_option :ua_password, aliases: '-t', :desc => 'User agent password'
+    method_option :debug, :aliases => '-d', :desc => 'Debug mode', :type => :boolean, :default => false
     def console(url)
       client = rets_client(url, options)
       Retscli::Shell.new(client).start
     end
 
     no_commands do
-      def rets_client(url, params)
+      def rets_client(url, params={})
+        logger = options[:debug] ? Logger.new($stdout) : nil
+
         ::Rets::Client.new({
           :login_url => url,
           :username => params[:username],
           :password => params[:password],
           :version => params[:version],
           :agent => params[:agent],
-          :ua_password => params[:ua_password]
+          :ua_password => params[:ua_password],
+          :logger => logger
         })
       end
     end

data/lib/retscli/display_adapter.rb

@@ -2,11 +2,19 @@ require "terminal-table"
 
 module Retscli
   class DisplayAdapter
+    NO_RESULTS = 'No Results'.freeze
+    EMPTY_VALUE = '<empty>'.freeze
+
     def initialize(client)
       @client = client
       @colorer = ::Thor::Shell::Color.new
     end
 
+    def login
+      @client.login
+      set_color("\u2713 Logged in", :green)
+    end
+
     def capabilities
       Terminal::Table.new(:rows => @client.capabilities.to_a)
     end
@@ -108,6 +116,30 @@ module Retscli
       search_results
     end
 
+    def search(resource, klass, query, options={})
+      select = options[:select] ? options[:select].join(',') : ''
+      count = options[:count] ? 2 : 0
+
+      results = @client.find(
+        :all,
+        search_type: resource,
+        class: klass,
+        query: query,
+        select: select,
+        limit: options[:limit],
+        offset: options[:offset],
+        count: count,
+        format: options[:format],
+        no_records_not_an_error: true
+      )
+
+      if results.is_a?(Integer)
+        resource_table([{ 'count' => results }])
+      else
+        resource_table(results)
+      end
+    end
+
     def page(output)
       begin
         pager = ENV['PAGER'] || 'less'
@@ -122,6 +154,18 @@ module Retscli
     end
 
     private
+    def resource_table(results=[])
+      term_table = Terminal::Table.new
+      if results.empty?
+        term_table.rows = [[NO_RESULTS]]
+      else
+        term_table.headings = results.first.keys
+        term_table.rows = results.map{ |result| result.values.map!{ |value| value.to_s.empty? ? EMPTY_VALUE : value } }
+      end
+
+     term_table
+    end
+
     def open_tempfile_with_content(editor, initial_content)
       temp_file do |f|
         f.puts(initial_content)

data/lib/retscli/shell.rb

@@ -18,24 +18,24 @@ module Retscli
     end
 
     def start
-      begin
-        while line = readline_with_hist_management
-          if EXIT_COMMANDS.include?(line)
-            close
-          else
-            execute_shell_command(line)
-          end
+      while line = readline_with_hist_management
+        if EXIT_COMMANDS.include?(line)
+          close
+        else
+          execute_shell_command(line)
         end
-      rescue Interrupt
-        close
       end
     end
 
     # NOTE: this should probably be private, but making it public allowed
     # for easier testing without having to deal with mocking readline. Can we
     # find a better way?
-    def execute_shell_command(line)
-      Retscli::ShellCommands.start(split_line(line), :display_adapter => @display_adapter)
+    def execute_shell_command(line, out=$stdout)
+      begin
+        Retscli::ShellCommands.start(split_line(line), :display_adapter => @display_adapter)
+      rescue => e
+        out.puts @colorer.set_color(e.message, :red)
+      end
     end
 
     private
@@ -86,7 +86,13 @@ module Retscli
 
     def close
       system('stty', @stty_save)
-      @client.logout
+
+      begin
+        @client.logout
+      rescue => e
+        puts @colorer.set_color(e.message, :red)
+      end
+
       exit
     end
   end

data/lib/retscli/shell_commands.rb

@@ -17,6 +17,11 @@ module Retscli
       all_commands.keys.map{ |command| command.gsub('_', '-') }
     end
 
+    desc 'login', 'Re-Login to RETS server. Use if session is no longer valid'
+    def login
+      puts @display_adapter.login
+    end
+
     desc 'capabilities', 'Display capabilities for rets server'
     def capabilities
       @display_adapter.page(@display_adapter.capabilities)
@@ -97,5 +102,24 @@ module Retscli
     end
 
     map 'search-metadata' => :search_metadata
+
+    desc 'search [RESOURCE] [CLASS] [QUERY]', 'Search resources, e.g. properties, open houses, etc.'
+    method_option :limit, :aliases => '-l', :desc => 'limit', :type => :numeric, :default => 20
+    method_option :offset, :aliases => '-o', :desc => 'Offset', :type => :numeric
+    method_option :count, :aliases => '-c', :desc => 'Return result count', :type => :boolean, :default => false
+    method_option :select, :aliases => '-s', :desc => 'Select specific fields from records', :type => :array, :default => []
+    method_option :format, :aliases => '-f', :desc => 'Rets data return format', :enum => ['COMPACT', 'COMPACT-DECODED', 'STANDARD-XML'], :default => 'COMPACT-DECODED'
+    def search(resource, klass, query)
+      search_options = {
+        :limit => options[:limit],
+        :offset => options[:offset],
+        :count => options[:count],
+        :select => options[:select],
+        :format => options[:format]
+      }
+
+      results = @display_adapter.search(resource, klass, query, search_options)
+      @display_adapter.page(results)
+    end
   end
 end

data/lib/retscli/version.rb

@@ -1,3 +1,3 @@
 module Retscli
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: retscli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ari Summer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-12 00:00:00.000000000 Z
+date: 2016-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rets
@@ -117,6 +117,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md