haml_to_star 0.2 → 0.3

data/MIT-LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright 2012 Sebastien Drouyer
+https://github.com/sdrdis/haml_to_star
+
+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 @@
+haml_to_*
+=========
+
+haml_to_star is a ruby library that purpose is to allow you to transform haml to any language.
+
+The compiler class handle common processing tasks as generating the code tree and html tags, but functions that are specific to languages such as how the code in the source code must be implemented on extensions.
+
+Please take a look at known extensions and at the documentation if you want to create your own extension.
+
+Known extensions
+----------------
+
+[haml_to_js](https://github.com/sdrdis/haml_to_js) converts haml to javascript
+
+Contributions
+-------------
+
+This project is hosted on [github](https://github.com/sdrdis/haml_to_star), so don't hesitate to contribute and raise issues.
+
+License
+-------
+
+This project is under MIT License.

data/haml_to_star.gemspec

@@ -0,0 +1,17 @@
+Gem::Specification.new do |s|
+  s.name        = 'haml_to_star'
+  s.version     = '0.3'
+  s.date        = '2012-12-25'
+  s.summary     = "haml_to_star is a ruby library that purpose is to allow you to transform haml to any language."
+  s.description =<<eos
+haml_to_star is a ruby library that purpose is to allow you to transform haml to any language.
+
+The compiler class handle common processing tasks as generating the code tree and html tags, but functions that are specific to languages such as how the code in the source code must be implemented on extensions.
+
+Please take a look at known extensions and at the documentation if you want to create your own extension.
+eos
+  s.authors     = ["Sébastien Drouyer"]
+  s.email       = 'sdrdis@hotmail.com'
+  s.files       = `git ls-files`.split("\n")
+  s.homepage    = 'https://github.com/sdrdis/haml_to_star'
+end

data/lib/haml_to_star/code_node.rb

@@ -0,0 +1,29 @@
+module HamlToStar
+
+  # This class is used only internally. It allows the compiler to construct the tree
+  # associated to the haml code. A code element is equivalent to a line in haml.
+  class CodeNode
+    
+    # Current line in haml
+    #
+    # @return [String]
+    attr_accessor :line
+    
+    # Children of current line in haml
+    #
+    # @return [Array<CodeNode>]
+    attr_accessor :children
+    
+    # The line number of the code element
+    #
+    # @return [Integer]
+    attr_accessor :line_number
+    
+    def initialize
+      @line = ''
+      @line_number = 0
+      @children = []
+    end
+  end
+
+end

data/lib/haml_to_star/compiler.rb

@@ -1,15 +1,35 @@
 require 'rubygems'
 require 'json'
 require 'cgi'
-require 'haml_to_star/code_element'
+require 'haml_to_star/code_node'
 
 module HamlToStar
 
+  # The compiler class transform an haml code to executable code.
   class Compiler
+    # Variable name in which we save resulting html.
+    #
+    # @return [String]
     attr_accessor :variable_name
+    
+    # Variable name in which we save current haml line code (debugging)
+    #
+    # @return [String]
     attr_accessor :variable_line_name
+    
+    # Self closing html tags (like meta or img)
+    #
+    # @return [Array<String>]
     attr_accessor :self_closing
+    
+    # Shortcuts for doc types (ex: 'xml' => '<?xml version="1.0" encoding="utf-8" ?>')
+    #
+    # @return [{String => String}]
     attr_accessor :doc_types
+    
+    # Current line number
+    #
+    # @return [Integer]
     attr_accessor :line_number
     
     def initialize
@@ -37,29 +57,41 @@ module HamlToStar
       }
     end
 
-
+    # Converts haml code to executable code.
+    # Internally, the function first convert it to a {CodeNode} and the calls convert_from_node
+    #
+    # @param str [String] The haml code 
+    #
+    # @return [String]
     def convert_from_string(str)
-      nb_char_spacing = get_indentation_spacing_from_string(str)
+      nb_char_per_indentation = get_indentation_spacing_from_string(str)
       
       @line_number = 0
-      code_tree = CodeElement.new
-      code_tree.children = get_code_children_from_string(str, nb_char_spacing, 0)
-      return convert_from_tree(code_tree) 
+      code_node = CodeNode.new
+      code_node.children = get_code_children_from_string(str, nb_char_per_indentation, 0)
+      return convert_from_node(code_node) 
     end
     
-    def get_code_children_from_string(str, nb_char_spacing, nb_indentation_objective)
+    # Converts haml code into an array of {CodeNode}.
+    # 
+    # @param str [String] The haml code
+    # @param nb_char_per_indentation [Integer] Number of spaces defining one unit indentation
+    # @param nb_indentation_depth [Integer] Depth of indentation we want to analyse (used by the recursivity)
+    #
+    # @return [Array<CodeNode>]
+    def get_code_children_from_string(str, nb_char_per_indentation, nb_indentation_depth)
       temp_str = ''
       children = []
       str.each_line do |line|
-        nb_indentations = get_nb_indentation_from_line(line, nb_char_spacing)
-        if (nb_indentations == nb_indentation_objective)
-          code_element = CodeElement.new
-          code_element.line = line[nb_indentation_objective * nb_char_spacing..line.size]
+        nb_indentations = get_nb_indentation_from_line(line, nb_char_per_indentation)
+        if (nb_indentations == nb_indentation_depth)
+          code_element = CodeNode.new
+          code_element.line = line[nb_indentation_depth * nb_char_per_indentation..line.size]
           if code_element.line[code_element.line.size - 1] == "\n"
             code_element.line = code_element.line[0..code_element.line.size - 2]
           end
           if (temp_str != '')
-            children.last.children = get_code_children_from_string(temp_str, nb_char_spacing, nb_indentation_objective + 1)
+            children.last.children = get_code_children_from_string(temp_str, nb_char_per_indentation, nb_indentation_depth + 1)
             temp_str = ''
           end
           @line_number += 1
@@ -70,13 +102,19 @@ module HamlToStar
         end
       end
       if (temp_str != '')
-        children.last.children = get_code_children_from_string(temp_str, nb_char_spacing, nb_indentation_objective + 1)
+        children.last.children = get_code_children_from_string(temp_str, nb_char_per_indentation, nb_indentation_depth + 1)
         temp_str = ''
       end
       return children
     end
     
-    def get_nb_indentation_from_line(line, nb_char_spacing)
+    # From a line in the haml code, determines the number of indentation unit
+    #
+    # @param line [String] The haml code line
+    # @param nb_char_per_indentation [Integer] Number of spaces defining one unit indentation
+    #
+    # @return [Integer]
+    def get_nb_indentation_from_line(line, nb_char_per_indentation)
       nb_char = 0
       line.each_char do |char|
         if is_spacing_character(char)
@@ -85,12 +123,17 @@ module HamlToStar
           break;
         end
       end
-      if (nb_char % nb_char_spacing != 0)
+      if (nb_char % nb_char_per_indentation != 0)
         raise "Bad indentation"
       end
-      return nb_char / nb_char_spacing
+      return nb_char / nb_char_per_indentation
     end
     
+    # From a haml code, determines number of spaces / tabs composes one indentation unit
+    #
+    # @param str [String] The haml code 
+    #
+    # @return [Integer]
     def get_indentation_spacing_from_string(str)
       str.each_line do |line|
         nb_char = 0
@@ -109,21 +152,31 @@ module HamlToStar
       return 1
     end
     
+    # Returns true if the character is a space or tab, false otherwise
+    #
+    # @param char [String] Character to be analysed
+    #
+    # @return [Boolean]
     def is_spacing_character(char)
       return char == ' ' || char == "\t";
     end
     
-    def convert_from_tree(code_tree, indentation = -1)
+    # Converts a {CodeNode} to executable code.
+    #
+    # @param code_node [CodeNode] The code tree
+    #
+    # @return [String]
+    def convert_from_node(code_node, indentation = -1)
       str = []
     
       inside = []
-      code_tree.children.each do |child|
-        inside << convert_from_tree(child, indentation + 1)
+      code_node.children.each do |child|
+        inside << convert_from_node(child, indentation + 1)
       end
       if (indentation > -1)
-        line = code_tree.line
+        line = code_node.line
         if (line[0] != '-')
-          process_code_number(str, code_tree.line_number)
+          process_code_line_number(str, code_node.line_number)
         end
         if (line[0] == '%' || line[0] == '.' || line[0] == '#')
           dom = convert_dom_element(line)
@@ -153,7 +206,12 @@ module HamlToStar
       
       return str.join("\n")
     end
-      
+    
+    # Converts a line in the haml code into a valid dom element.
+    #
+    # @param line [String] The haml code line
+    #
+    # @return [String]
     def convert_dom_element(line)
       div_base_informations = line.gsub(%r{[^\{ =]*}).first
       infos = div_base_informations.gsub(%r{[%.#][\w-]*})
@@ -185,7 +243,7 @@ module HamlToStar
         elsif (char == '}')
           num_brackets -= 1
           if (num_brackets == 0)
-            params[:additionnals] = process_additionnals(rest_of_line[start_brackets..char_num])
+            params[:dom_params] = process_dom_params(rest_of_line[start_brackets..char_num])
           end
         elsif (num_brackets == 0)
           remaining = rest_of_line[char_num..rest_of_line.size - 1].strip
@@ -205,11 +263,16 @@ module HamlToStar
       return construct_dom(params)
     end
     
+    # Converts object sent by convert_dom_element into a valid dom element.
+    #
+    # @param params [Object] Params sent by convert_dom_element
+    #
+    # @return [String]
     def construct_dom(params)
       dom = {}
       dom[:self_closing] = @self_closing.index(params[:tag])
       dom[:begin] = '\'<' + params[:tag] + ' '
-      if (params[:additionnals])
+      if (params[:dom_params])
         extend = {}
         if (params[:id])
           extend[:id] = params[:id]
@@ -217,7 +280,7 @@ module HamlToStar
         if (params[:class])
           extend[:class] = params[:class]
         end
-        dom[:begin] += '\' + attrs(' + params[:additionnals] + ', ' + extend.to_json + ') + \''
+        dom[:begin] += '\' + attrs(' + params[:dom_params] + ', ' + extend.to_json + ') + \''
       else
         if (params[:id])
           dom[:begin] += 'id="' + params[:id] + '" '
@@ -237,34 +300,60 @@ module HamlToStar
       return dom
     end
     
-    def process_additionnals(additionnals)
-      raise 'To be defined'
-    end
-
-    def process_code_line(line)
+    # Process dom parameters 
+    #
+    # @param dom_params [String] Dom parameters
+    #
+    # @return [String]
+    def process_dom_params(dom_params)
       raise 'To be defined'
     end
     
+    # What should be on the header of generated code
+    #
+    # @param str [String] Result string
+    # @param content [String] Generated code
     def initialize_content(str, content)
       raise 'To be defined'
     end
     
+    # How do we add html content to the result
+    #
+    # @param str [String] Result string
+    # @param content [String] Generated code
     def add_content(str, content)
       raise 'To be defined'
     end
     
+    # How do we add code content to the result
+    #
+    # @param str [String] Result string
+    # @param line [String] Current line
+    # @param inside [String] Children lines
     def add_code(str, line, inside)
       raise 'To be defined'
     end
     
+    # How do we what is after = or !=
+    #
+    # @param line [String] Line to be processed
+    #
+    # @return [String]
     def evaluate(line)
       raise 'To be defined'
     end
     
-    def process_code_number(str, code_number)
+    # How do we add the current line number into the resulted string
+    #
+    # @param str [String] Result string
+    # @param code_line_number [String] Current line number
+    def process_code_line_number(str, code_line_number)
       raise 'To be defined'
     end
     
+    # How do we process lines begining with = or !=
+    #
+    # @param line [String] Line to be processed
     def process_inline_code(str, content)
       raise 'To be defined'
     end   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haml_to_star
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
   prerelease: 
 platform: ruby
 authors:
@@ -9,17 +9,32 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-24 00:00:00.000000000Z
+date: 2012-12-25 00:00:00.000000000Z
 dependencies: []
-description: haml_to_star allows you to convert haml code into any language.
+description: ! 'haml_to_star is a ruby library that purpose is to allow you to transform
+  haml to any language.
+
+
+  The compiler class handle common processing tasks as generating the code tree and
+  html tags, but functions that are specific to languages such as how the code in
+  the source code must be implemented on extensions.
+
+
+  Please take a look at known extensions and at the documentation if you want to create
+  your own extension.
+
+'
 email: sdrdis@hotmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE.txt
+- README.md
+- haml_to_star.gemspec
+- lib/haml_to_star/code_node.rb
 - lib/haml_to_star/compiler.rb
-- lib/haml_to_star/code_element.rb
-homepage: http://rubygems.org/gems/haml_to_star
+homepage: https://github.com/sdrdis/haml_to_star
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -42,5 +57,6 @@ rubyforge_project:
 rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
-summary: convert haml code into an other language
+summary: haml_to_star is a ruby library that purpose is to allow you to transform
+  haml to any language.
 test_files: []

data/lib/haml_to_star/code_element.rb

@@ -1,15 +0,0 @@
-module HamlToStar
-
-  class CodeElement
-    attr_accessor :line
-    attr_accessor :children
-    attr_accessor :line_number
-    
-    def initialize
-      @line = ''
-      @line_number = 0
-      @children = []
-    end
-  end
-
-end