kss 0.1.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,23 @@
+# Knyle Style Sheets
+
+This is a ruby library for parsing KSS documented stylesheets and generating styleguides.
+
+Inspired by [TomDoc](http://tomdoc.org), 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. It is **not** a preprocessor, CSS framework, naming convention, or specificity guideline.
+
+## Spec
+
+If you would like to learn more about the methodology and ideas behind Knyle Style Sheets, you should read SPEC.md. It contains the documenting syntax and styleguide guidelines.
+
+## Ruby Library
+
+This repository includes a ruby library suitable for parsing SASS, SCSS, and CSS documented with KSS guidelines.
+
+The library is also fully TomDoc'd, completing the circle of life.
+
+## 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.rb

@@ -0,0 +1,9 @@
+require 'sass'
+
+require 'kss/modifier'
+require 'kss/parser'
+require 'kss/section'
+require 'kss/version'
+
+module Kss
+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.sub('.', ' ').sub(':', ' pseudo-class-').strip
+    end
+
+  end
+end

data/lib/kss/parser.rb

@@ -0,0 +1,68 @@
+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: 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|
+        root_node = Sass::SCSS::Parser.new(File.read(filename), filename).parse
+        root_node.children.each do |node|
+          next unless node.is_a? Sass::Tree::CommentNode
+          comment_text = self.class.clean_comments node.value[0]
+
+          if self.class.kss_block? comment_text
+            base_name = File.basename(filename)
+            section = Section.new(comment_text, base_name)
+            @sections[section.section] = section
+          end
+        end
+      end
+    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/i
+    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 comment syntax
+      text.gsub!(/(\/\* )?( \*\/)?/, '') # [/* + space] or [space + */]
+      text.gsub!(/\n\s\* ?/, "\n") # * in front of every line
+
+      # Manual generated comment syntax
+      text.gsub!(/^\/\*/, '') # starting block
+      text.gsub!(/\*\/$/, '') # ending block
+
+      text.strip!
+      text
+    end
+
+    # 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.1.0"
+end

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/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/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,58 @@
+require 'test/helper'
+
+class ParserTest < Kss::Test
+
+  def setup
+    @scss_parsed = Kss::Parser.new('test/fixtures/scss')
+    @css_parsed = Kss::Parser.new('test/fixtures/css')
+
+    @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
+
+  @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 "parses KSS comments in CSS" do
+    assert_equal 'Your standard form button.',
+      @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)
+  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,94 @@
+--- !ruby/object:Gem::Specification 
+name: kss
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Kyle Neath
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-02 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: 21
+        segments: 
+        - 3
+        - 1
+        - 11
+        version: 3.1.11
+  type: :runtime
+  version_requirements: *id001
+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: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- Rakefile
+- LICENSE
+- lib/kss/modifier.rb
+- lib/kss/parser.rb
+- lib/kss/section.rb
+- lib/kss/version.rb
+- lib/kss.rb
+- test/fixtures/css/buttons.css
+- test/fixtures/scss/buttons.scss
+- test/helper.rb
+- test/parser_test.rb
+- test/section_test.rb
+has_rdoc: true
+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 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A library for parsing KSS documented stylesheets and generating styleguides
+test_files: []
+