jsdm 0.4.0 → 0.4.2

data/{README.md → README.rdoc}

@@ -1,6 +1,6 @@
-Description
-===========
+= JSDM
 
+== Description
 JSDM is a JavaScript dependency management library written in Ruby - that is
 all.  It does not do anything special; in fact, it could be used to manage
 dependencies for any language as you can change what JSDM considers a
@@ -10,8 +10,7 @@ comment or a require statement.  JSDM will also...
 * Allow you to have globs in your require statements.
 * Allow you to specify load paths.
 
-Installation
-============
+== Installation
 To install from source:
 
     rake clobber
@@ -22,8 +21,7 @@ To install from rubygems.org:
 
     gem install jsdm
 
-Usage
-=====
+== Usage
 In your Javascript files, put #require directives in comments at the top of
 your file (note that they must be the non-whitespace characters in your file
 for JSDM to process them correctly):
@@ -43,7 +41,6 @@ Here is an example for using JSDM to concatenate all your sources into one
 big JavaScript file:
 
     require 'jsdm'
-
     jsdm = JSDM.new :load_path => %w(path_1 path_2 path_3 path_4)
     File.open('result.js', 'w') do |out|
       jsdm.sources.each do |f|
@@ -56,16 +53,20 @@ Here is an example that finds all the dependencies for file foo.js so it
 can generate the script tags for that file:
 
     require 'jsdm'
-
     Dir.chdir '/path/to/local/js/files' do
       jsdm = JSDM.new :load_path => '.'
-      jsdm.dependencies_for('foo.js') do |f|
+      jsdm.dependencies_for('foo.js').each do |f|
         puts "<script src='/path/to/server/js/files/#{f}' />"
       end
     end
 
-License
-=======
+== Author
+Min Huang <min.huang@alumni.usc.edu>
+
+== Contributors
+Pete Elmore <pete@debu.gs>, Ryan Wolf <ryan@borderstylo.com>
+
+== License
 The following is retained from BorderStylo's licensing terms:
 
 JSDM version 0.2.20 and above is licensed under the MIT license.

data/Rakefile

@@ -1,6 +1,5 @@
 require 'fileutils'
 require 'rake'
-require 'rake/clean'
 require 'rake/gempackagetask'
 require 'rake/rdoctask'
 
@@ -9,22 +8,32 @@ spec = Gem::Specification.new do |s|
   s.name              = 'jsdm'
   s.author            = 'Min Huang'
   s.email             = 'min.huang@alumni.usc.edu'
-  s.files             = Dir["{lib,doc,bin,ext}/**/*"].delete_if { |f|
+  s.files             = Dir['{lib,doc,bin,ext}/**/*'].delete_if { |f|
                           /\/rdoc(\/|$)/i.match f
-                        } + %w(Rakefile LICENSE README.md)
+                        } + %w(Rakefile README.rdoc)
   s.require_path      = 'lib'
   s.has_rdoc          = true
-  s.homepage          = "http://www.borderstylo.com/#{s.name}"
-  s.version           = '0.4.0'
-  s.summary           = 'Javascript dependency manager'
-  s.description       = 'Use #require statements to declare dependencies'
   s.rubyforge_project = 'jsdm'
+  s.homepage          = 'http://www.github.com/retiman/jsdm'
+  s.version           = '0.4.2'
+  s.summary           = 'Javascript dependency manager'
+  s.description       = <<-EOF
+    Use #require statements to declare dependencies in JavaScript and let JSDM
+    resolve the dependencies for you.
+  EOF
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
   pkg.need_tar_bz2 = true
 end
 
+Rake::RDocTask.new(:doc) do |t|
+  t.title = 'JSDM'
+  t.main = 'README.rdoc'
+  t.rdoc_files.include('lib/**/*.rb', 'doc/*', 'README.rdoc')
+  t.rdoc_dir = 'doc/rdoc'
+end
+
 desc 'Run tests (no arg), or single test (with arg)'
 task :test, :name do |t, args|
   opts = args.name.nil? ? '' : "-n test_#{args.name}"

data/doc/REFERENCES

@@ -0,0 +1,5 @@
+* Cormen, Leiserson, Rivest, Stein.
+  Introduction to Algorithms 2nd Edition.  Massachusetts, USA: MIT Press, 2003.
+
+* Muchnick, Steven S.
+  Advanced Compiler Design and Implementation.  London, United Kingdom: Academic Press, 1997.

data/lib/jsdm.rb

@@ -3,6 +3,21 @@ require 'jsdm/dependency_resolver'
 require 'jsdm/errors'
 require 'jsdm/preprocessor'
 
+# JSDM allows you to add #require statements to JavaScript and then manages
+# the dependencies for you.  You may place the JavaScript files in many
+# different directories, and then add those directories to your load path.
+#
+# JSDM will scan those directories, resolve your dependencies, and return to
+# you a list of sources sorted topologically (that is, dependent sources
+# come first).  You may then use that list to generate script tags, load them
+# in Spidermonkey for syntax checking, or whatever else you like.
+#
+# Here's a quick example of how to use JSDM:
+#
+#   jsdm = JSDM.new :load_path => %w(/path1 /path2 /path3)
+#   jsdm.sources.each do |source|
+#     puts source
+#   end
 class JSDM
   attr_accessor :options,
                 :sources,
@@ -30,6 +45,14 @@ class JSDM
     process
   end
 
+  # Preprocesses, resolves, and sorts the source files.  Here's how it does it:
+  #
+  # * Gather all the sources in the load path
+  # * Optionally sort them to ensure that dependencies have been set correctly
+  # * Create the Preprocessor, DependencyResolver, and DependencyManager
+  # * Preprocess the source files and resolve the dependencies
+  # * Add each individual dependency to the DependencyManager
+  # * Have the DependencyManager perform a topological sort
   def process
     self.sources      = options[:load_path].map { |path|
                           Dir[File.join(path, '**', "*.#{options[:extension]}")]
@@ -55,18 +78,23 @@ class JSDM
     sources
   end
 
+  # Returns an associative list of sources mapped to source dependencies
   def dependencies
     manager.dependencies
   end
 
+  # Returns the dependencies of a source file, as an array of strings
   def dependencies_for(source)
     manager.dependencies_for(source)
   end
 
+  # Returns the dependencies of a source file (and the source file itself) as
+  # an array of strings
   def sources_for(source)
     dependencies_for(source) << source
   end
 
+  # Returns the require statements for a source file
   def requires_for(source)
     requires.select { |r| r.first == source }.first.last
   end

data/lib/jsdm/dependency_manager.rb

@@ -5,6 +5,8 @@ require 'jsdm/natural_loops'
 require 'jsdm/errors'
 
 class JSDM
+  # This class processes a dependency graph to find the order the source files
+  # should be in after a topological sort.
   class DependencyManager
     attr_accessor :sources, :dependencies, :graph
 
@@ -14,12 +16,15 @@ class JSDM
       self.graph = nil
     end
 
+    # Add a dependency to the dependency graph.
     def add_dependency(source, dependency)
       unless same_file? dependency, source
         dependencies << [dependency, source]
       end
     end
 
+    # Recursively calculate dependencies for an individual source file.  Uses
+    # the acc argument as an accumulator.
     def dependencies_for(source, acc = [])
        ds = dependencies.select { |d| d.last == source }.
                          map { |d| d.first }
@@ -29,6 +34,18 @@ class JSDM
        acc
     end
 
+    # Does a topological sort to find the order of dependencies, and checks
+    # for any circular dependencies.  The reverse order of visitation in a
+    # depth-first search constitutes a topological sort.
+    #
+    # An algorithm for finding natural loops is used to determine whether or
+    # not any circular dependencies exist.  It is slower than simply adding
+    # a check to the DepthFirstSearch to see if any nodes have been visited
+    # twice, but it allows JSDM to more easily report all circular dependencies
+    # rather than just barfing on the first one found.
+    #
+    # See http://en.wikipedia.org/wiki/Topological_sorting for a more in
+    # depth explanation of topological sort.
     def process
       self.sources = sources.uniq.delete_if { |e| e.empty? }
       self.dependencies = dependencies.uniq.delete_if { |e| e.empty? }
@@ -41,6 +58,7 @@ class JSDM
 
     private
 
+    # Test if two files have resolved to the same thing
     def same_file?(a, b)
       File.expand_path(a) == File.expand_path(b)
     end

data/lib/jsdm/dependency_resolver.rb

@@ -1,6 +1,8 @@
 require 'jsdm/errors'
 
 class JSDM
+  # Resolves filenames and globs in a #require statement, relative to a load
+  # path.
   class DependencyResolver
     attr_accessor :load_path
 
@@ -8,11 +10,28 @@ class JSDM
       self.load_path = load_path
     end
 
+    # Returns a list of actual files that have been resolved.
+    #
+    # For example, if you do:
+    #
+    #   // #require foo/*.js, bar/*.js
+    #
+    # This function will resolve those to actual file names.
     def process(entries)
       entries.map { |entry| process_single entry }.
               flatten
     end
 
+    # Resolve a single entry in a require statement.  For example, if a source
+    # file #require's foo.js, this function will resolve foo.js to the proper
+    # file in your load_path.  The first directory in your load_path that
+    # contains foo.js will win; other files matching foo.js will be discarded.
+    #
+    # Incidentally, if you ask to resolve *.js, then this resolves to the first
+    # directory in your load_path!  Similarly, if you ask to resolve foo/*.js,
+    # it resolves to the first non-empty directory foo in your load_path.
+    #
+    # Be careful about using globs with multiple load paths.
     def process_single(entry)
       resolved = load_path.map { |path| Dir[File.join(path, entry.strip)] }.
                            drop_while { |sources| sources.empty? }.

data/lib/jsdm/depth_first_search.rb

@@ -1,6 +1,12 @@
 require 'set'
 
 class JSDM
+  # Performs a depth-first search on a DirectedGraph.  This class implements
+  # the algorithm described on page 541 of Introduction to Algorithms,
+  # 2nd Edition by Cormen, Leiserson, Rivest, and Stein.
+  #
+  # See http://en.wikipedia.org/wiki/Depth-first_search for a more accessible
+  # explanation of what a depth-first search is.
   class DepthFirstSearch
     def initialize(graph)
       self.graph            = graph
@@ -23,16 +29,16 @@ class JSDM
         :predecessors     => predecessors,
         :sorted           => sorted,
         :tree_edges       => edge_colors[:white],
-        :forward_edges    => edge_colors[:black].select do |e|
+        :forward_edges    => edge_colors[:black].select { |e|
                                t = discovered_times[e.first]
                                u = discovered_times[e.last]
                                t < u
-                             end,
-        :cross_edges      => edge_colors[:black].select do |e|
+                             },
+        :cross_edges      => edge_colors[:black].select { |e|
                                t = discovered_times[e.first]
                                u = discovered_times[e.last]
                                t > u
-                             end,
+                             },
         :back_edges       => edge_colors[:gray]
       }
     end
@@ -59,6 +65,7 @@ class JSDM
       self.time += 1
     end
 
+    # Returns the results of a depth-first search on a DirectedGraph.
     def self.dfs(graph)
       search = DepthFirstSearch.new(graph)
       search.process

data/lib/jsdm/directed_graph.rb

@@ -1,4 +1,7 @@
 class JSDM
+  # Very simple class to represent a directed graph using adjacency lists.
+  # See http://en.wikipedia.org/wiki/Digraph_(mathematics)
+  # See http://en.wikipedia.org/wiki/Adjacency_list
   class DirectedGraph
     attr_accessor :nodes, :arcs
     private :nodes=, :arcs=
@@ -8,6 +11,8 @@ class JSDM
       self.arcs  = arcs
     end
 
+    # Returns a list of nodes that are in the tail of an arc whose head
+    # is the given node.
     def successors(node)
       arcs.select { |a| a.first == node }.map { |a| a.last }
     end

data/lib/jsdm/errors.rb

@@ -1,6 +1,9 @@
 require 'pp'
 
 class JSDM
+  # This error is raised if a set of files (or if multiple sets of files) are
+  # in a circular dependency.  JSDM will report them all, so deps will be a
+  # set of sets.
   class CircularDependencyError < StandardError
     attr_accessor :deps
     private :deps=
@@ -15,6 +18,9 @@ class JSDM
     end
   end
 
+  # Used internally to indicate that a file could not be found; this error will
+  # not be exposed to the user.  This error eventually gets wrapped in a
+  # UnsatisfiableDependencyError.
   class FileNotFoundError < StandardError
     attr_accessor :file
     private :file=
@@ -25,6 +31,9 @@ class JSDM
     end
   end
 
+  # This error is raised if a file could not be found.  This error includes
+  # information about the dependency that couldn't be found, and the source
+  # that asked for that dependency.
   class UnsatisfiableDependencyError < StandardError
     attr_accessor :source, :dep
     private :source=, :dep=

data/lib/jsdm/natural_loops.rb

@@ -1,8 +1,18 @@
 require 'set'
 
 class JSDM
-  class NaturalLoops
-    def self.find(graph, back_edges)
+  # This class calculates the natural loops in a directed graph, given the
+  # back edges.
+  #
+  # Implements the algorithm found on page 192 of Advanced Compiler Design and
+  # Implementation by Steven S. Muchnick.
+  module NaturalLoops
+    extend self
+
+    # Returns a set of "loops" (which are in turn a set of nodes), given a
+    # DirectedGraph and the back edges found from a DepthFirstSearch, if any
+    # exist.
+    def find(graph, back_edges)
       loops = Set.new
       back_edges.each do |arc|
         l = [arc.first, arc.last]
@@ -12,12 +22,11 @@ class JSDM
           u = stack.pop
           neighbors = graph.arcs.
                             select { |a| a.last == u }.
-                            map { |a| a.first }.each 
+                            map { |a| a.first }
           neighbors.each do |v|
-            if !l.include?(v)
-              l << v
-              stack.push v
-            end
+            next if l.include? v
+            l << v
+            stack.push v
           end
         end
         loops << l.to_set

data/lib/jsdm/preprocessor.rb

@@ -1,4 +1,5 @@
 class JSDM
+  # Preprocesses the JavaScript for the DependencyResolver
   class Preprocessor
     attr_accessor :sources, :options
 
@@ -11,6 +12,15 @@ class JSDM
       self.options = defaults.merge options
     end
 
+    # Processes a single source file for its dependencies so that they may be
+    # resolved.  Here's how this function does it:
+    #
+    # * Open the source file and read it, taking all the lines that match the
+    #   comment_pattern
+    # * Select the lines that match the require_pattern from those lines
+    # * Split each require statement with a comma in it
+    # * Flatten the array of dependencies
+    # * Strip out the trailing whitespace
     def process_single(source)
       File.open(source).
            each_line.
@@ -21,6 +31,7 @@ class JSDM
            map { |entry| entry.strip }
     end
 
+    # Returns an associative list that maps source to (unresolved) dependencies
     def process
       sources.map { |source| [source, process_single(source)] }
     end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 4
-  - 0
-  version: 0.4.0
+  - 2
+  version: 0.4.2
 platform: ruby
 authors: 
 - Min Huang
@@ -14,11 +14,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-31 00:00:00 -07:00
+date: 2010-06-09 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
-description: "Use #require statements to declare dependencies"
+description: "    Use #require statements to declare dependencies in JavaScript and let JSDM\n    resolve the dependencies for you.\n"
 email: min.huang@alumni.usc.edu
 executables: []
 
@@ -35,11 +35,12 @@ files:
 - lib/jsdm/directed_graph.rb
 - lib/jsdm/natural_loops.rb
 - lib/jsdm/dependency_resolver.rb
+- doc/LICENSE
+- doc/REFERENCES
 - Rakefile
-- LICENSE
-- README.md
+- README.rdoc
 has_rdoc: true
-homepage: http://www.borderstylo.com/jsdm
+homepage: http://www.github.com/retiman/jsdm
 licenses: []
 
 post_install_message: