kss 0.2.0 → 0.3.0

data/lib/kss.rb

@@ -1,7 +1,4 @@
-require 'sass'
-require 'v8'
-require 'less'
-
+require 'kss/comment_parser'
 require 'kss/modifier'
 require 'kss/parser'
 require 'kss/section'

data/lib/kss/comment_parser.rb

@@ -0,0 +1,164 @@
+module Kss
+  # Public: Takes a file path of a text file and extracts comments from it.
+  # Currently accepts two formats:
+  #
+  # // Single line style.
+  # /* Multi-line style. */
+  class CommentParser
+
+    # Public: Is this a single-line comment? // This style
+    #
+    # line - A String of one line of text.
+    #
+    # Returns a boolean.
+    def self.single_line_comment?(line)
+      !!(line =~ /^\s*\/\//)
+    end
+
+    # Public: Is this the start of a multi-line comment? /* This style */
+    #
+    # line - A String of one line of text.
+    #
+    # Returns a boolean.
+    def self.start_multi_line_comment?(line)
+      !!(line =~ /^\s*\/\*/)
+    end
+
+    # Public: Is this the end of a multi-line comment? /* This style */
+    #
+    # line - A String of one line of text.
+    #
+    # Returns a boolean.
+    def self.end_multi_line_comment?(line)
+      return false if self.single_line_comment?(line)
+      !!(line =~ /.*\*\//)
+    end
+
+    # Public: Removes comment identifiers for single-line comments.
+    #
+    # line - A String of one line of text.
+    #
+    # Returns a String.
+    def self.parse_single_line(line)
+      cleaned = line.to_s.sub(/\s*\/\//, '')
+      cleaned.rstrip
+    end
+
+    # Public: Remove comment identifiers for multi-line comments.
+    #
+    # line - A String of one line of text.
+    #
+    # Returns a String.
+    def self.parse_multi_line(line)
+      cleaned = line.to_s.sub(/\s*\/\*/, '')
+      cleaned = cleaned.sub(/\*\//, '')
+      cleaned.rstrip
+    end
+
+    # Public: Initializes a new comment parser object. Does not parse on
+    # initialization.
+    #
+    # file_path - The location of the file to parse as a String.
+    # options   - Optional options hash.
+    #   :preserve_whitespace - Preserve the whitespace before/after comment
+    #                          markers (default:false).
+    #
+    def initialize(file_path, options={})
+      @options = options
+      @options[:preserve_whitespace] = false if @options[:preserve_whitespace].nil?
+      @file_path = file_path
+      @blocks = []
+      @parsed = false
+    end
+
+    # Public: The different sections of parsed comment text. A section is
+    # either a multi-line comment block's content, or consecutive lines of
+    # single-line comments.
+    #
+    # Returns an Array of parsed comment Strings.
+    def blocks
+      @parsed ? @blocks : parse_blocks
+    end
+
+
+    # Parse the file for comment blocks and populate them into @blocks.
+    #
+    # Returns an Array  of parsed comment Strings.
+    def parse_blocks
+      File.open @file_path do |file|
+        current_block = nil
+        inside_single_line_block = false
+        inside_multi_line_block  = false
+
+        file.each_line do |line|
+          # Parse single-line style
+          if self.class.single_line_comment?(line)
+            parsed = self.class.parse_single_line line
+            if inside_single_line_block
+              current_block += "\n#{parsed}"
+            else
+              current_block = parsed.to_s
+              inside_single_line_block = true
+            end
+          end
+
+          # Parse multi-lines tyle
+          if self.class.start_multi_line_comment?(line) || inside_multi_line_block
+            parsed = self.class.parse_multi_line line
+            if inside_multi_line_block
+              current_block += "\n#{parsed}"
+            else
+              current_block = parsed
+              inside_multi_line_block = true
+            end
+          end
+
+          # End a multi-line block if detected
+          inside_multi_line_block = false if self.class.end_multi_line_comment?(line)
+
+          # Store the current block if we're done
+          unless self.class.single_line_comment?(line) || inside_multi_line_block
+            @blocks << normalize(current_block) unless current_block.nil?
+
+            inside_single_line_block = false
+            current_block = nil
+          end
+        end
+      end
+
+      @parsed = true
+      @blocks
+    end
+
+    # Normalizes the comment block to ignore any consistent preceding
+    # whitespace. Consistent means the same amount of whitespace on every line
+    # of the comment block. Also strips any whitespace at the start and end of
+    # the whole block.
+    #
+    # Returns a String of normalized text.
+    def normalize(text_block)
+      return text_block if @options[:preserve_whitespace]
+
+      # Strip out any preceding [whitespace]* that occur on every line. Not
+      # the smartest, but I wonder if I care.
+      text_block = text_block.gsub(/^(\s*\*+)/, '')
+
+      # Strip consistent indenting by measuring first line's whitespace
+      indent_size = nil
+      unindented = text_block.split("\n").collect do |line|
+        preceding_whitespace = line.scan(/^\s*/)[0].to_s.size
+        indent_size = preceding_whitespace if indent_size.nil?
+        if line == ""
+          ""
+        elsif indent_size <= preceding_whitespace && indent_size > 0
+          line.slice(indent_size, line.length - 1)
+        else
+          line
+        end
+      end.join("\n")
+
+      unindented.strip
+    end
+
+  end
+end

data/lib/kss/parser.rb

@@ -2,7 +2,10 @@ module Kss
   # Public: The main KSS parser. Takes a directory full of SASS / SCSS / CSS
   # files and parses the KSS within them.
   class Parser
-
+    
+    # Public: Returns a hash of Sections.
+    attr_accessor :sections
+    
     # Public: Initializes a new parser based on a directory of files. Scans
     # within the directory recursively for any comment blocks that look like
     # KSS.
@@ -12,73 +15,17 @@ module Kss
       @sections = {}
 
       Dir["#{base_path}/**/*.*"].each do |filename|
-        if File.extname(filename) == ".less"
-          tree = Less::Parser.new(:paths => [base_path], :filename => filename).
-            # HACK: get the internal JS tree object
-            parse(File.read(filename)).instance_variable_get "@tree"
-
-          # inject less.js into a new V8 context
-          less = Less.instance_variable_get "@less"
-          cxt = V8::Context.new
-          cxt['less'] = less
-
-          # parse node tree for comments
-          parse_v8_node(cxt, tree, filename)
-        else
-          if filename.match(/\.css$/)
-            root_node = Sass::SCSS::Parser.new(File.read(filename), filename).parse
-          else
-            root_node = Sass::Engine.for_file(filename, {}).to_tree
-          end
-          parse_sass_node(root_node, filename)
+        parser = CommentParser.new(filename)
+        parser.blocks.each do |comment_block|
+          add_section comment_block, filename if self.class.kss_block?(comment_block)
         end
       end
     end
 
-    # Given a Sass::Tree::Node, find all CommentNodes and populate @sections
-    # with parsed Section objects.
-    #
-    # parent_node - A Sass::Tree::Node to start at.
-    # filename    - The filename String this node is found at.
-    #
-    # Returns the Sass::Tree::Node given.
-    def parse_sass_node parent_node, filename
-      parent_node.children.each do |node|
-        unless node.is_a? Sass::Tree::CommentNode
-          parse_sass_node(node, filename) if node.has_children
-          next
-        end
-        comment_text = self.class.clean_comments node.to_scss
-        add_section node.to_scss, filename
-      end
-      parent_node
-    end
-
-    def parse_v8_node cxt, parent_node, filename
-      parent_node.rules.each do |node|
-        # inject the current to into JS context
-        cxt['node'] = node
-
-        unless cxt.eval "node instanceof less.tree.Comment"
-          parse_v8_node(cxt, node, filename) if cxt.eval 'node.rules != null'
-
-          next
-        end
-
-        add_section node.value, filename
-      end
-
-      parent_node
-    end
-
-    def add_section comment, filename
-      comment_text = self.class.clean_comments comment
-
-      if self.class.kss_block? comment_text
-        base_name = File.basename(filename)
-        section = Section.new(comment_text, base_name)
-        @sections[section.section] = section
-      end
+    def add_section comment_text, filename
+      base_name = File.basename(filename)
+      section = Section.new(comment_text, base_name)
+      @sections[section.section] = section
     end
 
     # Public: Takes a cleaned (no comment syntax like // or /* */) comment
@@ -92,32 +39,6 @@ module Kss
       possible_reference =~ /Styleguide \d/
     end
 
-    # Takes the raw comment text including comment syntax and strips all
-    # comment syntax and normalizes the indention and whitespace to generate
-    # a clean comment block.
-    #
-    # Returns a claned comment String.
-    def self.clean_comments(text)
-      text.strip!
-
-      # SASS generated multi-line comment syntax
-      text.gsub!(/(\/\* )?( \*\/)?/, '') # [/* + space] or [space + */]
-      text.gsub!(/\n\s\* ?/, "\n") # * in front of every line
-
-      # SASS generated single-line comment syntax
-      text.gsub!(/\/\/ /, '') # [// + space]
-      text.gsub!(/\/\/\n/, "\n") # [// + carriage return]
-
-      # Manual generated comment syntax
-      text.gsub!(/^\/\*/, '') # starting block
-      text.gsub!(/\*\/$/, '') # ending block
-
-      text.gsub!(/^[ \t]+/, '') # remove leading whitespace
-
-      text.strip!
-      text
-    end
-
     # Public: Finds the Section for a given styleguide reference.
     #
     # Returns a Section for a reference, or a blank Section if none found.

data/lib/kss/version.rb

@@ -1,3 +1,3 @@
 module Kss
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/test/comment_parser_test.rb

@@ -0,0 +1,73 @@
+require 'test/helper'
+
+class CommentParser < Kss::Test
+
+  def setup
+    loc = 'test/fixtures/comments.txt'
+    @parsed_comments = Kss::CommentParser.new(loc).blocks
+  end
+
+  test "detects single-line comment syntax" do
+    assert Kss::CommentParser.single_line_comment?("// yuuuuup")
+    assert !Kss::CommentParser.single_line_comment?("nooooope")
+  end
+
+  test "detects start of multi--line comment syntax" do
+    assert Kss::CommentParser.start_multi_line_comment?("/* yuuuuup")
+    assert !Kss::CommentParser.start_multi_line_comment?("nooooope")
+  end
+
+  test "detects end of multi-line comment syntax" do
+    assert Kss::CommentParser.end_multi_line_comment?(" yuuuuup */")
+    assert !Kss::CommentParser.end_multi_line_comment?("nooooope")
+  end
+
+  test "parses the single-line comment syntax" do
+    assert_equal " yuuuuup", Kss::CommentParser.parse_single_line("// yuuuuup")
+  end
+
+  test "parses the multi-line comment syntax" do
+    assert_equal " yuuuup", Kss::CommentParser.parse_multi_line("/* yuuuup */")
+  end
+
+  test "finds single-line comment styles" do
+    expected  = <<comment
+This comment block has comment identifiers on every line.
+
+Fun fact: this is Kyle's favorite comment syntax!
+comment
+    assert @parsed_comments.include? expected.rstrip
+  end
+
+  test "finds block-style comment styles" do
+        expected  = <<comment
+This comment block is a block-style comment syntax.
+
+There's only two identifier across multiple lines.
+comment
+    assert @parsed_comments.include? expected.rstrip
+
+
+      expected  = <<comment
+This is another common multi-line comment style.
+
+It has stars at the begining of every line.
+comment
+  assert @parsed_comments.include? expected.rstrip
+
+  end
+
+  test "handles mixed styles" do
+    expected = "This comment has a /* comment */ identifier inside of it!"
+    assert @parsed_comments.include? expected
+
+    expected = "Look at my //cool// comment art!"
+    assert @parsed_comments.include? expected
+  end
+
+  test "handles indented comments" do
+    assert @parsed_comments.include? "Indented single-line comment."
+    assert @parsed_comments.include? "Indented block comment."
+  end
+
+end

data/test/fixtures/comments.txt

@@ -0,0 +1,33 @@
+This file is used for generic comment parsing across CSS, SCSS, SASS & LESS.
+
+There's single-line comment styles:
+
+// This comment block has comment identifiers on every line.
+//
+// Fun fact: this is Kyle's favorite comment syntax!
+
+
+There's block comment styles:
+
+/* This comment block is a block-style comment syntax.
+
+There's only two identifier across multiple lines. */
+
+/* This is another common multi-line comment style.
+ *
+ * It has stars at the begining of every line.
+ */
+
+
+Some people do crazy things like mix comment styles:
+
+// This comment has a /* comment */ identifier inside of it!
+
+/* Look at my //cool// comment art! */
+
+
+Indented comments:
+
+    // Indented single-line comment.
+
+    /* Indented block comment. */

data/test/parser_test.rb

@@ -85,17 +85,6 @@ comment
       @css_parsed.section('2.1.1').description
   end
 
-  test "cleans css comments" do
-    assert_equal @cleaned_css_comment,
-      Kss::Parser.clean_comments(@css_comment)
-    assert_equal @cleaned_css_comment,
-      Kss::Parser.clean_comments(@starred_css_comment)
-    assert_equal @cleaned_css_comment,
-      Kss::Parser.clean_comments(@slashed_css_comment)
-    assert_equal @cleaned_css_comment,
-      Kss::Parser.clean_comments(@indented_css_comment)
-  end
-
   test "parses nested SCSS documents" do
     assert_equal "Your standard form element.", @scss_parsed.section('3.0.0').description
     assert_equal "Your standard text input box.", @scss_parsed.section('3.0.1').description
@@ -111,4 +100,8 @@ comment
     assert_equal "Your standard text input box.", @sass_parsed.section('3.0.1').description
   end
 
+  test "public sections returns hash of sections" do
+    assert_equal 2, @css_parsed.sections.count
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: kss
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: 
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Kyle Neath
@@ -15,39 +15,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-22 00:00:00 -08:00
+date: 2012-02-06 00:00:00 -08:00
 default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: sass
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 5
-        segments: 
-        - 3
-        - 1
-        version: "3.1"
-  type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: less
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 2
-        - 0
-        version: "2.0"
-  type: :runtime
-  version_requirements: *id002
+dependencies: []
+
 description: "  Inspired by TomDoc, KSS attempts to provide a methodology for writing\n  maintainable, documented CSS within a team. Specifically, KSS is a CSS\n  structure, documentation specification, and styleguide format.\n\n  This is a ruby library for parsing KSS documented CSS and generating\n  styleguides.\n"
 email: kneath@gmail.com
 executables: []
@@ -60,12 +31,15 @@ files:
 - README.md
 - Rakefile
 - LICENSE
+- lib/kss/comment_parser.rb
 - lib/kss/modifier.rb
 - lib/kss/parser.rb
 - lib/kss/section.rb
 - lib/kss/version.rb
 - lib/kss.coffee
 - lib/kss.rb
+- test/comment_parser_test.rb
+- test/fixtures/comments.txt
 - test/fixtures/css/buttons.css
 - test/fixtures/less/_label.less
 - test/fixtures/less/buttons.less