kss-alan 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- data/LICENSE +20 -0
- data/README.md +78 -0
- data/Rakefile +56 -0
- data/lib/kss.coffee +39 -0
- data/lib/kss.rb +8 -0
- data/lib/kss/comment_parser.rb +164 -0
- data/lib/kss/modifier.rb +36 -0
- data/lib/kss/parser.rb +50 -0
- data/lib/kss/section.rb +80 -0
- data/lib/kss/version.rb +3 -0
- data/test/comment_parser_test.rb +73 -0
- data/test/fixtures/comments.txt +33 -0
- data/test/fixtures/css/buttons.css +38 -0
- data/test/fixtures/less/_label.less +10 -0
- data/test/fixtures/less/buttons.less +51 -0
- data/test/fixtures/less/mixins.less +8 -0
- data/test/fixtures/less/nested.less +17 -0
- data/test/fixtures/sass/buttons.sass +40 -0
- data/test/fixtures/sass/nested.sass +10 -0
- data/test/fixtures/scss/buttons.scss +47 -0
- data/test/fixtures/scss/nested.scss +12 -0
- data/test/helper.rb +19 -0
- data/test/parser_test.rb +107 -0
- data/test/section_test.rb +40 -0
- metadata +72 -0
data/LICENSE
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2011 Tom Preston-Werner, Kyle Neath
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
Software), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,78 @@
|
|
1
|
+
# Knyle Style Sheets
|
2
|
+
|
3
|
+
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.
|
4
|
+
|
5
|
+
* **[The Spec (What KSS is)](https://github.com/kneath/kss/blob/master/SPEC.md)**
|
6
|
+
* **[Example living styleguide](https://github.com/kneath/kss/tree/master/example)**
|
7
|
+
|
8
|
+
## KSS in a nutshell
|
9
|
+
|
10
|
+
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.
|
11
|
+
|
12
|
+
```css
|
13
|
+
/*
|
14
|
+
A button suitable for giving stars to someone.
|
15
|
+
|
16
|
+
:hover - Subtle hover highlight.
|
17
|
+
.stars-given - A highlight indicating you've already given a star.
|
18
|
+
.stars-given:hover - Subtle hover highlight on top of stars-given styling.
|
19
|
+
.disabled - Dims the button to indicate it cannot be used.
|
20
|
+
|
21
|
+
Styleguide 2.1.3.
|
22
|
+
*/
|
23
|
+
a.button.star{
|
24
|
+
...
|
25
|
+
}
|
26
|
+
a.button.star.stars-given{
|
27
|
+
...
|
28
|
+
}
|
29
|
+
a.button.star.disabled{
|
30
|
+
...
|
31
|
+
}
|
32
|
+
```
|
33
|
+
|
34
|
+
## Ruby Library
|
35
|
+
|
36
|
+
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.
|
37
|
+
|
38
|
+
```ruby
|
39
|
+
styleguide = Kss::Parser.new("#{RACK_ROOT}public/stylesheets")
|
40
|
+
|
41
|
+
styleguide.section('2.1.1')
|
42
|
+
# => <Kss::Section>
|
43
|
+
|
44
|
+
styleguide.section('2.1.1').description
|
45
|
+
# => "A button suitable for giving stars to someone."
|
46
|
+
|
47
|
+
styleguide.section('2.1.1').modifiers.first
|
48
|
+
# => <Kss::Modifier>
|
49
|
+
|
50
|
+
styleguide.section('2.1.1').modifiers.first.name
|
51
|
+
# => ':hover'
|
52
|
+
|
53
|
+
styleguide.section('2.1.1').modifiers.first.class_name
|
54
|
+
# => 'pseudo-class-hover'
|
55
|
+
|
56
|
+
styleguide.section('2.1.1').modifiers.first.description
|
57
|
+
# => 'Subtle hover highlight'
|
58
|
+
|
59
|
+
```
|
60
|
+
|
61
|
+
The library is also fully TomDoc'd, completing the circle of life.
|
62
|
+
|
63
|
+
## Generating styleguides
|
64
|
+
|
65
|
+
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).
|
66
|
+
|
67
|
+
* [kss.coffee](https://github.com/kneath/kss/blob/master/lib/kss.coffee)
|
68
|
+
* [kss.js](https://github.com/kneath/kss/blob/master/example/public/javascripts/kss.js) (compiled js)
|
69
|
+
|
70
|
+
For an example of how to generate a styleguide, check out the [`example`](https://github.com/kneath/kss/tree/master/example) sinatra application.
|
71
|
+
|
72
|
+
## Development
|
73
|
+
|
74
|
+
To hack on KSS, you'll need to install dependencies with `bundle install`. Run tests with `rake`.
|
75
|
+
|
76
|
+
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`.
|
77
|
+
|
78
|
+
I apologize on behalf of the Ruby community for this, it's embarrassing and disappointing that dependency management is still so clumsy.
|
data/Rakefile
ADDED
@@ -0,0 +1,56 @@
|
|
1
|
+
require 'rake/testtask'
|
2
|
+
|
3
|
+
task :default => :test
|
4
|
+
|
5
|
+
def command?(command)
|
6
|
+
system("type #{command} > /dev/null 2>&1")
|
7
|
+
end
|
8
|
+
|
9
|
+
#
|
10
|
+
# Tests
|
11
|
+
#
|
12
|
+
|
13
|
+
if command? :turn
|
14
|
+
desc "Run tests"
|
15
|
+
task :test do
|
16
|
+
suffix = "-n #{ENV['TEST']}" if ENV['TEST']
|
17
|
+
sh "turn -Ilib:. test/*.rb #{suffix}"
|
18
|
+
end
|
19
|
+
else
|
20
|
+
Rake::TestTask.new do |t|
|
21
|
+
t.libs << 'lib'
|
22
|
+
t.libs << '.'
|
23
|
+
t.pattern = 'test/**/*_test.rb'
|
24
|
+
t.verbose = false
|
25
|
+
end
|
26
|
+
end
|
27
|
+
|
28
|
+
#
|
29
|
+
# Development
|
30
|
+
#
|
31
|
+
|
32
|
+
desc "Drop to irb."
|
33
|
+
task :console do
|
34
|
+
exec "irb -I lib -rkss"
|
35
|
+
end
|
36
|
+
|
37
|
+
#
|
38
|
+
# Gems
|
39
|
+
#
|
40
|
+
|
41
|
+
begin
|
42
|
+
require 'mg'
|
43
|
+
MG.new("kss.gemspec")
|
44
|
+
rescue LoadError
|
45
|
+
warn "mg not available."
|
46
|
+
warn "Install it with: gem install mg"
|
47
|
+
end
|
48
|
+
|
49
|
+
desc "Push a new version to Gemcutter and publish docs."
|
50
|
+
task :publish => "gem:publish" do
|
51
|
+
require File.dirname(__FILE__) + '/lib/kss/version'
|
52
|
+
|
53
|
+
sh "git tag v#{Kss::VERSION}"
|
54
|
+
sh "git push origin master --tags"
|
55
|
+
sh "git clean -fd"
|
56
|
+
end
|
data/lib/kss.coffee
ADDED
@@ -0,0 +1,39 @@
|
|
1
|
+
# This class scans your stylesheets for pseudo classes, then inserts a new CSS
|
2
|
+
# rule with the same properties, but named 'psuedo-class-{{name}}'.
|
3
|
+
#
|
4
|
+
# Supported pseudo classes: hover, disabled, active, visited, focus.
|
5
|
+
#
|
6
|
+
# Example:
|
7
|
+
#
|
8
|
+
# a:hover{ color:blue; }
|
9
|
+
# => a.pseudo-class-hover{ color:blue; }
|
10
|
+
class KssStateGenerator
|
11
|
+
constructor: ->
|
12
|
+
pseudos = /(\:hover|\:disabled|\:active|\:visited|\:focus)/g
|
13
|
+
|
14
|
+
try
|
15
|
+
for stylesheet in document.styleSheets
|
16
|
+
idxs = []
|
17
|
+
for rule, idx in stylesheet.cssRules
|
18
|
+
while (rule.type == CSSRule.STYLE_RULE) && pseudos.test(rule.selectorText)
|
19
|
+
replaceRule = (matched, stuff) ->
|
20
|
+
return matched.replace(/\:/g, '.pseudo-class-')
|
21
|
+
@insertRule(rule.cssText.replace(pseudos, replaceRule))
|
22
|
+
|
23
|
+
# Takes a given style and attaches it to the current page.
|
24
|
+
#
|
25
|
+
# rule - A CSS rule String (ex: ".test{ display:none; }").
|
26
|
+
#
|
27
|
+
# Returns nothing.
|
28
|
+
insertRule: (rule) ->
|
29
|
+
headEl = document.getElementsByTagName('head')[0]
|
30
|
+
styleEl = document.createElement('style')
|
31
|
+
styleEl.type = 'text/css'
|
32
|
+
if styleEl.styleSheet
|
33
|
+
styleEl.styleSheet.cssText = rule
|
34
|
+
else
|
35
|
+
styleEl.appendChild(document.createTextNode(rule))
|
36
|
+
|
37
|
+
headEl.appendChild(styleEl)
|
38
|
+
|
39
|
+
new KssStateGenerator
|
data/lib/kss.rb
ADDED
@@ -0,0 +1,164 @@
|
|
1
|
+
module Kss
|
2
|
+
# Public: Takes a file path of a text file and extracts comments from it.
|
3
|
+
# Currently accepts two formats:
|
4
|
+
#
|
5
|
+
# // Single line style.
|
6
|
+
# /* Multi-line style. */
|
7
|
+
class CommentParser
|
8
|
+
|
9
|
+
# Public: Is this a single-line comment? // This style
|
10
|
+
#
|
11
|
+
# line - A String of one line of text.
|
12
|
+
#
|
13
|
+
# Returns a boolean.
|
14
|
+
def self.single_line_comment?(line)
|
15
|
+
!!(line =~ /^\s*\/\//)
|
16
|
+
end
|
17
|
+
|
18
|
+
# Public: Is this the start of a multi-line comment? /* This style */
|
19
|
+
#
|
20
|
+
# line - A String of one line of text.
|
21
|
+
#
|
22
|
+
# Returns a boolean.
|
23
|
+
def self.start_multi_line_comment?(line)
|
24
|
+
!!(line =~ /^\s*\/\*/)
|
25
|
+
end
|
26
|
+
|
27
|
+
# Public: Is this the end of a multi-line comment? /* This style */
|
28
|
+
#
|
29
|
+
# line - A String of one line of text.
|
30
|
+
#
|
31
|
+
# Returns a boolean.
|
32
|
+
def self.end_multi_line_comment?(line)
|
33
|
+
return false if self.single_line_comment?(line)
|
34
|
+
!!(line =~ /.*\*\//)
|
35
|
+
end
|
36
|
+
|
37
|
+
# Public: Removes comment identifiers for single-line comments.
|
38
|
+
#
|
39
|
+
# line - A String of one line of text.
|
40
|
+
#
|
41
|
+
# Returns a String.
|
42
|
+
def self.parse_single_line(line)
|
43
|
+
cleaned = line.to_s.sub(/\s*\/\//, '')
|
44
|
+
cleaned.rstrip
|
45
|
+
end
|
46
|
+
|
47
|
+
# Public: Remove comment identifiers for multi-line comments.
|
48
|
+
#
|
49
|
+
# line - A String of one line of text.
|
50
|
+
#
|
51
|
+
# Returns a String.
|
52
|
+
def self.parse_multi_line(line)
|
53
|
+
cleaned = line.to_s.sub(/\s*\/\*/, '')
|
54
|
+
cleaned = cleaned.sub(/\*\//, '')
|
55
|
+
cleaned.rstrip
|
56
|
+
end
|
57
|
+
|
58
|
+
# Public: Initializes a new comment parser object. Does not parse on
|
59
|
+
# initialization.
|
60
|
+
#
|
61
|
+
# file_path - The location of the file to parse as a String.
|
62
|
+
# options - Optional options hash.
|
63
|
+
# :preserve_whitespace - Preserve the whitespace before/after comment
|
64
|
+
# markers (default:false).
|
65
|
+
#
|
66
|
+
def initialize(file_path, options={})
|
67
|
+
@options = options
|
68
|
+
@options[:preserve_whitespace] = false if @options[:preserve_whitespace].nil?
|
69
|
+
@file_path = file_path
|
70
|
+
@blocks = []
|
71
|
+
@parsed = false
|
72
|
+
end
|
73
|
+
|
74
|
+
# Public: The different sections of parsed comment text. A section is
|
75
|
+
# either a multi-line comment block's content, or consecutive lines of
|
76
|
+
# single-line comments.
|
77
|
+
#
|
78
|
+
# Returns an Array of parsed comment Strings.
|
79
|
+
def blocks
|
80
|
+
@parsed ? @blocks : parse_blocks
|
81
|
+
end
|
82
|
+
|
83
|
+
|
84
|
+
# Parse the file for comment blocks and populate them into @blocks.
|
85
|
+
#
|
86
|
+
# Returns an Array of parsed comment Strings.
|
87
|
+
def parse_blocks
|
88
|
+
File.open @file_path do |file|
|
89
|
+
current_block = nil
|
90
|
+
inside_single_line_block = false
|
91
|
+
inside_multi_line_block = false
|
92
|
+
|
93
|
+
file.each_line do |line|
|
94
|
+
# Parse single-line style
|
95
|
+
if self.class.single_line_comment?(line)
|
96
|
+
parsed = self.class.parse_single_line line
|
97
|
+
if inside_single_line_block
|
98
|
+
current_block += "\n#{parsed}"
|
99
|
+
else
|
100
|
+
current_block = parsed.to_s
|
101
|
+
inside_single_line_block = true
|
102
|
+
end
|
103
|
+
end
|
104
|
+
|
105
|
+
# Parse multi-lines tyle
|
106
|
+
if self.class.start_multi_line_comment?(line) || inside_multi_line_block
|
107
|
+
parsed = self.class.parse_multi_line line
|
108
|
+
if inside_multi_line_block
|
109
|
+
current_block += "\n#{parsed}"
|
110
|
+
else
|
111
|
+
current_block = parsed
|
112
|
+
inside_multi_line_block = true
|
113
|
+
end
|
114
|
+
end
|
115
|
+
|
116
|
+
# End a multi-line block if detected
|
117
|
+
inside_multi_line_block = false if self.class.end_multi_line_comment?(line)
|
118
|
+
|
119
|
+
# Store the current block if we're done
|
120
|
+
unless self.class.single_line_comment?(line) || inside_multi_line_block
|
121
|
+
@blocks << normalize(current_block) unless current_block.nil?
|
122
|
+
|
123
|
+
inside_single_line_block = false
|
124
|
+
current_block = nil
|
125
|
+
end
|
126
|
+
end
|
127
|
+
end
|
128
|
+
|
129
|
+
@parsed = true
|
130
|
+
@blocks
|
131
|
+
end
|
132
|
+
|
133
|
+
# Normalizes the comment block to ignore any consistent preceding
|
134
|
+
# whitespace. Consistent means the same amount of whitespace on every line
|
135
|
+
# of the comment block. Also strips any whitespace at the start and end of
|
136
|
+
# the whole block.
|
137
|
+
#
|
138
|
+
# Returns a String of normalized text.
|
139
|
+
def normalize(text_block)
|
140
|
+
return text_block if @options[:preserve_whitespace]
|
141
|
+
|
142
|
+
# Strip out any preceding [whitespace]* that occur on every line. Not
|
143
|
+
# the smartest, but I wonder if I care.
|
144
|
+
text_block = text_block.gsub(/^(\s*\*+)/, '')
|
145
|
+
|
146
|
+
# Strip consistent indenting by measuring first line's whitespace
|
147
|
+
indent_size = nil
|
148
|
+
unindented = text_block.split("\n").collect do |line|
|
149
|
+
preceding_whitespace = line.scan(/^\s*/)[0].to_s.size
|
150
|
+
indent_size = preceding_whitespace if indent_size.nil?
|
151
|
+
if line == ""
|
152
|
+
""
|
153
|
+
elsif indent_size <= preceding_whitespace && indent_size > 0
|
154
|
+
line.slice(indent_size, line.length - 1)
|
155
|
+
else
|
156
|
+
line
|
157
|
+
end
|
158
|
+
end.join("\n")
|
159
|
+
|
160
|
+
unindented.strip
|
161
|
+
end
|
162
|
+
|
163
|
+
end
|
164
|
+
end
|
data/lib/kss/modifier.rb
ADDED
@@ -0,0 +1,36 @@
|
|
1
|
+
module Kss
|
2
|
+
# Public: Represents a style modifier. Usually a class name or a
|
3
|
+
# pseudo-class such as :hover. See the spec on The Modifiers Section for
|
4
|
+
# more information.
|
5
|
+
class Modifier
|
6
|
+
|
7
|
+
# Public: Returns the modifier name String.
|
8
|
+
attr_accessor :name
|
9
|
+
|
10
|
+
# Public: Returns the description String for a Modifier.
|
11
|
+
attr_accessor :description
|
12
|
+
|
13
|
+
# Public: Initialize a new Modifier.
|
14
|
+
#
|
15
|
+
# name - The name String of the modifier.
|
16
|
+
# description - The description String of the modifier.
|
17
|
+
def initialize(name, description=nil)
|
18
|
+
@name = name.to_s
|
19
|
+
@description = description
|
20
|
+
end
|
21
|
+
|
22
|
+
# Public: The modifier name as a CSS class. For pseudo-classes, a
|
23
|
+
# generated class name is returned. Useful for generating styleguides.
|
24
|
+
#
|
25
|
+
# Examples
|
26
|
+
#
|
27
|
+
# :hover => "pseudo-class-hover"
|
28
|
+
# sexy-button => "sexy-button"
|
29
|
+
#
|
30
|
+
# Returns a CSS class String.
|
31
|
+
def class_name
|
32
|
+
name.gsub('.', ' ').gsub(':', ' pseudo-class-').strip
|
33
|
+
end
|
34
|
+
|
35
|
+
end
|
36
|
+
end
|
data/lib/kss/parser.rb
ADDED
@@ -0,0 +1,50 @@
|
|
1
|
+
module Kss
|
2
|
+
# Public: The main KSS parser. Takes a directory full of SASS / SCSS / CSS
|
3
|
+
# files and parses the KSS within them.
|
4
|
+
class Parser
|
5
|
+
|
6
|
+
# Public: Returns a hash of Sections.
|
7
|
+
attr_accessor :sections
|
8
|
+
|
9
|
+
# Public: Initializes a new parser based on a directory of files. Scans
|
10
|
+
# within the directory recursively for any comment blocks that look like
|
11
|
+
# KSS.
|
12
|
+
#
|
13
|
+
# base_path - The path String where style files are located.
|
14
|
+
def initialize(base_path)
|
15
|
+
@sections = {}
|
16
|
+
|
17
|
+
Dir["#{base_path}/**/*.*"].each do |filename|
|
18
|
+
parser = CommentParser.new(filename)
|
19
|
+
parser.blocks.each do |comment_block|
|
20
|
+
add_section comment_block, filename if self.class.kss_block?(comment_block)
|
21
|
+
end
|
22
|
+
end
|
23
|
+
end
|
24
|
+
|
25
|
+
def add_section comment_text, filename
|
26
|
+
base_name = File.basename(filename)
|
27
|
+
section = Section.new(comment_text, base_name)
|
28
|
+
@sections[section.section] = section
|
29
|
+
end
|
30
|
+
|
31
|
+
# Public: Takes a cleaned (no comment syntax like // or /* */) comment
|
32
|
+
# block and determines whether it is a KSS documentation block.
|
33
|
+
#
|
34
|
+
# Returns a boolean indicating whether the block conforms to KSS.
|
35
|
+
def self.kss_block?(cleaned_comment)
|
36
|
+
return false unless cleaned_comment.is_a? String
|
37
|
+
|
38
|
+
possible_reference = cleaned_comment.split("\n\n").last
|
39
|
+
possible_reference =~ /Styleguide \d/
|
40
|
+
end
|
41
|
+
|
42
|
+
# Public: Finds the Section for a given styleguide reference.
|
43
|
+
#
|
44
|
+
# Returns a Section for a reference, or a blank Section if none found.
|
45
|
+
def section(reference)
|
46
|
+
@sections[reference] || Section.new
|
47
|
+
end
|
48
|
+
|
49
|
+
end
|
50
|
+
end
|
data/lib/kss/section.rb
ADDED
@@ -0,0 +1,80 @@
|
|
1
|
+
module Kss
|
2
|
+
# Public: Represents a styleguide section. Each section describes one UI
|
3
|
+
# element. A Section can be thought of as the collection of the description,
|
4
|
+
# modifiers, and styleguide reference.
|
5
|
+
class Section
|
6
|
+
|
7
|
+
# Returns the raw comment text for the section, not including comment
|
8
|
+
# syntax (such as // or /* */).
|
9
|
+
attr_reader :raw
|
10
|
+
|
11
|
+
# Public: Returns the filename where this section is found.
|
12
|
+
attr_reader :filename
|
13
|
+
|
14
|
+
# Public: Initialize a new Section
|
15
|
+
#
|
16
|
+
# comment_text - The raw comment String, minus any comment syntax.
|
17
|
+
# filename - The filename as a String.
|
18
|
+
def initialize(comment_text=nil, filename=nil)
|
19
|
+
@raw = comment_text
|
20
|
+
@filename = filename
|
21
|
+
end
|
22
|
+
|
23
|
+
# Splits up the raw comment text into comment sections that represent
|
24
|
+
# description, modifiers, etc.
|
25
|
+
#
|
26
|
+
# Returns an Array of comment Strings.
|
27
|
+
def comment_sections
|
28
|
+
@comment_sections ||= raw ? raw.split("\n\n") : []
|
29
|
+
end
|
30
|
+
|
31
|
+
# Public: The styleguide section for which this comment block references.
|
32
|
+
#
|
33
|
+
# Returns the section reference String (ex: "2.1.8").
|
34
|
+
def section
|
35
|
+
return @section unless @section.nil?
|
36
|
+
|
37
|
+
comment_sections.each do |text|
|
38
|
+
if text =~ /Styleguide \d/i
|
39
|
+
cleaned = text.strip.sub(/\.$/, '') # Kill trailing period
|
40
|
+
@section = cleaned.match(/Styleguide (.+)/)[1]
|
41
|
+
end
|
42
|
+
end
|
43
|
+
|
44
|
+
@section
|
45
|
+
end
|
46
|
+
|
47
|
+
# Public: The description section of a styleguide comment block.
|
48
|
+
#
|
49
|
+
# Returns the description String.
|
50
|
+
def description
|
51
|
+
comment_sections.first
|
52
|
+
end
|
53
|
+
|
54
|
+
# Public: The modifiers section of a styleguide comment block.
|
55
|
+
#
|
56
|
+
# Returns an Array of Modifiers.
|
57
|
+
def modifiers
|
58
|
+
last_indent = nil
|
59
|
+
modifiers = []
|
60
|
+
return modifiers unless comment_sections[1]
|
61
|
+
|
62
|
+
comment_sections[1].split("\n").each do |line|
|
63
|
+
next if line.strip.empty?
|
64
|
+
indent = line.scan(/^\s*/)[0].to_s.size
|
65
|
+
|
66
|
+
if last_indent && indent > last_indent
|
67
|
+
modifiers.last.description += line.squeeze(" ")
|
68
|
+
else
|
69
|
+
modifier, desc = line.split(" - ")
|
70
|
+
modifiers << Modifier.new(modifier.strip, desc.strip) if modifier && desc
|
71
|
+
end
|
72
|
+
|
73
|
+
last_indent = indent
|
74
|
+
end
|
75
|
+
|
76
|
+
modifiers
|
77
|
+
end
|
78
|
+
|
79
|
+
end
|
80
|
+
end
|
data/lib/kss/version.rb
ADDED
@@ -0,0 +1,73 @@
|
|
1
|
+
require 'test/helper'
|
2
|
+
|
3
|
+
class CommentParser < Kss::Test
|
4
|
+
|
5
|
+
def setup
|
6
|
+
loc = 'test/fixtures/comments.txt'
|
7
|
+
@parsed_comments = Kss::CommentParser.new(loc).blocks
|
8
|
+
end
|
9
|
+
|
10
|
+
test "detects single-line comment syntax" do
|
11
|
+
assert Kss::CommentParser.single_line_comment?("// yuuuuup")
|
12
|
+
assert !Kss::CommentParser.single_line_comment?("nooooope")
|
13
|
+
end
|
14
|
+
|
15
|
+
test "detects start of multi--line comment syntax" do
|
16
|
+
assert Kss::CommentParser.start_multi_line_comment?("/* yuuuuup")
|
17
|
+
assert !Kss::CommentParser.start_multi_line_comment?("nooooope")
|
18
|
+
end
|
19
|
+
|
20
|
+
test "detects end of multi-line comment syntax" do
|
21
|
+
assert Kss::CommentParser.end_multi_line_comment?(" yuuuuup */")
|
22
|
+
assert !Kss::CommentParser.end_multi_line_comment?("nooooope")
|
23
|
+
end
|
24
|
+
|
25
|
+
test "parses the single-line comment syntax" do
|
26
|
+
assert_equal " yuuuuup", Kss::CommentParser.parse_single_line("// yuuuuup")
|
27
|
+
end
|
28
|
+
|
29
|
+
test "parses the multi-line comment syntax" do
|
30
|
+
assert_equal " yuuuup", Kss::CommentParser.parse_multi_line("/* yuuuup */")
|
31
|
+
end
|
32
|
+
|
33
|
+
test "finds single-line comment styles" do
|
34
|
+
expected = <<comment
|
35
|
+
This comment block has comment identifiers on every line.
|
36
|
+
|
37
|
+
Fun fact: this is Kyle's favorite comment syntax!
|
38
|
+
comment
|
39
|
+
assert @parsed_comments.include? expected.rstrip
|
40
|
+
end
|
41
|
+
|
42
|
+
test "finds block-style comment styles" do
|
43
|
+
expected = <<comment
|
44
|
+
This comment block is a block-style comment syntax.
|
45
|
+
|
46
|
+
There's only two identifier across multiple lines.
|
47
|
+
comment
|
48
|
+
assert @parsed_comments.include? expected.rstrip
|
49
|
+
|
50
|
+
|
51
|
+
expected = <<comment
|
52
|
+
This is another common multi-line comment style.
|
53
|
+
|
54
|
+
It has stars at the begining of every line.
|
55
|
+
comment
|
56
|
+
assert @parsed_comments.include? expected.rstrip
|
57
|
+
|
58
|
+
end
|
59
|
+
|
60
|
+
test "handles mixed styles" do
|
61
|
+
expected = "This comment has a /* comment */ identifier inside of it!"
|
62
|
+
assert @parsed_comments.include? expected
|
63
|
+
|
64
|
+
expected = "Look at my //cool// comment art!"
|
65
|
+
assert @parsed_comments.include? expected
|
66
|
+
end
|
67
|
+
|
68
|
+
test "handles indented comments" do
|
69
|
+
assert @parsed_comments.include? "Indented single-line comment."
|
70
|
+
assert @parsed_comments.include? "Indented block comment."
|
71
|
+
end
|
72
|
+
|
73
|
+
end
|
@@ -0,0 +1,33 @@
|
|
1
|
+
This file is used for generic comment parsing across CSS, SCSS, SASS & LESS.
|
2
|
+
|
3
|
+
There's single-line comment styles:
|
4
|
+
|
5
|
+
// This comment block has comment identifiers on every line.
|
6
|
+
//
|
7
|
+
// Fun fact: this is Kyle's favorite comment syntax!
|
8
|
+
|
9
|
+
|
10
|
+
There's block comment styles:
|
11
|
+
|
12
|
+
/* This comment block is a block-style comment syntax.
|
13
|
+
|
14
|
+
There's only two identifier across multiple lines. */
|
15
|
+
|
16
|
+
/* This is another common multi-line comment style.
|
17
|
+
*
|
18
|
+
* It has stars at the begining of every line.
|
19
|
+
*/
|
20
|
+
|
21
|
+
|
22
|
+
Some people do crazy things like mix comment styles:
|
23
|
+
|
24
|
+
// This comment has a /* comment */ identifier inside of it!
|
25
|
+
|
26
|
+
/* Look at my //cool// comment art! */
|
27
|
+
|
28
|
+
|
29
|
+
Indented comments:
|
30
|
+
|
31
|
+
// Indented single-line comment.
|
32
|
+
|
33
|
+
/* Indented block comment. */
|
@@ -0,0 +1,38 @@
|
|
1
|
+
/*
|
2
|
+
Your standard form button.
|
3
|
+
|
4
|
+
:hover - Highlights when hovering.
|
5
|
+
:disabled - Dims the button when disabled.
|
6
|
+
.primary - Indicates button is the primary action.
|
7
|
+
.smaller - A little bit smaller now.
|
8
|
+
|
9
|
+
Styleguide 2.1.1.
|
10
|
+
*/
|
11
|
+
button {
|
12
|
+
padding: 5px 15px; }
|
13
|
+
button.primary, button.primary:hover {
|
14
|
+
color: #fff; }
|
15
|
+
button.smaller {
|
16
|
+
font-size: 11px; }
|
17
|
+
button:hover {
|
18
|
+
color: #337797; }
|
19
|
+
button:disabled {
|
20
|
+
opacity: 0.5; }
|
21
|
+
|
22
|
+
|
23
|
+
/*
|
24
|
+
A button suitable for giving stars to someone.
|
25
|
+
|
26
|
+
.star-given - A highlight indicating you've already given a star.
|
27
|
+
.disabled - Dims the button to indicate it cannot be used.
|
28
|
+
|
29
|
+
Styleguide 2.2.1.
|
30
|
+
*/
|
31
|
+
a.button.star {
|
32
|
+
display: inline-block; }
|
33
|
+
a.button.star .star {
|
34
|
+
font-size: 10px; }
|
35
|
+
a.button.star.star-given {
|
36
|
+
color: #ae7e00; }
|
37
|
+
a.button.star.disabled {
|
38
|
+
opacity: 0.5; }
|
@@ -0,0 +1,51 @@
|
|
1
|
+
/*
|
2
|
+
Your standard form button.
|
3
|
+
|
4
|
+
:hover - Highlights when hovering.
|
5
|
+
:disabled - Dims the button when disabled.
|
6
|
+
.primary - Indicates button is the primary action.
|
7
|
+
.smaller - A little bit smaller now.
|
8
|
+
|
9
|
+
Styleguide 2.1.1.
|
10
|
+
*/
|
11
|
+
button, .button {
|
12
|
+
padding:5px 15px;
|
13
|
+
|
14
|
+
&.primary, &.primary:hover{
|
15
|
+
color:#fff;
|
16
|
+
}
|
17
|
+
|
18
|
+
&.smaller{
|
19
|
+
font-size:9px;
|
20
|
+
}
|
21
|
+
|
22
|
+
&:hover{
|
23
|
+
color:#337797;
|
24
|
+
}
|
25
|
+
|
26
|
+
&:disabled{
|
27
|
+
opacity:0.5;
|
28
|
+
}
|
29
|
+
}
|
30
|
+
|
31
|
+
/*
|
32
|
+
A button suitable for giving stars to someone.
|
33
|
+
|
34
|
+
.star-given - A highlight indicating you've already given a star.
|
35
|
+
.disabled - Dims the button to indicate it cannot be used.
|
36
|
+
|
37
|
+
Styleguide 2.2.1.
|
38
|
+
*/
|
39
|
+
a.button.star{
|
40
|
+
display:inline-block;
|
41
|
+
|
42
|
+
.star{ font-size:10px; }
|
43
|
+
|
44
|
+
&.star-given{
|
45
|
+
color:#ae7e00;
|
46
|
+
}
|
47
|
+
|
48
|
+
&.disabled{
|
49
|
+
opacity:0.5;
|
50
|
+
}
|
51
|
+
}
|
@@ -0,0 +1,40 @@
|
|
1
|
+
/* Your standard form button.
|
2
|
+
*
|
3
|
+
* :hover - Highlights when hovering.
|
4
|
+
* :disabled - Dims the button when disabled.
|
5
|
+
* .primary - Indicates button is the primary action.
|
6
|
+
* .smaller - A little bit smaller now.
|
7
|
+
*
|
8
|
+
* Styleguide 2.1.1. */
|
9
|
+
button
|
10
|
+
padding: 5px 15px
|
11
|
+
|
12
|
+
&.primary, &.primary:hover
|
13
|
+
color: #fff
|
14
|
+
|
15
|
+
&.smaller
|
16
|
+
font-size: 11px
|
17
|
+
|
18
|
+
&:hover
|
19
|
+
color: #337797
|
20
|
+
|
21
|
+
&:disabled
|
22
|
+
opacity: 0.5
|
23
|
+
|
24
|
+
// A button suitable for giving stars to someone.
|
25
|
+
//
|
26
|
+
// .star-given - A highlight indicating you've already given a star.
|
27
|
+
// .disabled - Dims the button to indicate it cannot be used.
|
28
|
+
//
|
29
|
+
// Styleguide 2.2.1.
|
30
|
+
a.button.star
|
31
|
+
display: inline-block
|
32
|
+
|
33
|
+
.star
|
34
|
+
font-size: 10px
|
35
|
+
|
36
|
+
&.star-given
|
37
|
+
color: #ae7e00
|
38
|
+
|
39
|
+
&.disabled
|
40
|
+
opacity: 0.5
|
@@ -0,0 +1,47 @@
|
|
1
|
+
// Your standard form button.
|
2
|
+
//
|
3
|
+
// :hover - Highlights when hovering.
|
4
|
+
// :disabled - Dims the button when disabled.
|
5
|
+
// .primary - Indicates button is the primary action.
|
6
|
+
// .smaller - A little bit smaller now.
|
7
|
+
//
|
8
|
+
// Styleguide 2.1.1.
|
9
|
+
button{
|
10
|
+
padding:5px 15px;
|
11
|
+
|
12
|
+
&.primary, &.primary:hover{
|
13
|
+
color:#fff;
|
14
|
+
}
|
15
|
+
|
16
|
+
&.smaller{
|
17
|
+
font-size:11px;
|
18
|
+
}
|
19
|
+
|
20
|
+
&:hover{
|
21
|
+
color:#337797;
|
22
|
+
}
|
23
|
+
|
24
|
+
&:disabled{
|
25
|
+
opacity:0.5;
|
26
|
+
}
|
27
|
+
}
|
28
|
+
|
29
|
+
// A button suitable for giving stars to someone.
|
30
|
+
//
|
31
|
+
// .star-given - A highlight indicating you've already given a star.
|
32
|
+
// .disabled - Dims the button to indicate it cannot be used.
|
33
|
+
//
|
34
|
+
// Styleguide 2.2.1.
|
35
|
+
a.button.star{
|
36
|
+
display:inline-block;
|
37
|
+
|
38
|
+
.star{ font-size:10px; }
|
39
|
+
|
40
|
+
&.star-given{
|
41
|
+
color:#ae7e00;
|
42
|
+
}
|
43
|
+
|
44
|
+
&.disabled{
|
45
|
+
opacity:0.5;
|
46
|
+
}
|
47
|
+
}
|
data/test/helper.rb
ADDED
@@ -0,0 +1,19 @@
|
|
1
|
+
require 'test/unit'
|
2
|
+
|
3
|
+
require 'kss'
|
4
|
+
|
5
|
+
module Kss
|
6
|
+
class Test < ::Test::Unit::TestCase
|
7
|
+
def self.test(name, &block)
|
8
|
+
define_method("test_#{name.gsub(/\W/,'_')}", &block) if block
|
9
|
+
end
|
10
|
+
|
11
|
+
def default_test
|
12
|
+
end
|
13
|
+
|
14
|
+
def fixture(name)
|
15
|
+
@fixtures ||= {}
|
16
|
+
@fixtures[name] ||= File.read("test/fixtures/#{name}")
|
17
|
+
end
|
18
|
+
end
|
19
|
+
end
|
data/test/parser_test.rb
ADDED
@@ -0,0 +1,107 @@
|
|
1
|
+
require 'test/helper'
|
2
|
+
|
3
|
+
class ParserTest < Kss::Test
|
4
|
+
|
5
|
+
def setup
|
6
|
+
@scss_parsed = Kss::Parser.new('test/fixtures/scss')
|
7
|
+
@sass_parsed = Kss::Parser.new('test/fixtures/sass')
|
8
|
+
@css_parsed = Kss::Parser.new('test/fixtures/css')
|
9
|
+
@less_parsed = Kss::Parser.new('test/fixtures/less')
|
10
|
+
|
11
|
+
@css_comment = <<comment
|
12
|
+
/*
|
13
|
+
A button suitable for giving stars to someone.
|
14
|
+
|
15
|
+
.star-given - A highlight indicating you've already given a star.
|
16
|
+
.disabled - Dims the button to indicate it cannot be used.
|
17
|
+
|
18
|
+
Styleguide 2.2.1.
|
19
|
+
*/
|
20
|
+
comment
|
21
|
+
|
22
|
+
@starred_css_comment = <<comment
|
23
|
+
/* A button suitable for giving stars to someone.
|
24
|
+
*
|
25
|
+
* .star-given - A highlight indicating you've already given a star.
|
26
|
+
* .disabled - Dims the button to indicate it cannot be used.
|
27
|
+
*
|
28
|
+
* Styleguide 2.2.1. */
|
29
|
+
comment
|
30
|
+
|
31
|
+
@slashed_css_comment = <<comment
|
32
|
+
// A button suitable for giving stars to someone.
|
33
|
+
//
|
34
|
+
// .star-given - A highlight indicating you've already given a star.
|
35
|
+
// .disabled - Dims the button to indicate it cannot be used.
|
36
|
+
//
|
37
|
+
// Styleguide 2.2.1.
|
38
|
+
comment
|
39
|
+
|
40
|
+
@indented_css_comment = <<comment
|
41
|
+
/*
|
42
|
+
A button suitable for giving stars to someone.
|
43
|
+
|
44
|
+
.star-given - A highlight indicating you've already given a star.
|
45
|
+
.disabled - Dims the button to indicate it cannot be used.
|
46
|
+
|
47
|
+
Styleguide 2.2.1.
|
48
|
+
*/
|
49
|
+
comment
|
50
|
+
|
51
|
+
@cleaned_css_comment = <<comment
|
52
|
+
A button suitable for giving stars to someone.
|
53
|
+
|
54
|
+
.star-given - A highlight indicating you've already given a star.
|
55
|
+
.disabled - Dims the button to indicate it cannot be used.
|
56
|
+
|
57
|
+
Styleguide 2.2.1.
|
58
|
+
comment
|
59
|
+
@cleaned_css_comment.rstrip!
|
60
|
+
|
61
|
+
end
|
62
|
+
|
63
|
+
test "parses KSS comments in SCSS" do
|
64
|
+
assert_equal 'Your standard form button.',
|
65
|
+
@scss_parsed.section('2.1.1').description
|
66
|
+
end
|
67
|
+
|
68
|
+
test "parsers KSS comments in LESS" do
|
69
|
+
assert_equal 'Your standard form button.',
|
70
|
+
@less_parsed.section('2.1.1').description
|
71
|
+
end
|
72
|
+
|
73
|
+
test "parses KSS multi-line comments in SASS (/* ... */)" do
|
74
|
+
assert_equal 'Your standard form button.',
|
75
|
+
@sass_parsed.section('2.1.1').description
|
76
|
+
end
|
77
|
+
|
78
|
+
test "parses KSS single-line comments in SASS (// ... )" do
|
79
|
+
assert_equal 'A button suitable for giving stars to someone.',
|
80
|
+
@sass_parsed.section('2.2.1').description
|
81
|
+
end
|
82
|
+
|
83
|
+
test "parses KSS comments in CSS" do
|
84
|
+
assert_equal 'Your standard form button.',
|
85
|
+
@css_parsed.section('2.1.1').description
|
86
|
+
end
|
87
|
+
|
88
|
+
test "parses nested SCSS documents" do
|
89
|
+
assert_equal "Your standard form element.", @scss_parsed.section('3.0.0').description
|
90
|
+
assert_equal "Your standard text input box.", @scss_parsed.section('3.0.1').description
|
91
|
+
end
|
92
|
+
|
93
|
+
test "parses nested LESS documents" do
|
94
|
+
assert_equal "Your standard form element.", @less_parsed.section('3.0.0').description
|
95
|
+
assert_equal "Your standard text input box.", @less_parsed.section('3.0.1').description
|
96
|
+
end
|
97
|
+
|
98
|
+
test "parses nested SASS documents" do
|
99
|
+
assert_equal "Your standard form element.", @sass_parsed.section('3.0.0').description
|
100
|
+
assert_equal "Your standard text input box.", @sass_parsed.section('3.0.1').description
|
101
|
+
end
|
102
|
+
|
103
|
+
test "public sections returns hash of sections" do
|
104
|
+
assert_equal 2, @css_parsed.sections.count
|
105
|
+
end
|
106
|
+
|
107
|
+
end
|
@@ -0,0 +1,40 @@
|
|
1
|
+
require 'test/helper'
|
2
|
+
|
3
|
+
class SectionTest < Kss::Test
|
4
|
+
|
5
|
+
def setup
|
6
|
+
@comment_text = <<comment
|
7
|
+
Your standard form button.
|
8
|
+
|
9
|
+
:hover - Highlights when hovering.
|
10
|
+
:disabled - Dims the button when disabled.
|
11
|
+
.primary - Indicates button is the primary action.
|
12
|
+
.smaller - A smaller button
|
13
|
+
|
14
|
+
Styleguide 2.1.1.
|
15
|
+
comment
|
16
|
+
|
17
|
+
@section = Kss::Section.new(@comment_text, 'example.css')
|
18
|
+
end
|
19
|
+
|
20
|
+
test "parses the description" do
|
21
|
+
assert_equal "Your standard form button.", @section.description
|
22
|
+
end
|
23
|
+
|
24
|
+
test "parses the modifiers" do
|
25
|
+
assert_equal 4, @section.modifiers.size
|
26
|
+
end
|
27
|
+
|
28
|
+
test "parses a modifier's names" do
|
29
|
+
assert_equal ':hover', @section.modifiers.first.name
|
30
|
+
end
|
31
|
+
|
32
|
+
test "parses a modifier's description" do
|
33
|
+
assert_equal 'Highlights when hovering.', @section.modifiers.first.description
|
34
|
+
end
|
35
|
+
|
36
|
+
test "parses the styleguide reference" do
|
37
|
+
assert_equal '2.1.1', @section.section
|
38
|
+
end
|
39
|
+
|
40
|
+
end
|
metadata
ADDED
@@ -0,0 +1,72 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: kss-alan
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 0.3.0
|
5
|
+
prerelease:
|
6
|
+
platform: ruby
|
7
|
+
authors:
|
8
|
+
- Alan Hogan
|
9
|
+
autorequire:
|
10
|
+
bindir: bin
|
11
|
+
cert_chain: []
|
12
|
+
date: 2012-06-10 00:00:00.000000000 Z
|
13
|
+
dependencies: []
|
14
|
+
description: ! " Inspired by TomDoc, KSS attempts to provide a methodology for writing\n
|
15
|
+
\ maintainable, documented CSS within a team. Specifically, KSS is a CSS\n structure,
|
16
|
+
documentation specification, and styleguide format.\n\n This is a ruby library
|
17
|
+
for parsing KSS documented CSS and generating\n styleguides.\n"
|
18
|
+
email: gem@alanhogan.com
|
19
|
+
executables: []
|
20
|
+
extensions: []
|
21
|
+
extra_rdoc_files: []
|
22
|
+
files:
|
23
|
+
- README.md
|
24
|
+
- Rakefile
|
25
|
+
- LICENSE
|
26
|
+
- lib/kss/comment_parser.rb
|
27
|
+
- lib/kss/modifier.rb
|
28
|
+
- lib/kss/parser.rb
|
29
|
+
- lib/kss/section.rb
|
30
|
+
- lib/kss/version.rb
|
31
|
+
- lib/kss.coffee
|
32
|
+
- lib/kss.rb
|
33
|
+
- test/comment_parser_test.rb
|
34
|
+
- test/fixtures/comments.txt
|
35
|
+
- test/fixtures/css/buttons.css
|
36
|
+
- test/fixtures/less/_label.less
|
37
|
+
- test/fixtures/less/buttons.less
|
38
|
+
- test/fixtures/less/mixins.less
|
39
|
+
- test/fixtures/less/nested.less
|
40
|
+
- test/fixtures/sass/buttons.sass
|
41
|
+
- test/fixtures/sass/nested.sass
|
42
|
+
- test/fixtures/scss/buttons.scss
|
43
|
+
- test/fixtures/scss/nested.scss
|
44
|
+
- test/helper.rb
|
45
|
+
- test/parser_test.rb
|
46
|
+
- test/section_test.rb
|
47
|
+
homepage: http://github.com/kneath/kss
|
48
|
+
licenses: []
|
49
|
+
post_install_message:
|
50
|
+
rdoc_options: []
|
51
|
+
require_paths:
|
52
|
+
- lib
|
53
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
54
|
+
none: false
|
55
|
+
requirements:
|
56
|
+
- - ! '>='
|
57
|
+
- !ruby/object:Gem::Version
|
58
|
+
version: '0'
|
59
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
60
|
+
none: false
|
61
|
+
requirements:
|
62
|
+
- - ! '>='
|
63
|
+
- !ruby/object:Gem::Version
|
64
|
+
version: '0'
|
65
|
+
requirements: []
|
66
|
+
rubyforge_project:
|
67
|
+
rubygems_version: 1.8.24
|
68
|
+
signing_key:
|
69
|
+
specification_version: 3
|
70
|
+
summary: A library for parsing KSS documented stylesheets and generating styleguides
|
71
|
+
(originally by Kyle Neath)
|
72
|
+
test_files: []
|