cocoadex 1.2 → 1.3

data/bin/cocoadex

@@ -10,35 +10,43 @@ include Cocoadex
 
 logger.error_level = Logger::ERROR
 
-main do |arg|
-  if options[:verbose]
-    logger.error_level = Logger::DEBUG
-  end
-
-  if options[:'load-docset'] and path = File.expand_path(options[:'load-docset'].first)
-    Parser.parse(path)
-  end
-
-  if options[:search] and text = options[:search].first
+main do |query|
+
+  logger.error_level = Logger::DEBUG if options[:verbose]
+
+  if options[:configure]
+    DocSetHelper.search_and_index
+  elsif options[:'load-docset']
+    paths = options[:'load-docset'].map do |p|
+      File.expand_path(p)
+    end.uniq
+    DocSetHelper.search_and_index(paths)
+  elsif query
     if Keyword.loaded?
       logger.debug "Loading index..."
       Keyword.read
-      Cocoadex.search(text, options[:first])
+      Cocoadex.search(query, options[:first])
     else
-      puts "No DocSets loaded"
+      puts "No DocSets loaded. Run `cocodex --configure` to search for existing DocSets."
     end
+  else
+    help_now! "No options or query specified"
   end
 end
 
 version Cocoadex::VERSION
 description 'A Class Reference Utility for Cocoa APIs'
 
+arg :query, :optional
+
 on("--verbose","Be verbose")
+
+on("--configure","Index all DocSets in default locations")
+
 on("--first","Load first result when multiple matches exist")
 
 on("-d DOCSET","--load-docset","Load a DocSet into the datastore",/^(.*)$/)
-on("-s QUERY","--search","Search the index",/^(.*)$/)
 
-# todo: support --platform, --platform-version, --language, --first, --force
+# todo: support --platform, --platform-version, --format [format]
 
 go!

data/bin/cocoadex_completion.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env sh
+#
+# cocoadex_completion.sh
+#
+# Bash completion for Cocoa classes
+# Install by adding the following to your .bash_profile:
+#
+# complete -C /path/to/cocoadex_completion.sh -o default cocoadex
+
+/usr/bin/env ruby <<-EORUBY
+
+require 'cocoadex'
+
+class TagCompletion
+  def initialize(command)
+    @command = command
+  end
+
+  def matches
+    tags.select do |tag|
+      tag[0, typed.length] == typed
+    end
+  end
+
+  def typed
+    @command[/\s(.+?)$/, 1] || ''
+  end
+
+  def tags
+    @tags ||= Cocoadex::Keyword.tags
+  end
+end
+
+puts TagCompletion.new(ENV["COMP_LINE"]).matches
+
+EORUBY

data/changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.3
+
+ - Added `--configure` command, for finding and indexing
+   any docsets in preset default locations
+ - Search term is now an argument, so no need for `-s`
+ - Added example script for enabling bash completion on
+   class and method names
+ - Accept multiple arguments for the `--load-docset` option
+
 ## 1.2
 
  - Fix docset loading regression introduced in 1.1

data/lib/cocoadex/docset_helper.rb

@@ -0,0 +1,51 @@
+
+module Cocoadex
+  class DocSetHelper
+
+    ROOT_PATHS = [
+      '~/Library/Developer/Documentation/DocSets',
+      '~/Library/Developer/Shared/Documentation/DocSets',
+      '/Applications/Xcode.app/Contents/Developer/Documentation/DocSets',
+      '/Applications/Xcode.app/Contents/Developer/Platforms/*/Developer/Documentation/DocSets'
+    ]
+
+    def self.data_path
+      Cocoadex.config_file("data/docsets.blob")
+    end
+
+    def self.docset_paths
+      @paths ||= begin
+        ROOT_PATHS.map { |path| Dir.glob(File.expand_path(path)+'/*/') }.flatten
+      end
+    end
+
+    def self.search_and_index paths=docset_paths
+      docsets = []
+      paths.map do |path|
+        if docset = Parser.parse(path)
+          docsets << docset
+        end
+      end
+
+      if docsets.size > 0
+        Keyword.write(:overwrite)
+        Keyword.generate_tags!
+        write(docsets)
+      end
+      logger.info "Done! #{docsets.size} DocSet#{docsets.size == 1 ? '':'s'} indexed."
+    end
+
+    def indexed_docsets
+      @docsets ||= Serializer.read(data_path)
+    end
+
+    def self.read
+      @docsets = Serializer.read(data_path)
+    end
+
+    def self.write docsets
+      @docsets = docsets
+      Serializer.write(data_path, docsets, :overwrite)
+    end
+  end
+end

data/lib/cocoadex/keyword.rb

@@ -6,10 +6,6 @@ module Cocoadex
     attr_reader :term, :type, :docset, :url
     attr_accessor :fk, :id
 
-    # Cache storage location
-    DATA_PATH = File.expand_path("~/.cocoadex/data/store.blob")
-
-    SEPARATOR = "--__--"
     CLASS_METHOD_DELIM = '+'
     INST_METHOD_DELIM  = '-'
     CLASS_PROP_DELIM   = '.'
@@ -19,15 +15,28 @@ module Cocoadex
       @store ||= []
     end
 
+    # Cache storage location
+    def self.data_path
+      Cocoadex.config_file("data/store.blob")
+    end
+
+    def self.tags_path
+      Cocoadex.config_file("tags")
+    end
+
     # Search the cache for matching text
     def self.find text
       if scope = SCOPE_CHARS.detect {|c| text.include? c }
         class_name, term = text.split(scope)
+        logger.debug "Searching scope: #{scope}, #{class_name}, #{term}"
         find_with_scope scope, class_name, term
       else
+        logger.debug "Searching Keyword datastore (#{datastore.size}): #{text}"
         keys = datastore.select {|k| k.term.start_with? text }
+        logger.debug "#{keys.size} keys found"
         if key = keys.detect {|k| k.term == text }
           keys = [key]
+          logger.debug "Exact match!"
         end
         untokenize(keys)
       end
@@ -53,30 +62,36 @@ module Cocoadex
 
     # Are any docsets loaded into the cache?
     def self.loaded?
-      File.exists? DATA_PATH
+      File.exists? data_path
     end
 
     # Read a serialized cache file into an Array
     def self.read
-      $/=SEPARATOR
-      File.open(DATA_PATH, "r").each do |object|
-        datastore << Marshal::load(object)
-      end
+      @store = Serializer.read(data_path)
+      logger.debug "Loaded #{datastore.size} tokens"
     end
 
     # Write a cache Array as a serialized file
-    def self.write
-      unless File.exists? File.dirname(DATA_PATH)
-        FileUtils.mkdir_p File.dirname(DATA_PATH)
-      end
-      File.open(DATA_PATH, "w") do |file|
-        datastore.each do |keyword|
-          file.print(Marshal.dump(keyword))
-          file.print SEPARATOR
+    def self.write style
+      Serializer.write(data_path, datastore, style)
+    end
+
+    def self.tags
+      @tags ||= begin
+        if File.exists? tags_path
+          IO.read(tags_path).split('\n')
+        else
+          []
         end
       end
     end
 
+    # Build a tags file from existing kewords
+    def self.generate_tags!
+      text = datastore.map {|k| k.term }.join('\n')
+      Serializer.write_text tags_path, text
+    end
+
     # Create Cocoadex model objects for Keyword references
     def self.untokenize keys
       keys.map do |key|
@@ -86,6 +101,7 @@ module Cocoadex
         when :method, :property
           if class_key = datastore.detect {|k| k.id == key.fk}
             klass = Cocoadex::Class.new(class_key.url)
+            logger.debug "Searching #{key.type} list of #{klass.name}"
             list = key.type == :method ? klass.methods : klass.properties
             list.detect {|m| m.name == key.term}
           end

data/lib/cocoadex/models/docset.rb

@@ -4,12 +4,12 @@ module Cocoadex
     attr_reader :platform, :version, :name, :description, :path
 
     def initialize plist_path
-      @doc = Nokogiri::HTML(IO.read(plist_path))
+      doc = Nokogiri::HTML(IO.read(plist_path))
       @path = plist_path
-      @name = plist_value 'CFBundleName'
-      @platform = plist_value "DocSetPlatformFamily"
-      @version = plist_value "DocSetPlatformVersion"
-      @description = plist_value "DocSetDescription"
+      @name = plist_value doc, 'CFBundleName'
+      @platform = plist_value doc, "DocSetPlatformFamily"
+      @version = plist_value doc, "DocSetPlatformVersion"
+      @description = plist_value doc, "DocSetDescription"
     end
 
     def inspect
@@ -18,15 +18,15 @@ module Cocoadex
 
     private
 
-    def plist_value key
-      key_node = @doc.css("dict key").detect do |node|
+    def plist_value doc, key
+      key_node = doc.css("dict key").detect do |node|
         node.text == key
       end
 
       if key_node
         key_node.next.text
       else
-        logger.iwarn "Node not found: #{key}"
+        logger.debug "Node not found: #{key}"
         nil
       end
     end

data/lib/cocoadex/models/method.rb

@@ -36,27 +36,26 @@ module Cocoadex
         @scope  = type
         @name   = node.css("h3.#{type}Method").first.text
         logger.debug("parsing #{@type} method #{@name}")
+
         @abstract = node.css(".abstract").first.text
         @declaration = node.css(".declaration").first.text
 
         decl_nodes = node.css(".declaredIn code.HeaderFile")
-        if decl_nodes.size > 0
-          @declared_in = decl_nodes.first.text
-        end
+        @declared_in = decl_nodes.first.text if decl_nodes.size > 0
 
-        if discussion_node = node.css(".discussion > p") and discussion_node.length > 0
-          @discussion = discussion_node.first.text
-        end
+        discussion_node = node.css(".discussion > p")
+        @discussion = discussion_node.first.text if discussion_node.length > 0
 
-        if return_nodes = node.css(".return_value p") and return_nodes.size > 0
-          @return_value = return_nodes.first.text
-        end
+        return_nodes = node.css(".return_value p")
+        @return_value = return_nodes.first.text if return_nodes.size > 0
 
         ava_nodes = node.css(".availability > ul > li")
-        if ava_nodes.size > 0
-          @availability = ava_nodes.first.text
-        end
+        @availability = ava_nodes.first.text if ava_nodes.size > 0
+
+        parse_parameters(node)
+      end
 
+      def parse_parameters node
         if parameters = node.css(".parameters") and parameters.length > 0
           @parameters = []
           parameters.first.css("dt").each do |param|

data/lib/cocoadex/parser.rb

@@ -25,11 +25,15 @@ module Cocoadex
       title.include? "Class Reference" or title.include? "Protocol Reference"
     end
 
+    def self.deprecated? title
+      title =~ /^Deprecated ([A-Za-z]+) Methods$/
+    end
+
     def self.parse docset_path
-      logger.info "Parsing docset tokens (This may take a moment)..."
       plist = File.join(docset_path,"Contents", "Info.plist")
       if File.exist? plist
         docset = DocSet.new(plist)
+        logger.info "Parsing docset tokens in #{docset.name}. This may take a moment..."
 
         files = Dir.glob(docset_path+"/**/*.html")
         files.reject! {|f| ignored?(f) }
@@ -37,8 +41,8 @@ module Cocoadex
           index_html(docset,f,i)
         end
 
-        logger.info "Tokens Indexed: #{Keyword.datastore.size}"
-        Keyword.write
+        logger.info "  Tokens Indexed: #{Keyword.datastore.size}"
+        docset
       end
     end
 
@@ -51,7 +55,7 @@ module Cocoadex
         title = title_nodes.first['content']
 
         if class_ref? title
-          # logger.info "Caching #{title}"
+          logger.debug "Caching #{title}"
           Keyword.tokenize_class docset.name, path, index
         end
       end

data/lib/cocoadex/serializer.rb

@@ -0,0 +1,49 @@
+
+module Cocoadex
+  class Serializer
+    SEPARATOR = "--__--"
+
+    # Read a serialized cache file into an Array
+    def self.read path
+      $/=SEPARATOR
+      array = []
+      File.open(path, "r").each do |object|
+        array << Marshal::load(object)
+      end
+      array
+    end
+
+    def self.check_path path
+      unless File.exists? File.dirname(path)
+        FileUtils.mkdir_p File.dirname(path)
+      end
+    end
+
+    # Write text to a file
+    def self.write_text path, text
+      check_path path
+      File.open(path, 'w') do |file|
+        file.print text
+      end
+    end
+
+    # Write a cache Array as a serialized file
+    def self.write path, array, style
+      check_path path
+
+      mode = case style
+        when :append then 'a'
+        when :overwrite then 'w'
+        else
+          raise "Unknown file mode: #{style}"
+      end
+
+      File.open(path, mode) do |file|
+        array.each do |object|
+          file.print(Marshal.dump(object))
+          file.print SEPARATOR
+        end
+      end
+    end
+  end
+end

data/lib/cocoadex/version.rb

@@ -1,3 +1,3 @@
 module Cocoadex
-  VERSION = "1.2"
+  VERSION = "1.3"
 end

data/lib/cocoadex.rb

@@ -1,6 +1,8 @@
 
 require 'erb'
 require 'bri'
+require 'cocoadex/docset_helper'
+require 'cocoadex/serializer'
 require 'cocoadex/version'
 require 'cocoadex/templates'
 require 'cocoadex/models/docset'
@@ -19,6 +21,8 @@ module Cocoadex
 
   DEFAULT_WIDTH = 72
 
+  CONFIG_DIR=File.expand_path("~/.cocoadex")
+
   # output documentation text for a given search term
   def self.search term, load_first=false
     term = term.strip
@@ -44,6 +48,11 @@ module Cocoadex
     @width = width
   end
 
+  # path to a file in the default configuration directory
+  def self.config_file subpath
+    File.expand_path(File.join(Cocoadex::CONFIG_DIR,subpath))
+  end
+
   # add leading whitespace to lines
   def self.indent text, level=2
     text.split("\n").collect {|row| "#{' '*level}#{row}"}.join("\n" )

data/readme.md

@@ -4,24 +4,53 @@ Documentation lookup for Cocoa APIs, in the spirit of RI
 
 Cocoadex parses Cocoa documentation files and creates a keyword index. Queries can then be run against the index for fast documentation lookup.
 
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/kattrali/cocoadex)
+
+
 ## Installation
 
     gem install cocoadex
 
+## Configuration
+
+Load any DocSets in known locations:
+
+    cocoadex --configure
+
 ## Usage
 
- - **View Options:** `cocoadex --help`
+### View Options
+
+    cocoadex --help
+
+
+### Loading a Custom DocSet
+
+    cocoadex --load-docset [path] --load-docset [path2] ...
+
+
+### Look up Documentation
+
+    cocoadex [query]
+
+Valid search terms are Class, method, and property names. Search scope can also be focused using delimiters, such as `ClassName-method` to find instance methods, `Class+method` to find class methods, or `Class.method` to find any matching method or property in `Class`.
+
+
+## Enabling Tab Completion
+
+Cocoadex generates a tags file of all indexed search terms during configuration. Enable tab completion for bash by linking/saving `bin/cocoadex_completion.sh` and adding the following to your .bash_profile (or similar):
+
+    complete -C /path/to/cocoadex_completion.sh -o default cocoadex
 
- - **Loading a DocSet:** `cocoadex --load-docset [path]` (Try `~/Library/Developer/Shared/Documentation/DocSets/[docset name]`)
 
- - **Look up Documentation:** `cocoadex --search [query]`
-   - Valid search terms are Class, method, and property names. Search scope can also be focused using delimiters, such as `ClassName-method` to find instance methods, `Class+method` to find class methods, or `Class.method` to find any matching method or property in `Class`.
+I wish I knew how to get this working with zsh too.
 
+## Example Output
 
-*Property Lookup Example*
+### Property Lookup Example
 
 <pre>
-$ cocoadex -s tableView
+$ cocoadex tableView
 
 -------------------------------------------------------------- tableView
                                                  (UITableViewController)
@@ -34,10 +63,10 @@ Available in iOS 2.0 and later.
 </pre>
 
 
-*Method Lookup Example*
+### Method Lookup Example
 
 <pre>
-$ cocoadex -s tableView:viewForFoo
+$ cocoadex tableView:viewForFoo
 
 -------------------------------------- tableView:viewForFooterInSection:
                                                    (UITableViewDelegate)
@@ -60,10 +89,10 @@ Parameters:
 Available in iOS 2.0 and later.
 </pre>
 
-*Class Lookup Example (Clipped for brevity)*
+### Class Lookup Example (Clipped for brevity)
 
 <pre>
-$ cocoadex -s UILabel
+$ cocoadex UILabel
 
 --------------------------------------------------------- Class: UILabel
                                        (UIView > UIResponder > NSObject)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cocoadex
 version: !ruby/object:Gem::Version
-  version: '1.2'
+  version: '1.3'
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-19 00:00:00.000000000 -04:00
-default_executable: 
+date: 2012-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &10672660 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +21,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *10672660
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &10672100 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,10 +37,15 @@ dependencies:
         version: 0.9.2
   type: :development
   prerelease: false
-  version_requirements: *10672100
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
 - !ruby/object:Gem::Dependency
   name: methadone
-  requirement: &10671500 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -44,10 +53,15 @@ dependencies:
         version: 1.2.1
   type: :runtime
   prerelease: false
-  version_requirements: *10671500
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.1
 - !ruby/object:Gem::Dependency
   name: term-ansicolor
-  requirement: &10671060 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +69,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *10671060
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bri
-  requirement: &10670580 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +85,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *10670580
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &10670020 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,12 +101,18 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *10670020
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A command-line class reference utility Cocoa APIs
 email:
 - iskanamagus@gmail.com
 executables:
 - cocoadex
+- cocoadex_completion.sh
 extensions: []
 extra_rdoc_files:
 - readme.md
@@ -94,9 +124,12 @@ files:
 - changelog.md
 - readme.md
 - bin/cocoadex
+- bin/cocoadex_completion.sh
 - lib/cocoadex.rb
+- lib/cocoadex/docset_helper.rb
 - lib/cocoadex/keyword.rb
 - lib/cocoadex/parser.rb
+- lib/cocoadex/serializer.rb
 - lib/cocoadex/templates.rb
 - lib/cocoadex/version.rb
 - lib/cocoadex/models/class.rb
@@ -106,7 +139,6 @@ files:
 - lib/cocoadex/models/method.rb
 - lib/cocoadex/models/property.rb
 - lib/ext/nil.rb
-has_rdoc: true
 homepage: http://kattrali.github.com/cocoadex
 licenses: []
 post_install_message: 
@@ -127,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A command-line class reference utility for Cocoa APIs, based on RI.