kss-alan 0.3.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Tom Preston-Werner, Kyle Neath
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+Software), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,78 @@
+# Knyle Style Sheets
+
+Inspired by [TomDoc](http://tomdoc.org), KSS attempts to provide a methodology for writing maintainable, documented CSS within a team. Specifically, KSS is a documentation specification and styleguide format. It is **not** a preprocessor, CSS framework, naming convention, or specificity guideline.
+
+* **[The Spec (What KSS is)](https://github.com/kneath/kss/blob/master/SPEC.md)**
+* **[Example living styleguide](https://github.com/kneath/kss/tree/master/example)**
+
+## 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.
+
+```css
+/*
+A button suitable for giving stars to someone.
+
+:hover             - Subtle hover highlight.
+.stars-given       - A highlight indicating you've already given a star.
+.stars-given:hover - Subtle hover highlight on top of stars-given styling.
+.disabled          - Dims the button to indicate it cannot be used.
+
+Styleguide 2.1.3.
+*/
+a.button.star{
+  ...
+}
+a.button.star.stars-given{
+  ...
+}
+a.button.star.disabled{
+  ...
+}
+```
+
+## Ruby Library
+
+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.
+
+```ruby
+styleguide = Kss::Parser.new("#{RACK_ROOT}public/stylesheets")
+
+styleguide.section('2.1.1')
+# => <Kss::Section>
+
+styleguide.section('2.1.1').description
+# => "A button suitable for giving stars to someone."
+
+styleguide.section('2.1.1').modifiers.first
+# => <Kss::Modifier>
+
+styleguide.section('2.1.1').modifiers.first.name
+# => ':hover'
+
+styleguide.section('2.1.1').modifiers.first.class_name
+# => 'pseudo-class-hover'
+
+styleguide.section('2.1.1').modifiers.first.description
+# => 'Subtle hover highlight'
+
+```
+
+The library is also fully TomDoc'd, completing the circle of life.
+
+## Generating styleguides
+
+The documenting syntax and ruby library are intended to generate styleguides automatically. To do this, you'll need to leverage a small javascript library that generates class styles for pseudo-class styles (`:hover`, `:disabled`, etc).
+
+* [kss.coffee](https://github.com/kneath/kss/blob/master/lib/kss.coffee)
+* [kss.js](https://github.com/kneath/kss/blob/master/example/public/javascripts/kss.js) (compiled js)
+
+For an example of how to generate a styleguide, check out the [`example`](https://github.com/kneath/kss/tree/master/example) sinatra application.
+
+## Development
+
+To hack on KSS, you'll need to install dependencies with `bundle install`. Run tests with `rake`.
+
+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.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rake/testtask'
+
+task :default => :test
+
+def command?(command)
+  system("type #{command} > /dev/null 2>&1")
+end
+
+#
+# Tests
+#
+
+if command? :turn
+  desc "Run tests"
+  task :test do
+    suffix = "-n #{ENV['TEST']}" if ENV['TEST']
+    sh "turn -Ilib:. test/*.rb #{suffix}"
+  end
+else
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.libs << '.'
+    t.pattern = 'test/**/*_test.rb'
+    t.verbose = false
+  end
+end
+
+#
+# Development
+#
+
+desc "Drop to irb."
+task :console do
+  exec "irb -I lib -rkss"
+end
+
+#
+# Gems
+#
+
+begin
+  require 'mg'
+  MG.new("kss.gemspec")
+rescue LoadError
+  warn "mg not available."
+  warn "Install it with: gem install mg"
+end
+
+desc "Push a new version to Gemcutter and publish docs."
+task :publish => "gem:publish" do
+  require File.dirname(__FILE__) + '/lib/kss/version'
+
+  sh "git tag v#{Kss::VERSION}"
+  sh "git push origin master --tags"
+  sh "git clean -fd"
+end

data/lib/kss.coffee

@@ -0,0 +1,39 @@
+# 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.
+#
+# Example:
+#
+#   a:hover{ color:blue; }
+#   => a.pseudo-class-hover{ color:blue; }
+class KssStateGenerator
+  constructor: ->
+    pseudos = /(\:hover|\:disabled|\:active|\:visited|\:focus)/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))
+
+  # Takes a given style and attaches it to the current page.
+  #
+  # rule - A CSS rule String (ex: ".test{ display:none; }").
+  #
+  # Returns nothing.
+  insertRule: (rule) ->
+    headEl = document.getElementsByTagName('head')[0]
+    styleEl = document.createElement('style')
+    styleEl.type = 'text/css'
+    if styleEl.styleSheet
+      styleEl.styleSheet.cssText = rule
+    else
+      styleEl.appendChild(document.createTextNode(rule))
+
+    headEl.appendChild(styleEl)
+
+new KssStateGenerator

data/lib/kss.rb

@@ -0,0 +1,8 @@
+require 'kss/comment_parser'
+require 'kss/modifier'
+require 'kss/parser'
+require 'kss/section'
+require 'kss/version'
+
+module Kss
+end

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/modifier.rb

@@ -0,0 +1,36 @@
+module Kss
+  # Public: Represents a style modifier. Usually a class name or a
+  # pseudo-class such as :hover. See the spec on The Modifiers Section for
+  # more information.
+  class Modifier
+
+    # Public: Returns the modifier name String.
+    attr_accessor :name
+
+    # Public: Returns the description String for a Modifier.
+    attr_accessor :description
+
+    # Public: Initialize a new Modifier.
+    #
+    # name        - The name String of the modifier.
+    # description - The description String of the modifier.
+    def initialize(name, description=nil)
+      @name = name.to_s
+      @description = description
+    end
+
+    # Public: The modifier name as a CSS class. For pseudo-classes, a
+    # generated class name is returned. Useful for generating styleguides.
+    #
+    # Examples
+    #
+    #   :hover => "pseudo-class-hover"
+    #   sexy-button => "sexy-button"
+    #
+    # Returns a CSS class String.
+    def class_name
+      name.gsub('.', ' ').gsub(':', ' pseudo-class-').strip
+    end
+
+  end
+end

data/lib/kss/parser.rb

@@ -0,0 +1,50 @@
+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.
+    #
+    # base_path - The path String where style files are located.
+    def initialize(base_path)
+      @sections = {}
+
+      Dir["#{base_path}/**/*.*"].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
+    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
+    # block and determines whether it is a KSS documentation block.
+    #
+    # Returns a boolean indicating whether the block conforms to KSS.
+    def self.kss_block?(cleaned_comment)
+      return false unless cleaned_comment.is_a? String
+
+      possible_reference = cleaned_comment.split("\n\n").last
+      possible_reference =~ /Styleguide \d/
+    end
+
+    # Public: Finds the Section for a given styleguide reference.
+    #
+    # Returns a Section for a reference, or a blank Section if none found.
+    def section(reference)
+      @sections[reference] || Section.new
+    end
+
+  end
+end

data/lib/kss/section.rb

@@ -0,0 +1,80 @@
+module Kss
+  # Public: Represents a styleguide section. Each section describes one UI
+  # element. A Section can be thought of as the collection of the description,
+  # modifiers, and styleguide reference.
+  class Section
+
+    # Returns the raw comment text for the section, not including comment
+    # syntax (such as // or /* */).
+    attr_reader :raw
+
+    # Public: Returns the filename where this section is found.
+    attr_reader :filename
+
+    # Public: Initialize a new Section
+    #
+    # comment_text - The raw comment String, minus any comment syntax.
+    # filename     - The filename as a String.
+    def initialize(comment_text=nil, filename=nil)
+      @raw = comment_text
+      @filename = filename
+    end
+
+    # Splits up the raw comment text into comment sections that represent
+    # description, modifiers, etc.
+    #
+    # Returns an Array of comment Strings.
+    def comment_sections
+      @comment_sections ||= raw ? raw.split("\n\n") : []
+    end
+
+    # Public: The styleguide section for which this comment block references.
+    #
+    # Returns the section reference String (ex: "2.1.8").
+    def section
+      return @section unless @section.nil?
+
+      comment_sections.each do |text|
+        if text =~ /Styleguide \d/i
+          cleaned = text.strip.sub(/\.$/, '') # Kill trailing period
+          @section = cleaned.match(/Styleguide (.+)/)[1]
+        end
+      end
+
+      @section
+    end
+
+    # Public: The description section of a styleguide comment block.
+    #
+    # Returns the description String.
+    def description
+      comment_sections.first
+    end
+
+    # Public: The modifiers section of a styleguide comment block.
+    #
+    # Returns an Array of Modifiers.
+    def modifiers
+      last_indent = nil
+      modifiers = []
+      return modifiers unless comment_sections[1]
+
+      comment_sections[1].split("\n").each do |line|
+        next if line.strip.empty?
+        indent = line.scan(/^\s*/)[0].to_s.size
+
+        if last_indent && indent > last_indent
+          modifiers.last.description += line.squeeze(" ")
+        else
+          modifier, desc = line.split(" - ")
+          modifiers << Modifier.new(modifier.strip, desc.strip) if modifier && desc
+        end
+
+        last_indent = indent
+      end
+
+      modifiers
+    end
+
+  end
+end

data/lib/kss/version.rb

@@ -0,0 +1,3 @@
+module Kss
+  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/fixtures/css/buttons.css

@@ -0,0 +1,38 @@
+/*
+Your standard form button.
+
+:hover    - Highlights when hovering.
+:disabled - Dims the button when disabled.
+.primary  - Indicates button is the primary action.
+.smaller  - A little bit smaller now.
+
+Styleguide 2.1.1.
+*/
+button {
+  padding: 5px 15px; }
+  button.primary, button.primary:hover {
+    color: #fff; }
+  button.smaller {
+    font-size: 11px; }
+  button:hover {
+    color: #337797; }
+  button:disabled {
+    opacity: 0.5; }
+
+
+/*
+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.
+*/
+a.button.star {
+  display: inline-block; }
+  a.button.star .star {
+    font-size: 10px; }
+  a.button.star.star-given {
+    color: #ae7e00; }
+  a.button.star.disabled {
+    opacity: 0.5; }

data/test/fixtures/less/_label.less

@@ -0,0 +1,10 @@
+/*
+A default form label
+
+Styleguide 5.0.0
+*/
+label {
+  display: block;
+  float: left;  
+  width: 150px;
+}

data/test/fixtures/less/buttons.less

@@ -0,0 +1,51 @@
+/*
+Your standard form button.
+
+:hover    - Highlights when hovering.
+:disabled - Dims the button when disabled.
+.primary  - Indicates button is the primary action.
+.smaller  - A little bit smaller now.
+ 
+Styleguide 2.1.1.
+*/
+button, .button {
+  padding:5px 15px;
+
+  &.primary, &.primary:hover{
+    color:#fff;
+  }
+
+  &.smaller{
+    font-size:9px;
+  }
+
+  &:hover{
+    color:#337797;
+  }
+
+  &:disabled{
+    opacity:0.5;
+  }
+}
+
+/*
+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.
+*/
+a.button.star{
+  display:inline-block;
+
+  .star{ font-size:10px; }
+
+  &.star-given{
+    color:#ae7e00;
+  }
+
+  &.disabled{
+    opacity:0.5;
+  }
+}

data/test/fixtures/less/mixins.less

@@ -0,0 +1,8 @@
+/*
+Your standard grid helper.
+
+Styleguide 4.0.0.
+*/
+.grid(@columns, @max: 10) {
+  width: (@columns / @max) * 960px;
+}

data/test/fixtures/less/nested.less

@@ -0,0 +1,17 @@
+@import "_label";
+/*
+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;
+  }
+}

data/test/fixtures/sass/buttons.sass

@@ -0,0 +1,40 @@
+/* Your standard form button.
+ *
+ * :hover    - Highlights when hovering.
+ * :disabled - Dims the button when disabled.
+ * .primary  - Indicates button is the primary action.
+ * .smaller  - A little bit smaller now.
+ *
+ * Styleguide 2.1.1. */
+button
+  padding: 5px 15px
+
+  &.primary, &.primary:hover
+    color: #fff
+
+  &.smaller
+    font-size: 11px
+
+  &:hover
+    color: #337797
+
+  &:disabled
+    opacity: 0.5
+
+// 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.
+a.button.star
+  display: inline-block
+
+  .star
+    font-size: 10px
+
+  &.star-given
+    color: #ae7e00
+
+  &.disabled
+    opacity: 0.5

data/test/fixtures/sass/nested.sass

@@ -0,0 +1,10 @@
+/* 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

data/test/fixtures/scss/buttons.scss

@@ -0,0 +1,47 @@
+// Your standard form button.
+//
+// :hover    - Highlights when hovering.
+// :disabled - Dims the button when disabled.
+// .primary  - Indicates button is the primary action.
+// .smaller  - A little bit smaller now.
+//
+// Styleguide 2.1.1.
+button{
+  padding:5px 15px;
+
+  &.primary, &.primary:hover{
+    color:#fff;
+  }
+
+  &.smaller{
+    font-size:11px;
+  }
+
+  &:hover{
+    color:#337797;
+  }
+
+  &:disabled{
+    opacity:0.5;
+  }
+}
+
+// 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.
+a.button.star{
+  display:inline-block;
+
+  .star{ font-size:10px; }
+
+  &.star-given{
+    color:#ae7e00;
+  }
+
+  &.disabled{
+    opacity:0.5;
+  }
+}

data/test/fixtures/scss/nested.scss

@@ -0,0 +1,12 @@
+// 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;
+  }
+}

data/test/helper.rb

@@ -0,0 +1,19 @@
+require 'test/unit'
+
+require 'kss'
+
+module Kss
+  class Test < ::Test::Unit::TestCase
+    def self.test(name, &block)
+      define_method("test_#{name.gsub(/\W/,'_')}", &block) if block
+    end
+
+    def default_test
+    end
+
+    def fixture(name)
+      @fixtures ||= {}
+      @fixtures[name] ||= File.read("test/fixtures/#{name}")
+    end
+  end
+end

data/test/parser_test.rb

@@ -0,0 +1,107 @@
+require 'test/helper'
+
+class ParserTest < Kss::Test
+
+  def setup
+    @scss_parsed = Kss::Parser.new('test/fixtures/scss')
+    @sass_parsed = Kss::Parser.new('test/fixtures/sass')
+    @css_parsed = Kss::Parser.new('test/fixtures/css')
+    @less_parsed = Kss::Parser.new('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
+    assert_equal 'Your standard form button.',
+      @scss_parsed.section('2.1.1').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 multi-line comments in SASS (/* ... */)" do
+    assert_equal 'Your standard form button.',
+      @sass_parsed.section('2.1.1').description
+  end
+
+  test "parses KSS single-line comments in SASS (// ... )" do
+    assert_equal 'A button suitable for giving stars to someone.',
+      @sass_parsed.section('2.2.1').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 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
+  end
+
+  test "parses nested LESS documents" do
+    assert_equal "Your standard form element.", @less_parsed.section('3.0.0').description
+    assert_equal "Your standard text input box.", @less_parsed.section('3.0.1').description
+  end
+
+  test "parses nested SASS documents" do
+    assert_equal "Your standard form element.", @sass_parsed.section('3.0.0').description
+    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

data/test/section_test.rb

@@ -0,0 +1,40 @@
+require 'test/helper'
+
+class SectionTest < Kss::Test
+
+  def setup
+    @comment_text = <<comment
+Your standard form button.
+
+:hover    - Highlights when hovering.
+:disabled - Dims the button when disabled.
+.primary  - Indicates button is the primary action.
+.smaller  - A smaller button
+
+Styleguide 2.1.1.
+comment
+
+    @section = Kss::Section.new(@comment_text, 'example.css')
+  end
+
+  test "parses the description" do
+    assert_equal "Your standard form button.", @section.description
+  end
+
+  test "parses the modifiers" do
+    assert_equal 4, @section.modifiers.size
+  end
+
+  test "parses a modifier's names" do
+    assert_equal ':hover', @section.modifiers.first.name
+  end
+
+  test "parses a modifier's description" do
+    assert_equal 'Highlights when hovering.', @section.modifiers.first.description
+  end
+
+  test "parses the styleguide reference" do
+    assert_equal '2.1.1', @section.section
+  end
+
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: kss-alan
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
+platform: ruby
+authors:
+- Alan Hogan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-10 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"
+email: gem@alanhogan.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+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
+- test/fixtures/less/mixins.less
+- test/fixtures/less/nested.less
+- test/fixtures/sass/buttons.sass
+- test/fixtures/sass/nested.sass
+- test/fixtures/scss/buttons.scss
+- test/fixtures/scss/nested.scss
+- test/helper.rb
+- test/parser_test.rb
+- test/section_test.rb
+homepage: http://github.com/kneath/kss
+licenses: []
+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.24
+signing_key: 
+specification_version: 3
+summary: A library for parsing KSS documented stylesheets and generating styleguides
+  (originally by Kyle Neath)
+test_files: []