kss 0.4.0 → 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1e5a7828fb96863926b68b29f71602747e9b3dec
+  data.tar.gz: 0a5e39cafe9a7d94171be7101c60059ab7570838
+SHA512:
+  metadata.gz: ebe249b7652df9e6b50d26a958b1a9195ed3d83936d19a67808a549a80c4885042cbd242e37bf330cdc0ac6cad049de266b04c7b66bb3bc784bed08582182250
+  data.tar.gz: efc8616414baafa51a686f45bce4e2544fe4d5b1d3b292620f54e431f22eb8382ad2d0b5aa76bb123fe69fa4b51ff2520e76dc87fbfd8039644b8dd4d9e077e9

data/README.md

@@ -7,7 +7,7 @@ Inspired by [TomDoc](http://tomdoc.org), KSS attempts to provide a methodology f
 
 ## KSS in a nutshell
 
-The methodology and ideas behind Knyle Style Sheets are contained in [SPEC.md](https://github.com/kneath/kss/blob/master/SPEC.md). At it's core, KSS is a documenting syntax for CSS.
+The methodology and ideas behind Knyle Style Sheets are contained in [SPEC.md](https://github.com/kneath/kss/blob/master/SPEC.md). At its core, KSS is a documenting syntax for CSS.
 
 ```css
 /*
@@ -31,7 +31,14 @@ a.button.star.disabled{
 }
 ```
 
-## Ruby Library
+KSS can also support words as Styleguide section names
+```scss
+// Styleguide Forms.Checkboxes.
+// - or -
+// Styleguide Forms - Special Checkboxes.
+```
+
+## Ruby Library [![Build Status](https://travis-ci.org/kneath/kss.png)](https://travis-ci.org/kneath/kss) [![Code Climate](https://codeclimate.com/github/kneath/kss.png)](https://codeclimate.com/github/kneath/kss)
 
 This repository includes a ruby library suitable for parsing SASS, SCSS, and CSS documented with KSS guidelines. To use the library, include it in your project as a gem from <https://rubygems.org/gems/kss>. Then, create a parser and explore your KSS.
 
@@ -55,7 +62,38 @@ styleguide.section('2.1.1').modifiers.first.class_name
 
 styleguide.section('2.1.1').modifiers.first.description
 # => 'Subtle hover highlight'
+```
 
+You can also initialize the `Kss::Parser` with a string CSS by using `Kss::Parser.new(string)`
+
+```ruby
+buttons =<<-'EOS'
+  /*
+  Your standard form button.
+
+  :hover    - Highlights when hovering.
+  :disabled - Dims the button when disabled.
+
+  Styleguide 1.1
+  */
+  button {
+    padding: 5px 15px;
+    line-height: normal;
+    /* ... */
+  }
+  button:disabled {
+    opacity: 0.5;
+  }
+EOS
+styleguide = Kss::Parser.new(buttons)
+
+styleguide.section('1.1')
+# => <Kss::Section>
+
+styleguide.section('1.1.1').description
+# => "Your standard form button."
+
+# ...
 ```
 
 The library is also fully TomDoc'd, completing the circle of life.
@@ -76,3 +114,8 @@ To hack on KSS, you'll need to install dependencies with `bundle install`. Run t
 To make your life easier, I suggest `bundle install --binstubs` and adding `bin/` to your `$PATH`. If you don't understand this, just blindly add `bundle exec` in front of everything you'd normally do, like `bundle exec rake`.
 
 I apologize on behalf of the Ruby community for this, it's embarrassing and disappointing that dependency management is still so clumsy.
+
+## Implementations
+
+The KSS specification has also been implemented in [Python](https://github.com/seanbrant/pykss), [Node.js](https://github.com/hughsk/kss-node) and [PHP](https://github.com/scaninc/kss-php)
+

data/lib/kss.coffee

@@ -1,24 +1,41 @@
 # This class scans your stylesheets for pseudo classes, then inserts a new CSS
 # rule with the same properties, but named 'psuedo-class-{{name}}'.
 #
-# Supported pseudo classes: hover, disabled, active, visited, focus.
+# Supported pseudo classes: hover, disabled, active, visited, focus, target.
 #
 # Example:
 #
 #   a:hover{ color:blue; }
 #   => a.pseudo-class-hover{ color:blue; }
 class KssStateGenerator
+  psuedo_selectors = [
+    'hover',
+    'enabled',
+    'disabled',
+    'active',
+    'visited',
+    'focus',
+    'target',
+    'checked',
+    'empty',
+    'first-of-type',
+    'last-of-type',
+    'first-child',
+    'last-child']
+
   constructor: ->
-    pseudos = /(\:hover|\:disabled|\:active|\:visited|\:focus)/g
+    pseudos = new RegExp "(\\:#{psuedo_selectors.join('|\\:')})", "g"
 
     try
       for stylesheet in document.styleSheets
-        idxs = []
-        for rule, idx in stylesheet.cssRules
-          while (rule.type == CSSRule.STYLE_RULE) && pseudos.test(rule.selectorText)
-            replaceRule = (matched, stuff) ->
-              return matched.replace(/\:/g, '.pseudo-class-')
-            @insertRule(rule.cssText.replace(pseudos, replaceRule))
+        if stylesheet.href.indexOf(document.domain) >= 0
+          idxs = []
+          for rule, idx in stylesheet.cssRules
+            if (rule.type == CSSRule.STYLE_RULE) && pseudos.test(rule.selectorText)
+              replaceRule = (matched, stuff) ->
+                return matched.replace(/\:/g, '.pseudo-class-')
+              @insertRule(rule.cssText.replace(pseudos, replaceRule))
+            pseudos.lastIndex = 0
 
   # Takes a given style and attaches it to the current page.
   #

data/lib/kss/comment_parser.rb

@@ -58,15 +58,19 @@ module Kss
     # 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.
+    # file_path_or_string_input - The location of the file to parse as a String, or the String itself.
+    # options                   - Optional options hash.
     #   :preserve_whitespace - Preserve the whitespace before/after comment
     #                          markers (default:false).
     #
-    def initialize(file_path, options={})
+    def initialize(file_path_or_string_input, options={})
       @options = options
       @options[:preserve_whitespace] = false if @options[:preserve_whitespace].nil?
-      @file_path = file_path
+      if File.exists?(file_path_or_string_input)
+        @file_path = file_path_or_string_input
+      else
+        @string_input = file_path_or_string_input
+      end
       @blocks = []
       @parsed = false
     end
@@ -80,52 +84,60 @@ module Kss
       @parsed ? @blocks : parse_blocks
     end
 
-
-    # Parse the file for comment blocks and populate them into @blocks.
+    # Parse the file or string for comment blocks and populate them into @blocks.
     #
-    # Returns an Array  of parsed comment Strings.
+    # 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
+      if !@file_path.nil?
+        # the input is an existing file
+        File.open @file_path do |file|
+          parse_blocks_input(file)
+        end
+      else
+        # @file_path is nil, we then expect the input to be a String
+        parse_blocks_input(@string_input)
+      end
+    end
+
+    def parse_blocks_input(input)
+      current_block = nil
+      inside_single_line_block = false
+      inside_multi_line_block  = false
+
+      input.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
+        # 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)
+        # 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?
+        # 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
+          inside_single_line_block = false
+          current_block = nil
         end
       end
-
       @parsed = true
       @blocks
     end
@@ -161,4 +173,4 @@ module Kss
     end
 
   end
-end
+end

data/lib/kss/parser.rb

@@ -2,29 +2,41 @@ module Kss
   # Public: The main KSS parser. Takes a directory full of SASS / SCSS / CSS
   # files and parses the KSS within them.
   class Parser
-    
+    STYLEGUIDE_PATTERN = (/(?<!No )Styleguide [[:alnum:]]/i).freeze
+
     # 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.
+
+    # Public: Initializes a new parser based on a directory of files or kss strings.
+    # Scans within the directory recursively or the strings for any comment blocks
+    # that look like KSS.
     #
-    # paths - Each path String where style files are located.
-    def initialize(*paths)
+    # paths_or_strings - Each path String where style files are located, or each String containing KSS.
+    def initialize(*paths_or_strings)
       @sections = {}
 
-      paths.each do |path|
-        Dir["#{path}/**/*.*"].each do |filename|
-          parser = CommentParser.new(filename)
+      paths_or_strings.each do |path_or_string|
+        if Dir.exists?(path_or_string)
+          # argument is a path
+          path = path_or_string
+          Dir["#{path}/**/*.{css,less,sass,scss}"].each do |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
+        else
+          # argument is a KSS string
+          kss_string = path_or_string
+          parser = CommentParser.new(kss_string)
           parser.blocks.each do |comment_block|
-            add_section comment_block, filename if self.class.kss_block?(comment_block)
+            add_section comment_block if self.class.kss_block?(comment_block)
           end
         end
       end
     end
 
-    def add_section comment_text, filename
+    def add_section comment_text, filename = ''
       base_name = File.basename(filename)
       section = Section.new(comment_text, base_name)
       @sections[section.section] = section
@@ -38,7 +50,7 @@ module Kss
       return false unless cleaned_comment.is_a? String
 
       possible_reference = cleaned_comment.split("\n\n").last
-      possible_reference =~ /Styleguide \d/
+      possible_reference =~ STYLEGUIDE_PATTERN
     end
 
     # Public: Finds the Section for a given styleguide reference.

data/lib/kss/section.rb

@@ -35,7 +35,7 @@ module Kss
       return @section unless @section.nil?
 
       cleaned  = section_comment.strip.sub(/\.$/, '') # Kill trailing period
-      @section = cleaned.match(/Styleguide (.+)/)[1]
+      @section = cleaned.match(/Styleguide (.+)/i)[1]
 
       @section
     end
@@ -77,13 +77,13 @@ module Kss
     end
 
   private
-  
+
     def section_comment
       comment_sections.find do |text|
-        text =~ /Styleguide \d/i
+        text =~ Parser::STYLEGUIDE_PATTERN
       end.to_s
     end
-  
+
     def modifiers_comment
       comment_sections[1..-1].reject do |section|
         section == section_comment

data/lib/kss/version.rb

@@ -1,3 +1,3 @@
 module Kss
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/test/fixtures/css/buttons.css

@@ -36,3 +36,34 @@ a.button.star {
     color: #ae7e00; }
   a.button.star.disabled {
     opacity: 0.5; }
+
+/*
+A big button
+
+.really-big - Even bigger button
+
+Styleguide Buttons.Big.
+*/
+a.button.big {
+  display: inline-block;
+  font-size: 10em; }
+  a.button.big.really-big {
+    font-size: 20em; }
+
+/*
+A button truly lime in color
+
+Styleguide Buttons - Truly Lime
+*/
+a.button.lime {
+  color: lime;
+}
+
+/*
+A button truly lime in color
+
+Seen in styleguide 10.2
+*/
+a.button.tricksy {
+  background: sparkles;
+}

data/test/fixtures/less/buttons.less

@@ -48,4 +48,20 @@ a.button.star{
   &.disabled{
     opacity:0.5;
   }
-}
+}
+
+/*
+A big button
+
+.really-big - Even bigger button
+
+Styleguide Buttons.Big.
+*/
+a.button.big {
+  display: inline-block;
+  font-size: 10em;
+
+  .really-big {
+    font-size: 20em;
+  }
+}

data/test/fixtures/sass/buttons.sass

@@ -38,3 +38,15 @@ a.button.star
 
   &.disabled
     opacity: 0.5
+
+// A big button
+//
+// .really-big - A really big button
+//
+// Styleguide Buttons.Big.
+a.button.big
+  display: inline-block;
+  font-size: 10em;
+
+  &.really-big
+    font-size: 20em;

data/test/fixtures/scss/buttons.scss

@@ -44,4 +44,18 @@ a.button.star{
   &.disabled{
     opacity:0.5;
   }
-}
+}
+
+// A big button
+//
+// .really-big - Even bigger button
+//
+// Styleguide Buttons.Big.
+a.button.big {
+  display: inline-block;
+  font-size: 10em;
+
+  &.really-big {
+    font-size: 20em;
+  }
+}

data/test/helper.rb

@@ -1,9 +1,8 @@
-require 'test/unit'
-
+require 'minitest/autorun'
 require 'kss'
 
 module Kss
-  class Test < ::Test::Unit::TestCase
+  class Test < ::Minitest::Test
     def self.test(name, &block)
       define_method("test_#{name.gsub(/\W/,'_')}", &block) if block
     end

data/test/parser_test.rb

@@ -8,57 +8,6 @@ class ParserTest < Kss::Test
     @css_parsed = Kss::Parser.new('test/fixtures/css')
     @less_parsed = Kss::Parser.new('test/fixtures/less')
     @multiple_parsed = Kss::Parser.new('test/fixtures/scss', 'test/fixtures/less')
-
-    @css_comment = <<comment
-/*
-A button suitable for giving stars to someone.
-
-.star-given - A highlight indicating you've already given a star.
-.disabled   - Dims the button to indicate it cannot be used.
-
-Styleguide 2.2.1.
-*/
-comment
-
-  @starred_css_comment = <<comment
-/* A button suitable for giving stars to someone.
- *
- * .star-given - A highlight indicating you've already given a star.
- * .disabled   - Dims the button to indicate it cannot be used.
- *
- * Styleguide 2.2.1. */
-comment
-
-  @slashed_css_comment = <<comment
-// A button suitable for giving stars to someone.
-//
-// .star-given - A highlight indicating you've already given a star.
-// .disabled   - Dims the button to indicate it cannot be used.
-//
-// Styleguide 2.2.1.
-comment
-
-  @indented_css_comment = <<comment
-  /*
-  A button suitable for giving stars to someone.
-
-  .star-given - A highlight indicating you've already given a star.
-  .disabled   - Dims the button to indicate it cannot be used.
-
-  Styleguide 2.2.1.
-  */
-comment
-
-  @cleaned_css_comment = <<comment
-A button suitable for giving stars to someone.
-
-.star-given - A highlight indicating you've already given a star.
-.disabled   - Dims the button to indicate it cannot be used.
-
-Styleguide 2.2.1.
-comment
-  @cleaned_css_comment.rstrip!
-
   end
 
   test "parses KSS comments in SCSS" do
@@ -66,11 +15,21 @@ comment
       @scss_parsed.section('2.1.1').description
   end
 
+  test "parses KSS keys that are words in SCSS" do
+    assert_equal 'A big button',
+      @scss_parsed.section('Buttons.Big').description
+  end
+
   test "parsers KSS comments in LESS" do
     assert_equal 'Your standard form button.',
       @less_parsed.section('2.1.1').description
   end
 
+  test "parses KSS keys that are words in LESS" do
+    assert_equal 'A big button',
+      @less_parsed.section('Buttons.Big').description
+  end
+
   test "parses KSS multi-line comments in SASS (/* ... */)" do
     assert_equal 'Your standard form button.',
       @sass_parsed.section('2.1.1').description
@@ -81,11 +40,26 @@ comment
       @sass_parsed.section('2.2.1').description
   end
 
+  test "parses KSS keys that are words in in SASS" do
+    assert_equal 'A big button',
+      @sass_parsed.section('Buttons.Big').description
+  end
+
   test "parses KSS comments in CSS" do
     assert_equal 'Your standard form button.',
       @css_parsed.section('2.1.1').description
   end
 
+  test "parses KSS keys that are words in CSS" do
+    assert_equal 'A big button',
+      @css_parsed.section('Buttons.Big').description
+  end
+
+  test "parses KSS keys that word phases in CSS" do
+    assert_equal 'A button truly lime in color',
+      @css_parsed.section('Buttons - Truly Lime').description
+  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
@@ -102,11 +76,42 @@ comment
   end
 
   test "public sections returns hash of sections" do
-    assert_equal 2, @css_parsed.sections.count
+    assert_equal 5, @css_parsed.sections.count
   end
 
   test "parse multiple paths" do
-    assert_equal 6, @multiple_parsed.sections.count
+    assert_equal 7, @multiple_parsed.sections.count
+  end
+
+  test "parse from string" do
+    scss_input =<<-'EOS'
+    // Your standard form element.
+    //
+    // Styleguide 3.0.0
+    form {
+
+      // Your standard text input box.
+      //
+      // Styleguide 3.0.1
+      input[type="text"] {
+        border: 1px solid #ccc;
+      }
+    }
+    EOS
+    assert_equal "Your standard form element.", Kss::Parser.new(scss_input).section('3.0.0').description
+    assert_equal "Your standard text input box.", @sass_parsed.section('3.0.1').description
   end
 
+  test "parse with no styleguide reference comment" do
+    scss_input =<<-'EOS'
+      // Nothing here
+      //
+      // No styleguide reference.
+      input[type="text"] {
+        border: 1px solid #ccc;
+      }
+    EOS
+
+    assert Kss::Parser.new(scss_input)
+  end
 end

data/test/section_test.rb

@@ -39,4 +39,10 @@ comment
     assert_equal '2.1.1', @section.section
   end
 
+  test "parses word phrases as styleguide references" do
+    @comment_text.gsub!('2.1.1', 'Buttons - Truly Lime')
+    section = Kss::Section.new(@comment_text, 'example.css')
+    assert_equal 'Buttons - Truly Lime', @section.section
+  end
+
 end

metadata

@@ -1,20 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: kss
 version: !ruby/object:Gem::Version
-  version: 0.4.0
-  prerelease: 
+  version: 0.5.0
 platform: ruby
 authors:
 - Kyle Neath
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-02 00:00:00.000000000 Z
+date: 2013-09-22 00:00:00.000000000 Z
 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"
+description: |2
+    Inspired by TomDoc, KSS attempts to provide a methodology for writing
+    maintainable, documented CSS within a team. Specifically, KSS is a CSS
+    structure, documentation specification, and styleguide format.
+
+    This is a ruby library for parsing KSS documented CSS and generating
+    styleguides.
 email: kneath@gmail.com
 executables: []
 extensions: []
@@ -33,6 +35,7 @@ files:
 - test/comment_parser_test.rb
 - test/fixtures/comments.txt
 - test/fixtures/css/buttons.css
+- test/fixtures/css/images/example.png
 - test/fixtures/less/_label.less
 - test/fixtures/less/buttons.less
 - test/fixtures/less/mixins.less
@@ -45,27 +48,28 @@ files:
 - test/parser_test.rb
 - test/section_test.rb
 homepage: http://github.com/kneath/kss
-licenses: []
+licenses:
+- MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 2.0.0
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: A library for parsing KSS documented stylesheets and generating styleguides
 test_files: []
+has_rdoc: false