jsus 0.1.4 → 0.1.5

data/CHANGELOG

@@ -1,4 +1,9 @@
 = Jsus Changelog
+== Version 0.1.5
+* Introduced new concept, Tag, which is going to be used instead of 
+  provides/requires strings
+* Introduced source extensions (monkey-patching, actually)
+* Wrote some basic documentation for the classes
 
 == Version 0.1.4
 * Switched from OptiFlag to Choice for command-line parsing in jsus utility

data/Manifest

@@ -11,7 +11,7 @@ lib/jsus/package.rb
 lib/jsus/packager.rb
 lib/jsus/pool.rb
 lib/jsus/source_file.rb
-lib/jsus/topsortable.rb
+lib/jsus/tag.rb
 spec/data/Basic/README
 spec/data/Basic/app/javascripts/Orwik/Source/Library/Color.js
 spec/data/Basic/app/javascripts/Orwik/Source/Widget/Input/Input.Color.js
@@ -24,6 +24,10 @@ spec/data/ChainDependencies/app/javascripts/Hash/Source/Hash.js
 spec/data/ChainDependencies/app/javascripts/Hash/package.yml
 spec/data/ChainDependencies/app/javascripts/Mash/Source/Mash.js
 spec/data/ChainDependencies/app/javascripts/Mash/package.yml
+spec/data/Extensions/app/javascripts/Core/Source/Class.js
+spec/data/Extensions/app/javascripts/Core/package.yml
+spec/data/Extensions/app/javascripts/Orwik/Extensions/Class.js
+spec/data/Extensions/app/javascripts/Orwik/package.yml
 spec/data/ExternalDependencies/app/javascripts/Orwik/Source/Test.js
 spec/data/ExternalDependencies/app/javascripts/Orwik/package.yml
 spec/data/OutsideDependencies/README
@@ -44,7 +48,7 @@ spec/lib/jsus/package_spec.rb
 spec/lib/jsus/packager_spec.rb
 spec/lib/jsus/pool_spec.rb
 spec/lib/jsus/source_file_spec.rb
-spec/lib/jsus/topsortable_spec.rb
+spec/lib/jsus/tag_spec.rb
 spec/shared/class_stubs.rb
 spec/spec.opts
 spec/spec_helper.rb

data/Rakefile

@@ -1,7 +1,7 @@
 require 'rubygems'
 require 'rake'
 require 'echoe'
-Echoe.new('jsus', '0.1.4') do |g|
+Echoe.new('jsus', '0.1.5') do |g|
   g.description    = "Packager/compiler for js-files that resolves dependencies and can compile everything into one file, providing all the neccessary meta-info."
   g.url            = "http://github.com/markiz/jsus"
   g.author         = "Markiz, idea by Inviz (http://github.com/Inviz)"

data/bin/jsus

@@ -44,6 +44,7 @@ pool = if Choice.choices[:dependencies]
 end
 package = Jsus::Package.new(Choice.choices[:input_directory], :pool => pool)
 package.include_dependencies! if Choice.choices[:dependencies]
+package.include_extensions! if Choice.choices[:dependencies]
 output_directory = Choice.choices[:output_directory]
 package.compile(output_directory)
 package.generate_scripts_info(output_directory) unless Choice.choices[:without_scripts_info]

data/jsus.gemspec

@@ -2,17 +2,17 @@
 
 Gem::Specification.new do |s|
   s.name = %q{jsus}
-  s.version = "0.1.4"
+  s.version = "0.1.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Markiz, idea by Inviz (http://github.com/Inviz)"]
-  s.date = %q{2010-06-07}
+  s.date = %q{2010-06-15}
   s.default_executable = %q{jsus}
   s.description = %q{Packager/compiler for js-files that resolves dependencies and can compile everything into one file, providing all the neccessary meta-info.}
   s.email = %q{markizko@gmail.com}
   s.executables = ["jsus"]
-  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README", "TODO", "bin/jsus", "lib/jsus.rb", "lib/jsus/container.rb", "lib/jsus/package.rb", "lib/jsus/packager.rb", "lib/jsus/pool.rb", "lib/jsus/source_file.rb", "lib/jsus/topsortable.rb"]
-  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README", "Rakefile", "TODO", "bin/jsus", "lib/jsus.rb", "lib/jsus/container.rb", "lib/jsus/package.rb", "lib/jsus/packager.rb", "lib/jsus/pool.rb", "lib/jsus/source_file.rb", "lib/jsus/topsortable.rb", "spec/data/Basic/README", "spec/data/Basic/app/javascripts/Orwik/Source/Library/Color.js", "spec/data/Basic/app/javascripts/Orwik/Source/Widget/Input/Input.Color.js", "spec/data/Basic/app/javascripts/Orwik/Source/Widget/Input/Input.js", "spec/data/Basic/app/javascripts/Orwik/Source/Widget/Widget.js", "spec/data/Basic/app/javascripts/Orwik/package.yml", "spec/data/ChainDependencies/app/javascripts/Class/Source/Class.js", "spec/data/ChainDependencies/app/javascripts/Class/package.yml", "spec/data/ChainDependencies/app/javascripts/Hash/Source/Hash.js", "spec/data/ChainDependencies/app/javascripts/Hash/package.yml", "spec/data/ChainDependencies/app/javascripts/Mash/Source/Mash.js", "spec/data/ChainDependencies/app/javascripts/Mash/package.yml", "spec/data/ExternalDependencies/app/javascripts/Orwik/Source/Test.js", "spec/data/ExternalDependencies/app/javascripts/Orwik/package.yml", "spec/data/OutsideDependencies/README", "spec/data/OutsideDependencies/app/javascripts/Core/Source/Class/Class.Extras.js", "spec/data/OutsideDependencies/app/javascripts/Core/Source/Class/Class.js", "spec/data/OutsideDependencies/app/javascripts/Core/Source/Native/Hash.js", "spec/data/OutsideDependencies/app/javascripts/Core/package.yml", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Library/Color.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Widget/Input/Input.Color.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Widget/Input/Input.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Widget/Widget.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/package.yml", "spec/data/bad_test_source_one.js", "spec/data/bad_test_source_two.js", "spec/data/test_source_one.js", "spec/lib/jsus/container_spec.rb", "spec/lib/jsus/package_spec.rb", "spec/lib/jsus/packager_spec.rb", "spec/lib/jsus/pool_spec.rb", "spec/lib/jsus/source_file_spec.rb", "spec/lib/jsus/topsortable_spec.rb", "spec/shared/class_stubs.rb", "spec/spec.opts", "spec/spec_helper.rb", "jsus.gemspec"]
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README", "TODO", "bin/jsus", "lib/jsus.rb", "lib/jsus/container.rb", "lib/jsus/package.rb", "lib/jsus/packager.rb", "lib/jsus/pool.rb", "lib/jsus/source_file.rb", "lib/jsus/tag.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README", "Rakefile", "TODO", "bin/jsus", "jsus.gemspec", "lib/jsus.rb", "lib/jsus/container.rb", "lib/jsus/package.rb", "lib/jsus/packager.rb", "lib/jsus/pool.rb", "lib/jsus/source_file.rb", "lib/jsus/tag.rb", "spec/data/Basic/README", "spec/data/Basic/app/javascripts/Orwik/Source/Library/Color.js", "spec/data/Basic/app/javascripts/Orwik/Source/Widget/Input/Input.Color.js", "spec/data/Basic/app/javascripts/Orwik/Source/Widget/Input/Input.js", "spec/data/Basic/app/javascripts/Orwik/Source/Widget/Widget.js", "spec/data/Basic/app/javascripts/Orwik/package.yml", "spec/data/ChainDependencies/app/javascripts/Class/Source/Class.js", "spec/data/ChainDependencies/app/javascripts/Class/package.yml", "spec/data/ChainDependencies/app/javascripts/Hash/Source/Hash.js", "spec/data/ChainDependencies/app/javascripts/Hash/package.yml", "spec/data/ChainDependencies/app/javascripts/Mash/Source/Mash.js", "spec/data/ChainDependencies/app/javascripts/Mash/package.yml", "spec/data/Extensions/app/javascripts/Core/Source/Class.js", "spec/data/Extensions/app/javascripts/Core/package.yml", "spec/data/Extensions/app/javascripts/Orwik/Extensions/Class.js", "spec/data/Extensions/app/javascripts/Orwik/package.yml", "spec/data/ExternalDependencies/app/javascripts/Orwik/Source/Test.js", "spec/data/ExternalDependencies/app/javascripts/Orwik/package.yml", "spec/data/OutsideDependencies/README", "spec/data/OutsideDependencies/app/javascripts/Core/Source/Class/Class.Extras.js", "spec/data/OutsideDependencies/app/javascripts/Core/Source/Class/Class.js", "spec/data/OutsideDependencies/app/javascripts/Core/Source/Native/Hash.js", "spec/data/OutsideDependencies/app/javascripts/Core/package.yml", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Library/Color.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Widget/Input/Input.Color.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Widget/Input/Input.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/Source/Widget/Widget.js", "spec/data/OutsideDependencies/app/javascripts/Orwik/package.yml", "spec/data/bad_test_source_one.js", "spec/data/bad_test_source_two.js", "spec/data/test_source_one.js", "spec/lib/jsus/container_spec.rb", "spec/lib/jsus/package_spec.rb", "spec/lib/jsus/packager_spec.rb", "spec/lib/jsus/pool_spec.rb", "spec/lib/jsus/source_file_spec.rb", "spec/lib/jsus/tag_spec.rb", "spec/shared/class_stubs.rb", "spec/spec.opts", "spec/spec_helper.rb"]
   s.homepage = %q{http://github.com/markiz/jsus}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Jsus", "--main", "README"]
   s.require_paths = ["lib"]

data/lib/jsus.rb

@@ -7,12 +7,20 @@ require 'active_support/core_ext/module/delegation'
 require 'rgl/adjacency'
 require 'rgl/topsort'
 
-require 'jsus/topsortable'
 require 'jsus/source_file'
+require 'jsus/package'
+require 'jsus/tag'
 require 'jsus/container'
 require 'jsus/packager'
-require 'jsus/package'
 require 'jsus/pool'
 
+#
+# Jsus — a library for packaging up your source files.
+#
+# For better understanding of jsus ideas start with http://github.com/Markiz/jsus-examples
+#
+#
+
+
 module Jsus
 end

data/lib/jsus/container.rb

@@ -1,21 +1,32 @@
+#
+# Container is an array which contains source files. Main difference
+# between it and array is the fact that container maintains topological
+# sort for the source files.
+#
 module Jsus
   class Container
-    include Topsortable        
-
+    #
+    # Every argument for initializer is pushed into the container.
+    #
     def initialize(*sources)
       sources.each do |source|
         self << source
       end
     end
+    
+    # Public API
 
-
-    # PRO TIP: #<< sorts upon every invokation
-    # #push doesn't
+    #
+    # Pushes an item to container and sorts container. 
+    #
+    # When given an array or another container, enumerates its contents.
+    #
     def <<(source)
       push(source)
       sort!
     end
 
+    # Pushes an item to container *without sorting it*. Use with care.
     def push(source)
       if source
         if source.kind_of?(Array) || source.kind_of?(Container)
@@ -27,37 +38,63 @@ module Jsus
       self
     end
 
-    def flatten      
+    # Flattens the container items.
+    def flatten
       map {|item| item.respond_to?(:flatten) ? item.flatten : item }.flatten
     end
 
-    def to_a
-      sources
-    end
-
+    # Contains the source files in the correct order.
     def sources
       @sources ||= []
     end
-
-    def sources=(new_value)
+    alias_method :to_a, :sources
+    
+    def sources=(new_value) # :nodoc:
       @sources = new_value
     end
 
+    # Performs a sort and returns self. Executed automatically by #<< .
     def sort!
-      self.sources = topsort(:sources)
+      self.sources = topsort
       self
     end
 
-    def inspect
+    def inspect # :nodoc:
       "#<#{self.class.name}:#{self.object_id} #{self.sources.inspect}>"
     end
 
-    # delegate undefined methods to #sources
+    # Private API
+    
+    def topsort # :nodoc:
+      graph = RGL::DirectedAdjacencyGraph.new
+      provides_map = {}
+      # init vertices
+      items = self.sources
+      items.each do |item|
+        graph.add_vertex(item)
+        item.provides.each do |provides|
+          provides_map[provides] = item
+        end
+      end
+      # init edges
+      items.each do |item|
+        item.dependencies.each do |dependency|
+          if required_item = provides_map[dependency]
+            graph.add_edge(required_item, item)
+          end
+        end
+      end
+      result = []
+      graph.topsort_iterator.each { |item| result << item }
+      result
+    end
+
     DELEGATED_METHODS = [
-                          "==", "map", "map!", "each", "inject", "reject",
-                          "detect", "size", "length", "[]", "empty?",
-                          "index", "include?"
-                        ]
+                          "==", "map", "map!", "each", "inject", "inject!",
+                          "reject", "reject!", "detect", "size", "length", "[]", 
+                          "empty?", "index", "include?", "select", "-", "+", "|", "&"
+                        ] # :nodoc:
+    # delegates most Enumerable methods to #sources
     (DELEGATED_METHODS).each {|m| delegate m, :to => :sources }
   end
 end

data/lib/jsus/package.rb

@@ -1,16 +1,34 @@
+#
+# Package is basically a list of source files with some meta info.
+#
+
+
 module Jsus
   class Package
-    attr_accessor :relative_directory
-    attr_accessor :directory
-    attr_accessor :pool
-     # Constructors
+    attr_accessor :directory # directory which this package resides in (full path)
+    attr_accessor :pool      # an instance of Pool
+    # Constructors
+     
+    #
+    # Creates a package from given directory.
+    #
+    # Accepts options:
+    # * +:pool:+ — which pool the package should belong to.
+    #
+    # Raises an error when the given directory doesn't contain a package.yml
+    # file with meta info.
+    #
     def initialize(directory, options = {})
-      self.relative_directory = directory
-      self.directory = File.expand_path(directory)
-      self.header = YAML.load_file(File.join(directory, 'package.yml'))
+      self.directory          = File.expand_path(directory)
+      self.header             = YAML.load_file(File.join(directory, 'package.yml'))
       Dir.chdir(directory) do
         files.each do |source|
-          source_files << SourceFile.from_file(source, :package => self)
+          source_file = SourceFile.from_file(source, :package => self)
+          if source_file.extension?
+            extensions << source_file
+          else
+            source_files << source_file
+          end
         end
       end
       if options[:pool]
@@ -21,56 +39,78 @@ module Jsus
 
 
     # Public API
+    
+    # Returns a package.yml header.
     def header
       @header ||= {}
     end
 
-    def header=(new_header)
-      @header = new_header
-    end
-
+    # Returns a package name.
     def name
       header["name"] ||= ""
     end
+    
+    # Returns a package description.
+    def description
+      header["description"] ||= ""
+    end    
 
+    # Returns a filename for compiled package.
     def filename
       header["filename"] ||= name + ".js"
     end
 
-    def provides
-      (source_files.map {|source| source.provides(:short => true) } + linked_external_dependencies.map {|d| d.provides }).flatten
-    end
-
+    # Returns a list of sources filenames.
     def files
       header["files"] = header["files"] || header["sources"] || []
     end
-
     alias_method :sources, :files
 
-    def dependencies
-      source_files.map {|source| source.dependencies(:short => true) }.flatten.compact.uniq - provides
+    # Returns an array of provided tags including those provided by linked external dependencies.
+    def provides
+      source_files.map {|s| s.provides }.flatten | linked_external_dependencies.map {|d| d.provides }.flatten
     end
 
-    def external_dependencies
-      source_files.map {|source| source.external_dependencies }
+    # Returns an array of provided tags names including those provided by linked external dependencies.
+    def provides_names
+      source_files.map {|s| s.provides_names(:short => true) }.flatten |
+      linked_external_dependencies.map {|d| d.provides_names }.flatten
     end
 
-    def linked_external_dependencies
-      @linked_external_dependencies ||= Container.new
+    # Returns an array of unresolved dependencies' tags for the package.
+    def dependencies
+      result = source_files.map {|source| source.dependencies }.flatten
+      result |= linked_external_dependencies.map {|d| d.dependencies}.flatten
+      result -= provides
+      result
     end
 
-    def linked_external_dependencies=(new_value)
-      @linked_external_dependencies = new_value
+    # Returns an array of unresolved dependencies' names.
+    def dependencies_names
+      dependencies.map {|d| d.name(:short => true) }
     end
 
-    def description
-      header["description"] ||= ""
-    end    
+    # Returns an array of external dependencies' tags (including resolved ones).
+    def external_dependencies
+      source_files.map {|s| s.external_dependencies }.flatten
+    end
+    
+    # Returns an array of external dependencies' names (including resolved ones).
+    def external_dependencies_names
+      external_dependencies.map {|d| d.name }
+    end
 
+    # Returns source files with external dependencies in correct order.
+    def linked_external_dependencies
+      @linked_external_dependencies ||= Container.new
+    end
+    
+    # Compiles source files and linked external source files into a given category.
     def compile(directory = ".")
       Packager.new(*(source_files.to_a + linked_external_dependencies.to_a)).pack(File.join(directory, filename))
     end
 
+    # Generates tree structure for files in package into a json file.
     def generate_tree(directory = ".", filename = "tree.json")
       FileUtils.mkdir_p(directory)
       result = ActiveSupport::OrderedHash.new
@@ -89,38 +129,62 @@ module Jsus
       result
     end
 
+    # Generates info about resulting compiled package into a json file.
     def generate_scripts_info(directory = ".", filename = "scripts.json")
       FileUtils.mkdir_p directory
       File.open(File.join(directory, filename), "w") { |resulting_file| resulting_file << JSON.pretty_generate(self.to_hash) }
       self.to_hash
     end
 
+    # Looks up all the external dependencies in the pool.
     def include_dependencies!
       source_files.each do |source|
         linked_external_dependencies << pool.lookup_dependencies(source)
       end
     end
 
+    # Executes #include_extensions for all the source files.
+    def include_extensions!
+      source_files.each do |source|
+        source.include_extensions!
+      end
+    end
 
-    def required_files
-      source_files.map {|s| s.filename }
+    # Lists the required files for the package.
+    def required_files      
+      source_files.map {|s| s.required_files }.flatten
     end
 
-    def to_hash
+    def to_hash # :nodoc:
       {
         name => {
           :desc => description,
-          :provides => provides,
-          :requires => dependencies
+          :provides => provides_names,
+          :requires => dependencies_names
         }
       }
     end
 
-
+    # Container with source files
     def source_files
       @source_files ||= Container.new
     end
 
+    # Container with extensions (they aren't compiled or included into #reqired_files list)
+    def extensions
+      @extensions ||= Container.new
+    end
+
+    # Private API
+    
+    def header=(new_header) # :nodoc:
+      @header = new_header
+    end
+
+    def linked_external_dependencies=(new_value) # :nodoc:
+      @linked_external_dependencies = new_value
+    end
+
     protected
   end
-end
+end

data/lib/jsus/packager.rb

@@ -1,15 +1,30 @@
+#
+# Packager is a plain simple class accepting several source files 
+# and joining their contents.
+#
+# It uses Container for storage which means it automatically sorts sources.
+#
 module Jsus
   class Packager
-    attr_accessor :container
+    attr_accessor :container  # :nodoc:
 
+    # 
+    # Inits packager with the given sources.
+    #
     def initialize(*sources)
       self.container = Container.new(*sources)
     end
 
-    def sources
+    def sources # :nodoc:
       container.sources
     end
 
+    # 
+    # Concatenates all the sources' contents into a single string.
+    # If given a filename, outputs into a file.
+    #
+    # Returns the concatenation.
+    #
     def pack(output_file = nil)
       result = sources.map {|s| s.content }.join("\n")