jsus 0.1.4 → 0.1.5

data/lib/jsus/pool.rb

@@ -1,63 +1,121 @@
+#
+# Pool class is designed for three purposes:
+# * Maintain connections between SourceFiles and/or Packages
+# * Resolve dependencies
+# * Look up extensions
+#
+# 
+
+
 module Jsus
   class Pool
 
+    # Constructors
+
+    #
+    # Basic constructor.
+    #
+    # Accepts an optional directory argument, when it is set, it looks up for 
+    # packages from the given directory and if it finds any, adds them to the pool.
+    #
+    # Directory is considered a Package directory if it contains +package.yml+ file.
+    #
     def initialize(dir = nil)
       if dir
         Dir[File.join(dir, '**', 'package.yml')].each do |package_path|
-          Package.new(Pathname.new(package_path).parent.to_s, :pool => self)
+          Package.new(File.dirname(package_path), :pool => self)
         end
       end
     end
-
+    
+    
+    # 
+    # An array containing all the packages in the pool. Unordered.
+    #
     def packages
       @packages ||= []
-      @packages.uniq!
-      @packages
     end
 
+    #
+    # Container with all the sources in the pool. It is actually ordered in case you 
+    # want to include ALL the source files from the pool.
+    #
     def sources
       @sources ||= Container.new
     end
 
+    #
+    # Looks up for a file providing given tag or tag key. 
+    #
+    # If given a source file, returns the input.
+    #
     def lookup(source_or_key)
       case source_or_key
       when String
+        provides_map[Tag[source_or_key]]
+      when Tag
         provides_map[source_or_key]
-      when Jsus::SourceFile
+      when SourceFile
         source_or_key
       else
-        raise "Illegal lookup query. Expected String or SourceFile, " <<
+        raise "Illegal lookup query. Expected String, Tag or SourceFile, " <<
               "given #{source_or_key.inspect}, an instance of #{source_or_key.class.name}."
       end
     end
+  
 
-    def lookup_direct_dependencies(source_or_source_key)
-      source = lookup(source_or_source_key)
-      result = source.external_dependencies.map {|d| lookup(d)}
-      Container.new(*result)
-    end
-
-    def lookup_dependencies(source_or_source_key)
+    #
+    # Looks up for dependencies for given file recursively.
+    #
+    # Returns an instance of Container which contains needed files sorted.
+    #
+    def lookup_dependencies(source_or_source_key)      
       source = lookup(source_or_source_key)
       result = Container.new
-      dependencies = lookup_direct_dependencies(source)
-      while !dependencies.empty?
-        dependencies.each { |d| result.push(d) }
-        dependencies = dependencies.map {|d| lookup_direct_dependencies(d).to_a }.flatten.uniq
+      if source
+        dependencies = lookup_direct_dependencies(source)
+        while !dependencies.empty?
+          dependencies.each { |d| result.push(d) }
+          dependencies = dependencies.map {|d| lookup_direct_dependencies(d).to_a }.flatten.uniq
+        end
+        result.sort!
       end
-      result.sort!
+      result
     end
 
+    #
+    # Returns an array with SourceFile-s with extensions for given tag.
+    #
+    def lookup_extensions(tag_or_tag_key)
+      tag = Tag[tag_or_tag_key]
+      extensions_map[tag]
+    end
+
+    #
+    # Pushes an item into a pool.
+    #
+    # Can be given:
+    # * SourceFile
+    # * Package (pushing all the child source files into the pool)
+    # * Array or Container (pushing all the contained source files into the pool)
+    #
+    # returns self.
     def <<(source_or_sources_or_package)
-      case 
+      case
       when source_or_sources_or_package.kind_of?(SourceFile)
-        source = source_or_sources_or_package
+        source = source_or_sources_or_package        
         sources << source
-        source.provides.each {|p| provides_map[p] = source }
+        if source.extends
+          extensions_map[source.extends] ||= []
+          extensions_map[source.extends] << source
+        else
+          source.provides.each {|p| provides_map[p] = source }
+        end
       when source_or_sources_or_package.kind_of?(Package)
         package = source_or_sources_or_package
         packages << package
-        package.source_files.each {|s| self << s}
+        package.source_files.each {|s| s.pool = self }
+        package.extensions.each {|e| e.pool = self }
       when source_or_sources_or_package.kind_of?(Array) || source_or_sources_or_package.kind_of?(Container)
         sources = source_or_sources_or_package
         sources.each {|s| self << s}
@@ -66,11 +124,26 @@ module Jsus
     end
 
     (Array.instance_methods - self.instance_methods).each {|m| delegate m, :to => :sources }
+    # Private API
+    
+    # 
+    # Looks up direct dependencies for the given source_file or provides tag.
+    # You probably will find yourself using #include_dependencies instead.
+    #
+    def lookup_direct_dependencies(source_or_source_key)      
+      source = lookup(source_or_source_key)
+      result = source ? source.external_dependencies.map {|d| lookup(d)} : []
+      Container.new(*result)
+    end
 
     protected
 
-    def provides_map
+    def provides_map # :nodoc:
       @provides_map ||= {}
     end
+
+    def extensions_map # :nodoc:
+      @extensions_map ||= Hash.new{|hash, key| hash[key] = [] }
+    end
   end
 end

data/lib/jsus/source_file.rb

@@ -1,18 +1,39 @@
+#
+# SourceFile is a base for any Jsus operation.
+# 
+# It contains basic info about source as well as file content.
+#
+#
 module Jsus
   class SourceFile
-    attr_accessor :relative_filename
-    attr_accessor :filename
-    attr_accessor :content
-    attr_accessor :package
-    # constructors
+    attr_accessor :relative_filename, :filename, :package # :nodoc:
+    # Constructors
 
+    # Basic constructor.
+    #
+    # You probably should use SourceFile.from_file instead.
+    #
+    # But if you know what you are doing, it accepts the following values:
+    # * +package+ — an instance of Package, normally passed by a parent
+    # * +relative_filename+ — used in Package, for generating tree structure of the source files
+    # * +filename+ — full filename for the given package
+    # * +content+ — file content of the source file
+    # * +pool+ — an instance of Pool
     def initialize(options = {})
-      [:header, :relative_filename, :filename, :content, :package].each do |field|
+      [:package, :header, :relative_filename, :filename, :content, :pool].each do |field|
         send("#{field}=", options[field]) if options[field]
       end
-      options[:pool] << self if options[:pool]
     end
 
+    #
+    # Initializes a SourceFile given the filename and options
+    # 
+    # options:
+    # * <tt>:pool:</tt> — an instance of Pool
+    # * <tt>:package:</tt> — an instance of Package
+    #
+    # returns either an instance of SourceFile or nil when it's not possible to parse the input
+    #
     def self.from_file(filename, options = {})
       if File.exists?(filename)
         source = File.read(filename)
@@ -24,70 +45,183 @@ module Jsus
           options[:content]           = source
           new(options)
         else
-          #puts "WARNING: file #{filename} has invalid format (should be YAML)"
+#          puts "WARNING: file #{filename} has invalid format (should be YAML)"
           nil
         end
       else
-        #puts "WARNING: file #{filename} does not exist"
+#        puts "WARNING: file #{filename} does not exist"
         nil
       end
     end
 
     # Public API
-    def header=(new_header)
-      @header = new_header
-      # prepare defaults
-      @header["description"] ||= ""
-      @header["requires"] = [@header["requires"] || []].flatten
-      @header["requires"].map! {|r| r.gsub(/^(\.)?\//, "") }
-      @header["provides"] = [@header["provides"] || []].flatten
-    end
 
+    #
+    # Returns a header parsed from YAML-formatted source file first comment.
+    # Contains information about authorship, naming, source files, etc.
+    #
     def header
       self.header = {} unless @header
       @header
     end
 
-    def dependencies(options = {})            
-      if !options[:short] && package
-        header["requires"].map {|r| r.index("/") ? r : "#{package.name}/#{r}"}
-      else
-        header["requires"]
-      end
+    #
+    # A string containing the description of the source file.
+    #
+    def description
+      header["description"]
+    end
+
+    # 
+    # Returns an array of dependencies tags. Unordered.
+    #
+    def dependencies
+      @dependencies
     end
     alias_method :requires, :dependencies
 
+    #
+    # Returns an array with names of dependencies. Unordered.
+    # Accepts options:
+    # * <tt>:short:</tt> — whether inner dependencies should not prepend package name
+    #   e.g. 'Class' instead of 'Core/Class' when in package 'Core').
+    #   Doesn't change anything for external dependencies
+    #
+    def dependencies_names(options = {})
+      dependencies.map {|d| d.name(options) }
+    end    
+    alias_method :requires_names, :dependencies_names
+
+    #
+    # Returns an array of external dependencies tags. Unordered.
+    #
     def external_dependencies
-      dependencies(:short => true).select {|d| d.index("/") }
+      dependencies.select {|d| d.external? }
     end
 
-    def internal_dependencies
-      dependencies(:short => true) - external_dependencies
+    #
+    # Returns an array with names for external dependencies. Unordered.
+    #
+    def external_dependencies_names
+      external_dependencies.map {|d| d.name }
     end
 
-    def provides(options = {})      
-      if !options[:short] && package
-        header["provides"].map {|p| "#{package.name}/#{p}"}
-      else
-        header["provides"]
+    # 
+    # Returns an array with provides tags.
+    #
+    def provides
+      @provides
+    end
+        
+    # 
+    # Returns an array with provides names. 
+    # Accepts options:
+    # * <tt>:short:</tt> — whether provides should not prepend package name
+    #   e.g. 'Class' instead of 'Core/Class' when in package 'Core')
+    def provides_names(options = {})
+      provides.map {|p| p.name(options)}
+    end
+
+
+    #
+    # Returns a tag for source file, which this one is an extension for.
+    #
+    # E.g.: file Foo.js in package Core provides ['Class', 'Hash']. File Bar.js in package Bar
+    # extends 'Core/Class'. That means its contents would be appended to the Foo.js when compiling 
+    # the result.
+    #
+    def extends
+      @extends
+    end
+
+    #
+    # Returns whether the source file is an extension.
+    #
+    def extension?
+      extends && !extends.empty?
+    end
+
+    #
+    # Returns an array of included extensions for given source.
+    #
+    def extensions
+      @extensions ||= []
+      @extensions = @extensions.flatten.compact.uniq
+      @extensions
+    end
+        
+    def extensions=(new_value) # :nodoc:
+      @extensions = new_value
+    end
+
+    #
+    # Looks up for extensions in the #pool and then includes
+    # extensions for all the provides tag this source file has.
+    #
+    def include_extensions!
+      if pool        
+        provides.each do |p|
+          extensions << pool.lookup_extensions(p)
+        end
       end
     end
 
-    def description
-      header["description"]
+    # 
+    # Returns an array of files required by this files including all the filenames for extensions.
+    # SourceFile filename always goes first, all the extensions are unordered.
+    # 
+    def required_files
+      [filename, extensions.map {|e| e.filename}].flatten
     end
 
+    # 
+    # Returns a hash containing basic info with dependencies/provides tags' names
+    # and description for source file.
+    #
     def to_hash
       {
         "desc"     => description,
-        "requires" => dependencies(:short => true),
-        "provides" => provides(:short => true)
+        "requires" => dependencies_names(:short => true),
+        "provides" => provides_names(:short => true)
       }
     end
 
-    def inspect
+    def inspect # :nodoc:
       self.to_hash.inspect
     end
+    # Private API
+    
+    def header=(new_header) # :nodoc:
+      @header = new_header
+      # prepare defaults
+      @header["description"] ||= ""
+      # handle tags
+      @dependencies = [@header["requires"] || []].flatten
+      @dependencies.map! {|tag_name| Tag.new(tag_name, :package => package) }
+      @provides = [@header["provides"] || []].flatten
+      @provides.map! {|tag_name| Tag.new(tag_name, :package => package) }
+      @extends = (@header["extends"] && !@header["extends"].empty?) ? Tag.new(@header["extends"]) : nil
+    end
+
+    def content=(new_value) # :nodoc:
+      @content = new_value
+    end
+
+    def content # :nodoc:
+      [@content, extensions.map {|e| e.content}].flatten.compact.join("\n")
+    end 
+    
+    # Assigns an instance of Jsus::Pool to the source file.
+    # Also performs push to that pool.
+    def pool=(new_value)
+      @pool = new_value
+      @pool << self if @pool
+    end
 
+    # A pool which the source file is assigned to. Used in #include_extensions!
+    def pool
+      @pool
+    end
+    
   end
 end

data/lib/jsus/tag.rb

@@ -0,0 +1,142 @@
+#
+# Tag is basically just a string that contains a package name and a name for class
+# (or not necessarily a class) which the given SourceFile provides/requires/extends.
+#
+module Jsus
+  class Tag
+    attr_accessor :package, :external # :nodoc:
+
+    # Constructors
+    
+    #
+    # Creates a tag from given name/options.
+    # 
+    # The way it works may seem a bit tricky but actually it parses name/options
+    # combinations in different ways and may be best described by examples:
+    #
+    #     a = Tag.new("Class")      # :package_name => "",     :name => "Class", :external => false
+    #     b = Tag.new("Core/Class") # :package_name => "Core", :name => "Class", :external => true
+    #     core = Package.new(...) # let's consider its name is 'Core'
+    #     c = Tag.new("Class", :package => core) # :package_name => "Core", :name => "Class", :external => false
+    #     d = Tag.new("Core/Class", :package => core) # :package_name => "Core", :name => "Class", :external => false
+    #     mash = Package.new(...) # let's consider its name is 'Mash'
+    #     e = Tag.new("Core/Class", :package => mash) # :package_name => "Core", :name => "Class", :external => true
+    # 
+    # Between all those, tags b,c,d and e are equal, meaning they all use 
+    # the same spot in Hash or whatever else.
+    #
+    def initialize(name, options = {})
+      normalized_options = Tag.normalize_name_and_options(name, options)
+      [:name, :package, :package_name, :external].each do |field|
+        self.send("#{field}=", normalized_options[field])
+      end
+    end
+
+    def self.new(tag_or_name, *args, &block) # :nodoc:
+      if tag_or_name.kind_of?(Tag)
+        tag_or_name
+      else
+        super
+      end
+    end
+
+    # alias for Tag.new
+    def self.[](*args)
+      new(*args)
+    end
+
+    # Public API
+
+    #
+    # Returns true if tag is external. See initialization for more info on cases.
+    #
+    def external?
+      !!external
+    end
+
+    #
+    # Returns a well-formed name for the tag.
+    # Options:
+    # * +:short:+ — whether the tag should try using short form
+    #
+    # Important note: only non-external tags support short forms.
+    # 
+    #    Tag.new('Core/Class').name(:short => true) # => 'Core/Class'
+    #    core = Package.new(...) # let's consider its name is 'Core'
+    #    Tag.new('Core/Class', :package => core).name(:short => true) # => 'Class'
+    def name(options = {})
+      if !package_name || package_name.empty? || (options[:short] && !external?)
+        @name
+      else
+        "#{package_name}/#{@name}"
+      end
+    end
+    alias_method :to_s, :name
+
+    # Returns its package name or an empty string
+    def package_name
+      @package_name ||= (@package ? @package.name : "")
+    end
+
+    # Returns true if its name is empty
+    def empty?
+      @name.empty?
+    end
+
+    # Returns true if it has the same name as other tag
+    def ==(other)
+      if other.kind_of?(Tag)
+        self.name == other.name
+      else
+        super
+      end
+    end
+    
+    # Private API
+    
+    def self.normalize_name_and_options(name, options = {}) # :nodoc:
+      result = {}
+      name.gsub!(%r(^(\.)?/), "")
+      if name.index("/")
+        parsed_name = name.split("/")
+        result[:package_name], result[:name] = parsed_name[0..-2].join("/"), parsed_name[-1]
+        result[:external] = options[:package] ? (result[:package_name] != options[:package].name) : true
+      else
+        if options[:package]
+          result[:package] = options[:package]
+          result[:package_name] = options[:package].name
+        end
+        result[:name] = name
+      end
+      result
+    end
+
+    def self.normalized_options_to_full_name(options) # :nodoc:
+      [options[:package_name], options[:name]].compact.join("/")
+    end
+
+    def self.name_and_options_to_full_name(name, options = {}) # :nodoc:
+      normalized_options_to_full_name(normalize_name_and_options(name, options))
+    end
+        
+    def package_name=(new_value) # :nodoc:
+      @package_name = new_value
+    end
+
+    def name=(new_value) # :nodoc:
+      @name = new_value
+    end
+
+    def eql?(other) # :nodoc:
+      self.==(other)
+    end
+
+    def hash # :nodoc:
+      self.name.hash
+    end
+
+    def inspect # :nodoc
+      "<Jsus::Tag: #{name}>"
+    end    
+  end
+end