cocoadex 1.4 → 1.5

data/lib/cocoadex/models/nested_node_element.rb

@@ -0,0 +1,17 @@
+
+module Cocoadex
+  # An element of a section where each item
+  # is divided into its own div element
+  class NestedNodeElement < Element
+
+    def parse_properties node
+      @abstract     = node.css(".abstract").first.text
+      @declaration  = node.css(".declaration").first.text
+      @declared_in  = node.css(".declaredIn code.HeaderFile").first.text
+      @discussion   = node.css(".discussion > p").first.text
+      @return_value = node.css(".return_value p").first.text
+      @return_value = nil if @return_value.empty?
+      @availability = node.css(".availability > ul > li").first.text
+    end
+  end
+end

data/lib/cocoadex/models/parameter.rb

@@ -0,0 +1,20 @@
+
+module Cocoadex
+  class Parameter
+    include Comparable
+
+    attr_reader :name, :description
+
+    def initialize name, description
+      @name, @description = name, description
+    end
+
+    def to_s
+      "#{name} - #{description}"
+    end
+
+    def <=> other
+      name <=> other.name if other.respond_to? :name
+    end
+  end
+end

data/lib/cocoadex/models/property.rb

@@ -1,8 +1,8 @@
 
 module Cocoadex
   # A Cocoa API class property
-  class Property < Element
-    TEMPLATE=Cocoadex::Templates::PROPERTY_DESCRIPTION
+  class Property < NestedNodeElement
+    TEMPLATE_NAME=:property
 
     attr_reader :abstract, :declaration, :discussion,
       :availability, :parent
@@ -10,23 +10,8 @@ module Cocoadex
     def initialize parent_class, node
       @parent = parent_class
       @name   = node.css("h3.method_property").first.text
-      logger.debug("Adding property: #{@name}")
 
-      if abs = node.css(".abstract") and abs.length > 0
-        @abstract = abs.first.text
-      end
-
-      if decl = node.css(".declaration") and decl.length > 0
-        @declaration = decl.first.text
-      end
-
-      if disc = node.css(".discussion > p") and disc.length > 0
-        @discussion = disc.first.text
-      end
-
-      if ava_nodes = node.css(".availability > ul > li") and ava_nodes.size > 0
-        @availability = ava_nodes.first.text
-      end
+      parse_properties(node)
     end
 
     def origin

data/lib/cocoadex/models/result_code.rb

@@ -0,0 +1,17 @@
+
+module Cocoadex
+  class ResultCode < Element
+    TEMPLATE_NAME=:result_code
+
+    attr_reader :value, :description
+
+    def initialize origin, name, value, description
+      @origin = origin
+      @name, @value, @description = name, value, description
+    end
+
+    def origin
+      @origin
+    end
+  end
+end

data/lib/cocoadex/models/seq_node_element.rb

@@ -0,0 +1,53 @@
+
+module Cocoadex
+  # An element of a section where each item
+  # is divided by anchor tags
+  class SequentialNodeElement < Element
+    Abstract     = ->(node) { node.classes.include? "abstract"     }
+    Declaration  = ->(node) { node.classes.include? "declaration"  }
+    ReturnValue  = ->(node) { node.classes.include? "return_value" }
+    Discussion   = ->(node) { node.classes.include? "discussion"   }
+    Availability = ->(node) { node.classes.include? "availability" }
+    DeclaredIn   = ->(node) { node.classes.include? "declaredIn"   }
+    Special      = ->(node) { node.classes.include? "specialConsiderations" }
+
+    def initialize origin, title_node
+      @origin = origin
+      @name = title_node.text
+      parse(title_node)
+    end
+
+    def origin
+      @origin
+    end
+
+    def parse title_node
+      prev_node = title_node
+      while node = prev_node.next and node.name != "a"
+        case node
+        when Abstract
+          @abstract = node.text
+        when Declaration
+          @declaration = node.text
+        when Availability
+          @availability = node.text.sub("Availability","")
+        when ReturnValue
+          @return_value = node.text.sub("Return Value","")
+        when Discussion
+          @discussion = node.text.sub("Discussion","")
+        when DeclaredIn
+          @declared_in = node.text.sub("Declared In","")
+        when Special
+          @considerations = node.text.sub("Special Considerations","")
+        else
+          handle_node(node)
+        end
+        prev_node = node
+      end
+    end
+
+    def handle_node node
+      logger.debug("Unhandled #{self.class} property: #{classes} => #{node.text}")
+    end
+  end
+end

data/lib/cocoadex/parser.rb

@@ -1,6 +1,12 @@
 
 module Cocoadex
+
+  # DocSet index and html documentation file parser
   class Parser
+    GenericReference  = ->(title) { title.include?("Reference") }
+    DeprecatedMethods = ->(title) { title =~ /^Deprecated ([A-Za-z]+) Methods$/ }
+    ClassReference    = ->(title) {
+      title.include?("Class Reference") or title.include?("Protocol Reference") }
 
     IGNORED_DIRS = [
       'codinghowtos', 'qa',
@@ -21,27 +27,22 @@ module Cocoadex
       (File.basename(path) == 'index.html' && File.exist?(File.join(File.dirname(path),'Reference')))
     end
 
-    def self.class_ref? title
-      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
       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) }
+        files = Dir.glob(docset_path+"/**/*.html").select {|f| not ignored?(f) }
+
+        pbar  = ProgressBar.new("#{docset.platform} #{docset.version}",files.size)
         files.each_with_index do |f,i|
           index_html(docset,f,i)
+          pbar.inc
         end
+        pbar.finish
 
-        logger.info "  Tokens Indexed: #{Keyword.datastore.size}"
+        logger.info "  Tokens Indexed: #{Tokenizer.tokens.size}"
         docset
       end
     end
@@ -50,13 +51,16 @@ module Cocoadex
       logger.debug "  Parsing path: #{path}"
 
       doc = Nokogiri::HTML(IO.read(path))
-      title_nodes = doc.css("#IndexTitle")
-      unless title_nodes.size == 0
-        title = title_nodes.first['content']
-
-        if class_ref? title
-          logger.debug "Caching #{title}"
-          Keyword.tokenize_class docset.name, path, index
+      if title = doc.css("#IndexTitle").first['content']
+        case title
+        when ClassReference
+          Tokenizer.tokenize_class(docset.name, path, index)
+        when GenericReference
+          Tokenizer.tokenize_ref(docset.name, path, index)
+        when DeprecatedMethods
+          # TODO
+        else
+          # TODO
         end
       end
     end

data/lib/cocoadex/serializer.rb

@@ -1,5 +1,7 @@
 
 module Cocoadex
+
+  # Move data to and from disk
   class Serializer
     SEPARATOR = "--__--"
 
@@ -13,6 +15,7 @@ module Cocoadex
       array
     end
 
+    # Ensure parent paths exist
     def self.check_path path
       unless File.exists? File.dirname(path)
         FileUtils.mkdir_p File.dirname(path)
@@ -20,23 +23,21 @@ module Cocoadex
     end
 
     # Write text to a file
-    def self.write_text path, text
+    def self.write_text path, text, style=:overwrite
       check_path path
+
+      mode = style_to_mode(style)
+
       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
+    def self.write_array path, array, style
       check_path path
 
-      mode = case style
-        when :append then 'a'
-        when :overwrite then 'w'
-        else
-          raise "Unknown file mode: #{style}"
-      end
+      mode = style_to_mode(style)
 
       File.open(path, mode) do |file|
         array.each do |object|
@@ -45,5 +46,14 @@ module Cocoadex
         end
       end
     end
+
+    def self.style_to_mode style
+      case style
+        when :append then 'a'
+        when :overwrite then 'w'
+        else
+          raise "Unknown file mode: #{style}"
+      end
+    end
   end
 end

data/lib/cocoadex/tokenizer.rb

@@ -0,0 +1,123 @@
+
+module Cocoadex
+  class Tokenizer
+
+    # Cache storage location
+    def self.data_path
+      Cocoadex.config_file("data/store.blob")
+    end
+
+    # All indexed searchable keys
+    def self.tokens
+      @store ||= loaded? ? Serializer.read(data_path) : []
+    end
+
+    # Find all tokens with a term identical to a string
+    def self.match text
+      subset_match(tokens, text)
+    end
+
+    # Find all tokens in a subset with a term identical
+    # to a string
+    def self.subset_match subset, text
+      subset.detect {|t| t.term == text }
+    end
+
+    # Find all tokens with a term at least starting with
+    # a text string. If there is an exact match, return
+    # it instead of the entire list
+    def self.fuzzy_match text
+      subset = tokens.select {|t| t.term.start_with? text }
+      if token = subset_match(subset, text)
+        [token]
+      else
+        subset
+      end
+    end
+
+    def self.persist
+      Serializer.write_array(data_path, tokens, :overwrite)
+    end
+
+    def self.loaded?
+      File.exists?(data_path)
+    end
+
+    # Find all searchable keywords in a class and
+    # add to cache
+    def self.tokenize_class docset, path, id
+      klass = Cocoadex::Class.new(path)
+      properties = {
+        :method   => klass.methods,
+        :property => klass.properties
+      }
+      tokenize(docset, klass, :class, id, properties)
+    end
+
+    # Find all searchable keywords in a reference
+    # and add to cache
+    def self.tokenize_ref docset, path, id
+      ref = Cocoadex::GenericRef.new(path)
+      properties = {
+        :constant    => ref.constants,
+        :data_type   => ref.data_types,
+        :result_code => ref.result_codes,
+        :const_group => ref.const_groups,
+        :function    => ref.functions,
+        :callback    => ref.callbacks
+      }
+      tokenize(docset, ref, :ref, id, properties)
+    end
+
+    # Create Cocoadex model objects from
+    # tokenized keywords references
+    def self.untokenize keys
+      keys.map do |key|
+        case key.type
+        when :class
+          Cocoadex::Class.new(key.url)
+        when :ref
+          Cocoadex::GenericRef.new(key.url)
+        when :data_type,   :result_code, :function,
+             :const_group, :constant, :callback
+
+          if class_key = tokens.detect {|k| k.id == key.fk}
+            ref = Cocoadex::GenericRef.new(class_key.url)
+            list = case key.type
+              when :result_code then ref.result_codes
+              when :data_type   then ref.data_types
+              when :const_group then ref.const_groups
+              when :constant    then ref.constants
+              when :function    then ref.functions
+              when :callback    then ref.callbacks
+            end
+            list.detect {|m| m.name == key.term}
+          end
+        when :method, :property
+          if class_key = tokens.detect {|k| k.id == key.fk}
+            klass = Cocoadex::Class.new(class_key.url)
+            list = key.type == :method ? klass.methods : klass.properties
+            list.detect {|m| m.name == key.term}
+          end
+        end
+      end
+    end
+
+    private
+
+    # Convert all elements into keyword tokens
+    def self.tokenize docset, entity, type, id, properties
+      key = Keyword.new(entity.name, type, docset, entity.path)
+      key.id = id
+      tokens << key
+
+      properties.each do |type, list|
+        list.each do |item|
+          item_key = Keyword.new(item.name, type, docset, entity.path)
+          item_key.fk = id
+          tokens << item_key
+        end
+      end
+    end
+  end
+end

data/lib/cocoadex/tools/completion_helper.rb

@@ -0,0 +1,84 @@
+
+module Cocoadex
+  class CompletionHelper
+    attr_reader :command
+
+    def initialize(command)
+      @command = command
+    end
+
+    def matches
+      scope = Keyword.get_scope(command)
+
+      CompletionHelper.tags.select do |tag|
+        tag[0, command.length] == command && Keyword.get_scope(tag) == scope
+      end
+    end
+
+    def scope_matches
+      scope = Keyword.get_scope(command)
+
+      CompletionHelper.tags.select do |tag|
+        Keyword.get_scope(tag) == scope
+      end
+    end
+
+    # Tags file location
+    def self.tags_path
+      Cocoadex.config_file("tags")
+    end
+
+    # Tags loaded from file
+    def self.tags
+      @tags ||= begin
+        if File.exists?(tags_path)
+          IO.read(tags_path, :mode => 'rb').split("\n")
+        else
+          []
+        end
+      end
+    end
+
+    # Clear all tags in file
+    def self.clear_tags
+      Serializer.write_text(tags_path, "")
+    end
+
+    # Build a tags file from existing kewords
+    def self.generate_tags!
+      logger.info "Generating tags file..."
+
+      datastore = Tokenizer.tokens.sort_by {|k| k.term }
+      text = datastore.map {|k| k.term }.join("\n") + "\n"
+
+      # Parse class elements and store tags for scope delimiters
+      datastore.select {|k| k.type == :class }.each_slice(50).to_a.each do |batch|
+        Tokenizer.untokenize(batch).each do |klass|
+          logger.debug("Tagging #{klass.name} properties")
+          text << tagify(
+            klass.name,
+            (klass.properties+klass.methods.to_a),
+            Keyword::CLASS_PROP_DELIM)
+          text << tagify(
+            klass.name,
+            klass.class_methods,
+            Keyword::CLASS_METHOD_DELIM)
+          text << tagify(
+            klass.name,
+            klass.instance_methods,
+            Keyword::INST_METHOD_DELIM)
+        end
+      end
+
+      Serializer.write_text(tags_path, text.strip)
+    end
+
+    private
+
+    def self.tagify class_name, properties, delimiter
+      properties.map {|p|
+          "#{class_name}#{delimiter}#{p.name}"
+      }.join("\n") + "\n"
+    end
+  end
+end

data/lib/cocoadex/version.rb

@@ -1,3 +1,3 @@
 module Cocoadex
-  VERSION = "1.4"
+  VERSION = "1.5"
 end

data/lib/cocoadex.rb

@@ -1,20 +1,17 @@
 
 require 'erb'
 require 'bri'
+require 'nokogiri'
 require 'cocoadex/docset_helper'
+require 'cocoadex/tokenizer'
 require 'cocoadex/serializer'
 require 'cocoadex/version'
-require 'cocoadex/templates'
-require 'cocoadex/models/docset'
-require 'cocoadex/models/element'
-require 'cocoadex/models/entity'
-require 'cocoadex/models/method'
-require 'cocoadex/models/property'
-require 'cocoadex/models/class'
+require 'cocoadex/model'
 require 'cocoadex/parser'
 require 'cocoadex/keyword'
-require 'ext/nil'
-require 'nokogiri'
+require 'cocoadex/tools/completion_helper'
+require 'extensions'
+require 'progressbar'
 require 'term/ansicolor'
 
 module Cocoadex
@@ -31,7 +28,7 @@ module Cocoadex
       elsif objects.size == 1 or load_first
         puts objects.first.print
       else
-        template = Cocoadex::Templates::MULTIPLE_CHOICES
+        template = IO.read(view_path('multiple'))
         puts ERB.new(template, nil, '<>').result(binding)
       end
     end
@@ -46,6 +43,11 @@ module Cocoadex
     Bri.width = width
   end
 
+  # retrieve a view template by name
+  def self.view_path name
+    File.join(File.dirname(__FILE__),'..','views',"#{name}.erb")
+  end
+
   # path to a file in the default configuration directory
   def self.config_file subpath
     File.expand_path(File.join(Cocoadex::CONFIG_DIR,subpath))

data/lib/ext/nil.rb

@@ -16,6 +16,9 @@ class NilClass
     []
   end
 
+  def each
+  end
+
   def next
     nil
   end

data/lib/ext/string.rb

@@ -0,0 +1,9 @@
+class String
+  def underscore
+    self.gsub(/::/, '/').
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    tr("-", "_").
+    downcase
+  end
+end

data/lib/ext/template_helpers.rb

@@ -0,0 +1,20 @@
+module Bri
+  module Templates
+    module Helpers
+      def wrap text
+        Bri::Renderer.wrap_row(text, Cocoadex.width)
+      end
+
+      def h3 text
+        Term::ANSIColor::blue + text + Term::ANSIColor::reset + "\n"
+      end
+
+      def inline_title title, value, alignment=0
+        length = alignment - title.length
+        buffer = length > 0 ? " "*length : ""
+        Term::ANSIColor::bold + title + ": " + Term::ANSIColor::reset + "#{buffer}#{value}\n"
+      end
+      module_function :h3, :inline_title, :wrap
+    end
+  end
+end

data/lib/ext/xml_element.rb

@@ -0,0 +1,10 @@
+
+module Nokogiri
+  module XML
+    class Element
+      def classes
+        (self['class'] || "").split(" ")
+      end
+    end
+  end
+end

data/readme.md

@@ -11,6 +11,10 @@ Cocoadex parses Cocoa documentation files and creates a keyword index. Queries c
 
     gem install cocoadex
 
+## Update
+
+    gem update cocoadex && cocoadex --configure
+
 ## Configuration
 
 Load any DocSets in known locations:
@@ -33,20 +37,44 @@ Load any DocSets in known locations:
 
     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`.
+#### Class Reference
+
+Valid search terms are Class, method, and property names. Search scope can also be focused using delimiters, such as `Class-method` to find instance methods, `Class+method` to find class methods, or `Class.method` to find any matching method or property in `Class`.
 
+#### Functions, Constants, Data Types, Callbacks, Structs...
+
+Valid search terms are function, constant, data type, callback and struct names, as well as constant groups (e.g. `cocoadex "Social Profile Keys"`).
 
 ## 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):
+Cocoadex generates a tags file of all indexed search terms during configuration.
+
+### Bash
+
+Enable tab completion for bash by linking/saving `tools/bash_completion.sh` and adding the following to your .bash_profile (or similar):
 
     complete -C /path/to/cocoadex_completion.sh -o default cocoadex
 
+### Z Shell
+
+Add the following to your `.zshrc` to enable tab completion for zsh:
+
+```sh
+
+_cocoadex() {
+    local cocoa_prefix
+    read -l cocoa_prefix
+    reply=(`cdex_completion "$cocoa_prefix"`)
+}
+
+compctl -K _cocoadex cocoadex
+```
+
 ## Example Output
 
 ### Property Lookup Example
 
-<pre>
+```sh
 $ cocoadex tableView
 
 -------------------------------------------------------------- tableView
@@ -57,12 +85,12 @@ $ cocoadex tableView
 Returns the table view managed by the controller object.
 
 Available in iOS 2.0 and later.
-</pre>
+```
 
 
 ### Method Lookup Example
 
-<pre>
+```sh
 $ cocoadex tableView:viewForFoo
 
 -------------------------------------- tableView:viewForFooterInSection:
@@ -84,11 +112,11 @@ Parameters:
     An index number identifying a section of tableView .
 
 Available in iOS 2.0 and later.
-</pre>
+```
 
 ### Class Lookup Example (Clipped for brevity)
 
-<pre>
+```sh
 $ cocoadex UILabel
 
 --------------------------------------------------------- Class: UILabel
@@ -110,4 +138,4 @@ Properties:
   numberOfLines, shadowColor, shadowOffset, text, textAlignment,
   textColor, userInteractionEnabled
 
-</pre>
+```