indexer 0.2.0 → 0.3.0

data/.index

@@ -1,22 +1,26 @@
 ---
-type: ruby
 revision: 2013
+type: ruby
 sources:
-- README.md
+- var
 authors:
 - name: trans
   email: transfire@gmail.com
-  website: http://trans.gihub.com/
+  website: http://trans.gihub.com
 - name: postmodern
-  website: http://postmodern.github.com/
-organizations: []
+  website: http://postmodern.github.com
+organizations:
+- name: Rubyworks
+  website: http://rubyworks.github.com
 requirements:
 - version: 1.5+
   name: nokogiri
 - version: 0.14+
   name: kramdown
-- version: 2.0+
-  optional: true
+- groups:
+  - optional
+  version: 2.0+
+  development: true
   name: redcarpet
 - groups:
   - test
@@ -25,7 +29,6 @@ requirements:
   name: qed
 - groups:
   - test
-  version: 0+
   development: true
   name: ae
 conflicts: []
@@ -39,20 +42,26 @@ resources:
   label: Source Code
 - type: api
   uri: http://rubydoc.info/gems/indexer/frames
-  label: API Reference
-repositories: []
+  label: API Guide
+repositories:
+- name: upstream
+  scm: git
+  uri: http://github.com/rubyworks/indexer/indexer.git
 categories:
 - metadata
-paths:
-  load:
-  - lib
 copyrights:
 - holder: Rubyworks
   year: '2012'
   license: BSD-2-Clause
-version: 0.2.0
+customs:
+- example
+paths:
+  lib:
+  - lib
 summary: Enable Your Project's Metadata
-description: Indexer provides projects with a universal metadata format.
-name: indexer
 title: Indexer
-date: '2012-12-27'
+version: 0.3.0
+name: indexer
+example: This is just an example of custom metadata.
+description: Indexer provides projects with a universal metadata format.
+date: '2013-01-20'

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--title 'Indexer Documentation'
+--private
+lib/**/*.rb
+-
+[A-Z]*.*

data/HISTORY.md

@@ -1,5 +1,24 @@
 # RELEASE HISTORY
 
+## 0.3.0 / 2012-01-19
+
+The 0.3 release makes three significant improvements. First, instead of
+using `paths['load']` for the Ruby load path setting, it designates the use
+of `paths['lib']`. In this manner the keys of the paths field can be generally
+based on standard locations in a project, and more generally on FHS. Secondly,
+this release also removes the `extra` field. Instead custom entries can be added
+at the root of the document. Note that this means that parts of the API may
+return `nil` instead of raising an error when queried for an undefined field.
+To ensure that metadata van still be strongly validated the specification adds
+a `customs` field where the names of custom fields are specified.
+
+Changes:
+
+* Designate `paths['lib']` for Ruby's load path, instead of `paths['load']`.
+* Remove `extra` field from specification; custom fields can be in root not.
+* Add `customs` field to allow customization in a robust manner.
+
+
 ## 0.2.0 / 2012-12-27
 
 The `load_path` field has been deprecated and replaced with the `paths` field,

data/README.md

@@ -1,68 +1,92 @@
-# <span class="ititle">Indexer</span> (v<span class="iversion">0.2.0</span>)
+# INDEXER
 
-<b class="isummary">Enable Your Project's Metadata<b>
+**Enable Your Project's Metadata**
 
 [![Build Status](https://secure.travis-ci.org/rubyworks/indexer.png)](http://travis-ci.org/rubyworks/indexer)
+[![Gem Version](https://badge.fury.io/rb/indexer.png)](http://badge.fury.io/rb/indexer)
 
 
-## Description
+## [What is Indexer?](#whatis)
 
-<p class="idescription">Indexer provides projects with a universal metadata format.</p>
+Indexer provides projects with a universal metadata format.
 
-Indexer defines a *canonical*, detailed and strict, project <span class="icategory">metadata</span> specification.
-The strictness of the specification makes the format simple enough for developers to use without an intermediate API.
-Although Indexer also provides a convenience API for working with the specification and its data 
-more loosely when suitable to the usecase. Indexer also specifies a stanadard location for canonized
-metadata to be kept, in a `.index` file.
+Indexer defines a *canonical* project metadata specification which is both
+detailed and strict. The strictness of the specification makes the format simple
+enough for developers to use without an intermediate API. Although Indexer also
+provides a convenience API for working with the specification and its data more
+loosely when suitable to the usecase. Indexer also specifies a standard
+location for canonized metadata to be kept, in a `.index` file.
 
-Indexer provides a tool to import metadata from external sources. Indexer can handle a variety of metadata
-source formats, including YAML, HTML Microformats and Ruby DSL scripts.
+Indexer provides a tool to import metadata from external sources. Indexer can
+handle a variety of metadata source formats, including YAML, HTML Microformats
+and Ruby DSL scripts.
 
 
-## Installation
+## [Features](#features)
 
-Indexer is a Ruby application, so as long as you have Ruby installed, it is easy to install Indexer via RubyGems.
-
-    $ gem install indexer
+* YAML-based format for universal accessibility.
+* Platform and programming language agnostic.
+* Canonical specification provides idempotent access.
+* Convenient Ruby API available.
+* Supports custom metadata fields.
 
 
-## Instruction
+## [Instruction](#instruction)
 
-Indexer is capable of generating a canonical `.index` file from a variety of sources. Being so flexiable, exactly
-how a developer descides to store a project's metadata is a largely a matter of taste. But in general there are
-three overall approaches:
+### [Installation](#installation)
 
-1. Specify the metadata using microformats in a project's README file.
-2. Specify the metadata in one or more static files, often a single YAML file.
-3. Construct the metadata via a Ruby DSL, customizing the generation in any way.
+Indexer is a Ruby application, so as long as you have Ruby installed, it is easy
+to install Indexer via RubyGems.
 
-The first choice is, in many respects, the nicest because it does not require any additional files be added
-to a project and it helps to ensure a good README file. On the downside, it requires some HTML be hand-coded
-into the README.
+    $ gem install indexer
 
-The second approach is a great option in the it is the easiest. One can quickly put together a YAML document
-covering a project's metadata. Since Indexer is very flexible in it's parsing of the YAML, it really is a
-quick and user-friendly way to go. Typically this file will be called `Index.yml`, but there is no name
-requirement. In fact, Indexer will let you split the metadata up over mutliple files, and even use a whole
-directory of files, one per field.
+### [Metadata Sources](#sources)
 
-The last approach provides maximum flexablity. Using the Ruby DSL one can literally script the metadata,
-which means it can come from anywhere at all. For example, you might want to pull the project's version
-from the `lib/project/version.rb` file, i.e. Bundler style. The DSL is as intutive and as flexible as 
-using plain YAML, so it's nearly as easy to take this approach. By convention this file is called `Indexfile`
-or `Index.rb`, but it too can be any file path one prefers.
+Indexer is capable of generating a canonical `.index` file from a variety of
+sources. Being so flexible, exactly how a developer decides to store a project's
+metadata is a largely a matter of taste. But in general there are four overall
+approaches:
 
-On the Indexer wiki you can find detailed tutorials on a variety of setups, along with thier pros and cons.
+1. Specify the metadata in one or more static files, typically a single YAML file.
+2. Specify the metadata using microformats in a project's README file.
+3. Construct the metadata via a Ruby DSL, customizing the generation in any way.
 
-As an example of getting started, lets say we want to customize our index metadata via a YAML file,
-but we want to keep the version information is a separate `VERSION` file. That's a common layout so Indexer
-is designed to handle it out of the box. First create the `VERSION` file.
+The first approach is a great option in the it is the easiest. One can quickly
+put together a YAML document covering a project's metadata. Since Indexer is
+very flexible in it's parsing of the YAML, it really is a quick and user-friendly
+way to go. Typically this file will be called `Index.yml`, but there is no name
+requirement. In fact, Indexer will also let you split the metadata up over
+multiple files, and can even go as far as using a *file store*,  which is
+a directory of files, one for each field.
+
+The second choice is, in many respects, the nicest because it does not require any
+additional files be added to a project and it helps to ensure a good README file.
+On the downside, it may require some HTML be hand-coded into the README. If your
+README's markup format has a sexy syntax for microformats, this approach rocks.
+Otherwise, another approach is probably the better choice.
+
+The last approach provides maximum flexibility. Using the Ruby DSL one can literally
+script the metadata, which means it can come from anywhere at all. For example,
+you might want to pull the project's version from the `lib/project/version.rb`
+file, i.e. Bundler style. The DSL is as intuitive and as flexible as using plain
+YAML, so it's nearly as easy to take this approach. By convention this file is
+called `Indexfile` or `Index.rb`, but it too can be any file path one prefers.
+
+On the Indexer wiki you can find detailed tutorials on a variety of setups,
+along with their pros and cons and various tip and tricks.
+
+### [Usage Example](#example)
+
+As an example of getting started, lets say we want to customize our index
+metadata via a YAML file, but we want to keep the version information is
+a separate `VERSION` file. That's a common layout so Indexer is designed
+to handle it out of the box. First create the `VERSION` file.
 
     $ echo '0.1.0' > VERSION
 
-Next we need our YAML file. Indexer makes out life easier by offering us some template generation for 
-common approaches. In this case we use the `-g/--generate` command option, specifying that we want an
-`Index.yml`.
+Next we need our YAML file. Indexer makes out life easier by offering us some
+template generation for common approaches. In this case we use the `-g/--generate`
+command option, specifying that we want an `Index.yml` file.
 
     $ index --generate Index.yml
 
@@ -70,57 +94,45 @@ Now we can edit the `Index.yaml` file to suite our project.
 
     $ vim Index.yml
 
-Once we have the source files setup, its easy to build the canonical `.index` file using the `index` 
-command line interface. We can simply issue the `index` command with the `-u/--using` command option:
+Once we have the source files setup, its easy to build the canonical `.index`
+file using the `index` command. We simply issue the `index` command with
+the `-u/--using` command option:
 
     $ index --using VERSION Index.yml
 
 Indexer will utilize both sources and create the `.index` file.
 
-Over time project metadata tends to evolve and change. To keep the canoncial `.index` file up to date simply
-call the `index` command without any options.
+Over time project metadata tends to evolve and change. To keep the canonical
+`.index` file up to date simply call the `index` command without any options.
 
     $ index
 
-By default the `.index` file will not be updated if it has a modification time newer than its source files.
-If need be, use the `-f/--force` option to override this.
+By default the `.index` file will not be updated if it has a modification time
+newer than its source files. If need be, use the `-f/--force` option to
+override this.
 
-That's the quick "one two". For more information on using Indexer, see the Wiki, API documentation, QED specifications
-and the Manpages.
+That's the quick "one two" of getting started with Indexer. For more information,
+see the Wiki, API documentation, QED specifications and the Manpages.
 
 
-## Resources
+## [Resources](#resources)
 
-<ul>
-<li><a class="iresource" href="http://rubyworks.github.com/indexer" name="home">Homepage</a></li>
-<li><a class="iresource" href="http://github.com/rubyworks/indexer" name="code">Source Code</a> (Github)</li>
-<li><a class="iresource" href="http://rubydoc.info/gems/indexer/frames" name="docs">API Reference</a></li>
-<li><a class="irepository" href="http://github.com/rubyworks/indexer/indexer.git" name="upstream">Master Git Repo</a></li>
-</ul>
+* [Website](http://rubyworks.github.com/indexer)
+* [Source Code](http://github.com/rubyworks/indexer) (Github)
+* [API Guide](http://rubydoc.info/gems/indexer/frames)
+* [Master Git Repo](http://github.com/rubyworks/indexer/indexer.git)
 
 
-## Requirements
+## [Requirements](#requirements)
 
-<ul>
-<li class="irequirement">
-  <a class="name" href="http://nokogiri.org/">nokogiri</a> <span class="version">1.5+</span></span>
-</li>
-<li class="irequirement">
-  <a class="name" href="http://kramdown.rubyforge.org/">kramdown</a> <span class="version">0.14+</span>
-</li>
-<li class="irequirement">
-  <a class="name" href="https://github.com/vmg/redcarpet">redcarpet</a> <span class="version">2.0+</span> (<span class="optional">optional</span>)
-</li>
-<li class="irequirement">
-  <a class="name" href="http://rubyworks.github.com/qed/">qed</a> <span class="version">2.9+</span> <span class="groups">(test)</span>
-</li>
-<li class="irequirement">
-  <a class="name" href="http://rubyworks.github.com/ae/">ae</a> <span class="version"></span> <span class="groups">(test)</span>
-</li>
-</ul>
+* [nokogiri](http://nokogiri.org/) 1.5+
+* [kramdown](http://kramdown.rubyforge.org/) 0.14+
+* [redcarpet](https://github.com/vmg/redcarpet) 2.0+ (optional)
+* [qed](http://rubyworks.github.com/qed/) 2.9+ (test)
+* [ae](http://rubyworks.github.com/ae/) (test)
 
 
-## Authors
+## [Authors](#authors)
 
 <ul>
 <li class="iauthor vcard">
@@ -135,14 +147,12 @@ and the Manpages.
 </ul>
 
 
-## Copyrights
+## [Copyrights](#copyrights)
 
-<ul>
-<li class="icopyright">
-  &copy; <span class="year">2012</span> <span class="holder">Rubyworks</span>
-  <div class="license">
-    <a href="http://www.spdx.org/licenses/BSD-2-Clause" rel="license">BSD-2-Clause License</a>
-  </div>
-</li>
-<ul>
+Indexer is copyrighted open-source software.
+
+**&copy; 2012 Rubyworks**
+
+It can be modified and redistributed in accordance with the terms
+of the [BSD-2-Clause](http://www.spdx.org/licenses/BSD-2-Clause) license.
 

data/lib/indexer/attributes.rb

@@ -80,16 +80,18 @@ module Indexer
     # The repository URLs for the project.
     attr_accessor :repositories
 
-    # TODO: Might webcvs simply be taken from the first repository instead?
+    # TODO: Might webcvs simply be taken from a repository?
+    #       Or perhaps from a specifically labeled resource?
 
     # URI for linking to source code.
     attr_accessor :webcvs
 
     # Map of path sets which can be used to identify paths within the project.
+    # The actual path keys largely depend on the project type, but in general
+    # should reflect the FHS,
     #
-    # For example, the `load` key is used by Ruby projectss to define which paths
-    # to search within the project when requiring files.
-    #
+    # For example, the `lib` path key is used by Ruby projects to designate
+    # which project paths to search within when requiring files.
     attr_accessor :paths
 
     # List of language engine/version family supported.
@@ -142,8 +144,8 @@ module Indexer
     # NOTE: how to best handle this?
     attr_accessor :namespace
 
-    # Any user-defined extraneous metadata.
-    #attr_accessor :extra
+    # The names of any user-defined fields.
+    attr_accessor :customs
 
   protected
 
@@ -166,7 +168,8 @@ module Indexer
         :repositories  => [],
         :resources     => [],
         :categories    => [],
-        :paths         => {'load' => ['lib']}
+        :customs       => [],
+        :paths         => {'lib' => ['lib']}
       }
     end
 

data/lib/indexer/conversion/gemfile.rb

@@ -13,7 +13,7 @@ module Indexer
 
       case file
       when String
-        # FIXME: Is this the correct way fot load a gemfile?
+        # FIXME: Is this the correct way to load a gemfile?
         bundle = ::Bundler::Dsl.new
         bundle.eval_gemfile(file)
       when NilClass

data/lib/indexer/importer/file.rb

@@ -21,29 +21,24 @@ module Indexer
       #
       # Import files from a given directory. This will only import files
       # that have a name corresponding to a metadata attribute, unless
-      # the file is listed in a `.index_extra` file within the directory.
+      # the file name is listed in the `customs` file within the directory.
       #
-      # However, files with an extension of `.yml` or `.yaml` will be loaded
+      # However, files with an extension of `.index` will be loaded as YAML
       # wholeclothe and not as a single attribute.
       #
       # @todo Subdirectories are simply omitted. Maybe do otherwise in future?
       #
       def load_directory(folder)
         if File.directory?(folder)
-          extra = []
-          extra_file = File.join(folder, '.index_extra')
-          if File.exist?(extra_file)
-            extra = File.read(extra_file).split("\n")
-            extra = extra.collect{ |pattern| pattern.strip  }
-            extra = extra.reject { |pattern| pattern.empty? }
-            extra = extra.collect{ |pattern| Dir[File.join(folder, pattern)] }.flatten
-          end
+          customs = read_customs(folder)
+
           files = Dir[File.join(folder, '*')]
+
           files.each do |file|
             next if File.directory?(file)
             name = File.basename(file).downcase
-            next load_yaml(file) if %w{.yaml .yml}.include?(File.extname(file))
-            next load_field_file(file) if extra.include?(name)
+            next load_yaml(file) if File.extname(file) == '.index'
+            next load_field_file(file) if customs.include?(name)
             next load_field_file(file) if metadata.attributes.include?(name.to_sym)
           end
         end
@@ -84,6 +79,30 @@ module Indexer
         end
       end
 
+      #
+      def read_customs(folder)
+        list = []
+        file = Dir[File.join(folder, 'customs{,.*}')].first
+        if file
+          if %w{.yaml .yml}.include?(File.extname(file))
+            list = YAML.load_file(file) || []
+            raise TypeError, "index: customs is not a array" unless Array === list
+          else
+            text = File.read(file)
+            if yaml?(text)
+              list = YAML.load_file(file) || []
+              raise TypeError, "index: customs is not a array" unless Array === list
+            else
+              list = text.split("\n")
+              list = list.collect{ |pattern| pattern.strip  }
+              list = list.reject { |pattern| pattern.empty? }
+              list = list.collect{ |pattern| Dir[File.join(folder, pattern)] }.flatten
+            end
+          end
+        end
+        return list
+      end
+
     end
 
     # Include FileImportation mixin into Builder class.

data/lib/indexer/metadata.rb

@@ -525,15 +525,16 @@ module Indexer
         end
     end
 
-    ##
-    ## Set extraneous developer-defined metdata.
-    ##
-    #def extra=(extra)
-    #  unless extra.kind_of?(Hash)
-    #    raise(ValidationError, "extra must be a Hash")
-    #  end
-    #  @data[:extra] = extra
-    #end
+    #
+    # Set custom user-field names.
+    #
+    def customs=(customs)
+      #unless customs.kind_of?(Hash)
+        #raise(ValidationError, "customs must be an Array")
+        Valid.array!(customs)
+      #end
+      @data[:customs] = customs
+    end
 
     # -- Utility Methods ----------------------------------------------------
 
@@ -541,14 +542,14 @@ module Indexer
     # Legacy method to common Ruby path via `paths['load']`.
     #
     def load_path
-      paths['load']
+      paths['lib']
     end
 
     #
     # Legacy method to set `paths['load']`.
     #
     def load_path=(path)
-      paths['load'] = Array(path).map{ |path| Valid.path!(path) }
+      paths['lib'] = Array(path).map{ |path| Valid.path!(path) }
     end
 
     #
@@ -831,6 +832,11 @@ module Indexer
       h['repositories']  = repositories.map  { |x| x.to_h }
       h['resources']     = resources.map     { |x| x.to_h }
 
+      customs.each do |name|
+$stderr.puts self[name]
+        h[name] = self[name]
+      end
+
       h
     end
 

data/lib/indexer/validator.rb

@@ -228,7 +228,7 @@ module Indexer
       super(value)
     end
 
-# TODO: How to handle project toplevel namespace?
+# TODO: How best to handle project toplevel namespace since it can be either a class or a module in a Ruby project?
 
     # Namespace must be a single line string.
     def namespace=(value)
@@ -251,9 +251,12 @@ module Indexer
       super(value)
     end
 
-    #
-    def extra=(value)
-      Valid.hash!(value, :extra)
+    # Custom field names must a valid list of strings.
+    def customs=(value)
+      Valid.array!(value, :customs)
+      value.each_with_index do |data, index|
+        Valid.string!(data, "customs ##{index}")
+      end
       super(value)
     end
 
@@ -284,8 +287,8 @@ module Indexer
     #
     def initialize_attributes
       @data = {
-        :type          => 'ruby',
         :revision      => REVISION,
+        :type          => 'ruby',
         :sources       => [],
         :authors       => [],
         :organizations => [],
@@ -295,8 +298,9 @@ module Indexer
         :resources     => [],
         :repositories  => [],
         :categories    => [],
-        :paths         => {'load' => ['lib']},
-        :copyrights    => []
+        :copyrights    => [],
+        :customs       => [],
+        :paths         => {'lib' => ['lib']},
       }
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: indexer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-27 00:00:00.000000000 Z
+date: 2013-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -44,6 +44,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: qed
   requirement: !ruby/object:Gem::Requirement
@@ -87,6 +103,7 @@ extra_rdoc_files:
 - README.md
 files:
 - .index
+- .yardopts
 - bin/index
 - data/indexer/index.kwalify
 - data/indexer/index.yes
@@ -144,7 +161,6 @@ files:
 - lib/indexer/webui/index.html
 - lib/indexer/webui.rb
 - lib/indexer.rb
-- Gemfile.lock
 - HISTORY.md
 - README.md
 homepage: http://rubyworks.github.com/indexer
@@ -168,8 +184,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Enable Your Project's Metadata
 test_files: []
+has_rdoc: 

data/Gemfile.lock

@@ -1,29 +0,0 @@
-PATH
-  remote: pkg
-  specs:
-    indexer (0.1.0)
-      nokogiri (>= 1.5)
-      redcarpet (>= 2.0)
-
-GEM
-  remote: http://rubygems.org/
-  specs:
-    ae (1.8.1)
-      ansi
-    ansi (1.4.3)
-    brass (1.2.1)
-    facets (2.9.3)
-    nokogiri (1.5.5)
-    qed (2.9.0)
-      ansi
-      brass
-      facets (>= 2.8)
-    redcarpet (2.2.2)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  ae
-  indexer!
-  qed (>= 2.9)