jsus 0.2.5 → 0.2.6

data/lib/jsus/tag.rb

@@ -1,8 +1,8 @@
-#
-# 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
+  #
+  # 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/replaces.
+  #  
   class Tag
     attr_accessor :package, :external # :nodoc:
 
@@ -57,7 +57,7 @@ module Jsus
     #
     # Returns a well-formed name for the tag.
     # Options:
-    # * +:short:+ — whether the tag should try using short form
+    # * +:short:+ -- whether the tag should try using short form
     #
     # Important note: only non-external tags support short forms.
     # 

data/lib/jsus/util.rb

@@ -0,0 +1,7 @@
+module Jsus
+  module Util
+    autoload :Tree,       'jsus/util/tree'
+    autoload :Documenter, 'jsus/util/documenter'
+    autoload :Validator,  'jsus/util/validator'
+  end # Util
+end # Jsus

data/lib/jsus/util/documenter.rb

@@ -0,0 +1,118 @@
+module Jsus
+  module Util
+    # Very opinionated documenter class. It uses Murdoc to generate the
+    # documentation using the template and stylesheet bundled with the
+    # jsus gem file. Also generates indices for navigation.
+    class Documenter
+      # Default documenter options
+      DEFAULT_OPTIONS = {:highlight_source => true}
+
+      # Documenter options
+      attr_accessor :options
+
+      # Constructor. Accepts options as the argument.
+      def initialize(options = DEFAULT_OPTIONS)
+        require "murdoc"
+        self.options = options
+      rescue LoadError
+        raise "You should install murdoc gem in order to produce documentation"
+      end
+
+      # Generates documentation tree into the given directory.
+      def generate(doc_dir = Dir.pwd)
+        #FileUtils.rm_rf(doc_dir)
+        FileUtils.mkdir_p(doc_dir)
+        template_path = File.dirname(__FILE__) + "/../../../markup"
+        template = File.read("#{template_path}/template.haml")
+        index_template = File.read("#{template_path}/index_template.haml")
+        stylesheet_path = "#{template_path}/stylesheet.css"
+        documented_sources.traverse(true) do |node|
+          if node.value # leaf
+            dir = doc_dir + File.dirname(node.full_path)
+            FileUtils.mkdir_p(dir)
+            file_from_contents(dir + "/#{node.name}.html", create_documentation_for_source(node.value, template))
+          else
+            dir = doc_dir + node.full_path
+            FileUtils.mkdir_p(dir)
+            FileUtils.cp(stylesheet_path, dir)
+            file_from_contents(dir + "/index.html", create_index_for_node(node, index_template))
+          end
+        end
+      end
+
+      # Adds a source file to the documented source tree
+      def <<(source) # :nodoc:
+        filename = File.basename(source.filename)
+        if source.package
+
+          tree["#{source.package.name}/#{filename}"] = source
+        else
+          tree["#{filename}"] = source
+        end
+        self
+      end
+
+      def tree # :nodoc:
+        @tree ||= Tree.new
+      end
+
+      # Scope for documentation in pathspec format. See Jsus::Util::Tree::Node#find_children_matching
+      def current_scope
+        @current_scope ||= default_scope
+      end
+
+      def default_scope # :nodoc:
+        ["/**/*"]
+      end
+
+      def current_scope=(scope) # :nodoc:
+        @current_scope = scope
+      end
+
+      # Sets documenter to exclusive scope for documentation.
+      # Exclusive scope overrides all the other scopes.
+      def only(scope)
+        result = clone
+        result.current_scope = [scope].flatten
+        result
+      end
+
+      # Sets documenter to additive scope for documentation.
+      # Additive scopes match any of the pathspecs given
+      def or(scope)
+        result = clone
+        result.current_scope = current_scope + [scope].flatten
+        result
+      end
+
+      # Returns the tree with documented sources.
+      def documented_sources
+        @documented_sources ||= documented_sources!
+      end
+
+      def documented_sources! # :nodoc:
+        doctree = Tree.new
+        current_scope.map {|pathspec| tree.find_nodes_matching(pathspec) }.
+                      flatten.each {|s| doctree.insert(s.full_path, s.value)}
+        doctree
+      end
+
+      protected
+
+      def create_documentation_for_source(source, template) # :nodoc:
+        skipped_lines = 0
+        content = source.original_content.gsub(/\A\s*\/\*.*?\*\//m) {|w| skipped_lines += w.split("\n").size; "" }
+        annotator = Murdoc::Annotator.new(content, :javascript, options)
+        Murdoc::Formatter.new(template).render(:paragraphs => annotator.paragraphs, :header => source.header, :source => source, :skipped_lines => skipped_lines)
+      end
+
+      def create_index_for_node(node, template) # :nodoc:
+        Haml::Engine.new(template).render(self, :node => node)
+      end
+
+      def file_from_contents(filename, contents) # :nodoc:
+        File.open(filename, "w+") {|f| f << contents }
+      end
+    end
+  end
+end

data/lib/jsus/util/tree.rb

@@ -0,0 +1,201 @@
+module Jsus
+  module Util
+    #
+    # Jsus::Tree is a basic hierarchical tree structure class
+    # What it does, basically, is maintaining hierarchical filesystem-like
+    # structure (with node names like /namespace/inner/item) and supporting
+    # lookups via #glob method.
+    #
+    # Example:
+    #
+    #     tree = Jsus::Tree.new
+    #     tree["/folder/item_0"] = "Hello"
+    #     tree["/folder/item_1"] = "World"
+    #     tree["/other/soul"]    = "Empty"
+    #     tree.glob("/*")         # => 3 Jsus::Node-s (`root`, `folder`, `other`)
+    #     tree.glob("/**/*")      # => 6 Jsus::Node-s (`root`, `folder`, `other`, `item_0`, `item_1`, `soul`)
+    #     tree["/something"]      # => nil
+    #     tree["/folder/item_1"]  # => Jsus::Node
+    #     tree["/other/soul"] = nil
+    #     tree.leaves(true)       # => 2 Jsus::Node-s (no `soul` node)
+    #     tree.leaves(false)      # => 3 Jsus::Node-s
+    #
+    class Tree
+      PATH_SEPARATOR = "/"
+
+
+      class <<self
+        # Utility functions
+
+        # Splits path into components
+        #     Jsus::Tree.components_from_path("/hello/world") # => ["hello", "world"]
+        def components_from_path(path)
+          raise "Empty path given: #{path.inspect}" if !path || path == ""
+          path = path.to_s.dup
+          path.split(PATH_SEPARATOR).reject {|comp| comp == "" }
+        end
+        alias_method :get_path_components, :components_from_path
+
+        # Joins components into a pathspec
+        #     Jsus::Tree.path_from_components(["hello", "world"]) # => "/hello/world"
+        def path_from_components(components)
+          "#{PATH_SEPARATOR}#{components.join(PATH_SEPARATOR)}"
+        end
+      end
+
+      #
+      # Jsus::Tree node class.
+      # Most of the time you only need to extract #value from the node,
+      # although sometimes you might need to refer to #parent node and #full_path
+      #
+      class Node
+        # Contains assigned value
+        attr_accessor :value
+        # Contains reference to parent node, nil for root node
+        attr_accessor :parent
+        # Contains array with path components
+        attr_accessor :path_components
+
+        # Initializes full path and value for the node
+        def initialize(full_path, value = nil)
+          self.full_path = full_path
+          self.value = value
+        end
+
+        # Contains full path to the node, such as '/hello/world'
+        attr_reader :full_path
+        # Contains node basename, such as 'world' for '/hello/world'
+        attr_reader :name
+        # Assigns node's full path and automatically deduces path components,
+        # basename etc.
+        def full_path=(full_path)
+          @full_path = full_path
+          @path_components = Tree.get_path_components(full_path)
+          @name = @path_components[-1]
+        end
+
+        # Returns node's direct descendants
+        def children
+          @children ||= []
+        end
+
+        # Finds a node child by basename
+        def find_child(name)
+          children.detect {|child| child.name == name }
+        end
+
+        # Creates a child with given name and value
+        def create_child(name, value = nil)
+          full_path = Tree.path_from_components(path_components + [name])
+          node = Node.new(full_path, value)
+          children << node
+          node.parent = self
+          node
+        end
+
+        # Finds a child with given name or creates a child with given name and
+        # value
+        def find_or_create_child(name, value = nil)
+          find_child(name) || create_child(name, value)
+        end
+
+        # Finds children matching the given pathspec
+        # Pathspec format:
+        #    '**' -- this node and all the children nodes that have children
+        #    'smth*' -- nodes beginning with smth
+        #    'smth*else' -- nodes beginning with smth and ending with else
+        #    <string without asterisks> -- plain node lookup by name
+        # Returns array with search results
+        def find_children_matching(pathspec)
+          case pathspec
+            when "**"
+              [self] + children.select {|child| child.has_children? }
+            when /\*/
+              regexp = Regexp.new("^" + Regexp.escape(pathspec).gsub("\\*", ".*") + "$")
+              children.select {|child| !child.has_children? && child.name =~ regexp }
+            else
+              [find_child(pathspec)].compact
+          end
+        end
+
+        # Returns whether this node has children
+        def has_children?
+          !children.empty?
+        end
+      end
+
+      # Root node of the tree
+      def root
+        @root ||= Node.new("/", nil)
+      end
+
+      # Looks up a node by direct path. Does not support wildcards
+      def lookup(path)
+        path_components = self.class.get_path_components(path)
+        path_components.inject(root) do |result, component|
+          if result
+            result.find_child(component)
+          end
+        end
+      end
+
+      def [](path)
+        node = lookup(path)
+        node ? node.value : nil
+      end
+
+
+
+      # Searches for nodes by a given pathspec
+      # See Jsus::Util::Tree::Node#find_children_matching for more details
+      def find_nodes_matching(pathspec)
+        self.class.get_path_components(pathspec).inject([root]) do |nodes, component|
+          nodes.map {|node| node.find_children_matching(component) }.flatten
+        end
+      end
+
+      # Returns values for nodes matching given pathspec
+      # See Jsus::Util::Tree::Node#find_children_matching for more details
+      def glob(pathspec)
+        find_nodes_matching(pathspec).map {|node| node.value }
+      end
+
+      # Inserts a node with given value into the tree
+      def insert(full_path, value = nil)
+        node = create_all_nodes_if_needed(full_path)
+        node.value = value
+        node
+      end
+      alias_method :[]=, :insert
+
+      # Traverses the tree.
+      # When given true as the argument, traverses all nodes.
+      # Otherwise, only leaves.
+      def traverse(all_nodes = false)
+        node_list = [root]
+        while !node_list.empty?
+          node = node_list.shift
+          yield node if all_nodes || !node.has_children?
+          node.children.each {|child| node_list << child }
+        end
+      end
+
+      # Returns a list of leaves.
+      # Returns only leaves with set values by default
+      def leaves(only_with_value = true)
+        result = []
+        traverse {|node| result << node if !only_with_value || node.value }
+        result
+      end
+
+      protected
+
+      def create_all_nodes_if_needed(full_path) # :nodoc:
+        self.class.get_path_components(full_path).inject(root) do |result, component|
+          result.find_or_create_child(component)
+        end
+      end
+
+    end
+  end
+end

data/lib/jsus/util/validator.rb

@@ -0,0 +1,8 @@
+module Jsus
+  module Util
+    module Validator
+      autoload :Base,     'jsus/util/validator/base'
+      autoload :Mooforge, 'jsus/util/validator/mooforge'
+    end # Validator
+  end # Util
+end # Jsus

data/lib/jsus/util/validator/base.rb

@@ -0,0 +1,48 @@
+module Jsus
+  module Util
+    # Base for any validator class.
+    module Validator
+      class Base
+        # Constructor accepts pool or array or container and adds every file
+        # to its source files set.
+        def initialize(pool_or_array_or_container)
+          self.source_files = pool_or_array_or_container
+        end
+
+        # Returns source files for validation
+        def source_files
+          @source_files ||= []
+        end
+        alias_method :sources, :source_files
+
+        # Sets source files for validation
+        def source_files=(pool_or_array_or_container)
+          case pool_or_array_or_container
+          when Pool
+            @source_files = pool_or_array_or_container.sources.to_a
+          when Array
+            @source_files = pool_or_array_or_container
+          when Container
+            @source_files = pool_or_array_or_container.to_a
+          end
+        end
+        alias_method :sources=, :source_files=
+
+        # Returns whether or not given sources conform to given set of rules
+        def validate
+          validation_errors.empty?
+        end
+
+        # List of validation errors, override this method on descendant classes.
+        def validation_errors
+          []
+        end
+
+        # Shortcut for creating and validating a list of items
+        def self.validate(*args)
+          new(*args).validate
+        end
+      end
+    end
+  end # Util
+end

data/lib/jsus/util/validator/mooforge.rb

@@ -0,0 +1,25 @@
+module Jsus
+  module Util
+    module Validator
+      # Mooforge validator checks every file for the following:
+      #   * Presence of header
+      #   * Presence of authors field
+      #   * Presence of license field
+      class Mooforge < Base
+        def validation_errors # :nodoc:
+          @validation_errors ||= sources.inject([]) do |result, sf|
+            if !sf.header
+              result << "#{sf.filename} is missing header"
+            elsif !sf.header["authors"]
+              result << "#{sf.filename} is missing authors"
+            elsif !sf.header["license"]
+              result << "#{sf.filename} is missing license"
+            else
+              result
+            end
+          end
+        end
+      end
+    end
+  end # Util
+end

data/spec/jsus/pool_spec.rb

@@ -147,7 +147,7 @@ describe Jsus::Pool do
     subject { Jsus::Pool.new(input_dir) }
 
     it "should return a tree with all the source elements in it" do
-      subject.source_tree["/Core/Class.js"].value.should be_a(Jsus::SourceFile)
+      subject.source_tree["/Core/Class.js"].should be_a(Jsus::SourceFile)
     end
 
     it "should not choke when sources got no referenced package" do
@@ -161,11 +161,11 @@ describe Jsus::Pool do
     subject { Jsus::Pool.new(input_dir) }
 
     it "should return a tree with all the source elements in it" do
-      subject.provides_tree.glob("/Core/Class")[0].value.should == Jsus::Tag["Core/Class"]
+      subject.provides_tree.glob("/Core/Class")[0].should == Jsus::Tag["Core/Class"]
     end
         
     it "should allow wildcards" do
-      subject.provides_tree.glob("/Core/*")[0].value.should == Jsus::Tag["Core/Class"]
+      subject.provides_tree.glob("/Core/*")[0].should == Jsus::Tag["Core/Class"]
     end
   end