update docs. update map handling

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+### 2.0.2 10/1/14
+* Reversed order that `map-merge` merges instance maps, so that newer instances are merged to the top rather than the bottom. Increased performance benchmarks by `23%`.
+* Added Ruby function for `map-fetch()`. Increased performance benchmarks by `15%`.
+* Updated main API mixin `_()` to follow SassDoc standards.
+
 ### 2.0.1 - 9/25/14
 * Updated Sass dependency to `~> 3.4` in gemspec.
 * Ignore `test` folder in bower.

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "flint",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "main": "stylesheets/_flint.scss",
   "description": "Flint is a highly advanced Sass grid framework designed for rapid responsive development.",
   "authors": ["Ezekiel Gabrielse <ezekg@yahoo.com>"],

lib/flint.rb

@@ -10,8 +10,8 @@
 end
 
 module Flint
-    VERSION = "2.0.1"
-    DATE = "2014-09-25"
+    VERSION = "2.0.2"
+    DATE = "2014-10-01"
 end
 
 module Sass::Script::Functions
@@ -26,41 +26,59 @@ def flint_use_ruby()
     end
 
     ###
-    # Turns string into a flat list
+    # Fetch value from map
     #
-    # @param {String} string    - string
+    # @param {Map}     map  - map to fetch value from
+    # @param {ArgList} keys - list of keys to traverse
+    #
+    # @return {String | False}
+    ###
+    def flint_ruby_map_fetch(map, *keys)
+        assert_type map, :Map, :map
+        result = map
+        keys.each {|key| result != nil ? result = result.to_h.fetch(key, nil) : break}
+        return result != nil ? result : Sass::Script::Bool.new(false)
+    end
+    declare :flint_ruby_map_fetch, :args => [:map, :keys], :var_args => true
+
+    ###
+    # Turn string into a flat list
+    #
+    # @param {String} string    - string to operate on
     # @param {String} separator - item to find which separates substrings
     # @param {String} ignore    - removes remaining string beyond item
     #
     # @return {List}
     ###
-    def string_to_list(string, separator, ignore)
-        # Remove rest of string after ignore
-        ignore = string.value[/[^#{ignore}]+/]
-        # Get first set of strings, convert to array by separator
-        items = ignore.split(separator.value)
-        # Convert array to list
+    def flint_ruby_string_to_list(string, separator, ignore)
+        assert_type string, :String, :string
+        assert_type separator, :String, :separator
+        assert_type ignore, :String, :ignore
+        # Remove everything after ignore, split with separator
+        items = string.value[/[^#{ignore}]+/].split(separator.value)
         if items.count == 1
             Sass::Script::String.new(items[0], :comma)
         else
             Sass::Script::List.new(items.map { |i| Sass::Script::String.new(i) }, :comma)
         end
     end
+    declare :flint_ruby_string_to_list, :args => [:string, :separator, :ignore]
 
     ###
-    # Replace substring
+    # Replace substring with string
     #
     # @param {String} string  - string that contains substring
     # @param {String} find    - substring to replace
     # @param {String} replace - new string to replace sub with
     #
     # @return {String}
     ###
-    def replace_substring(string, find, replace)
+    def flint_ruby_replace_substring(string, find, replace)
+        assert_type string, :String, :string
+        assert_type find, :String, :find
+        assert_type replace, :String, :replace
         Sass::Script::String.new(string.value.gsub(find.value, replace.value))
     end
-
-    declare :string_to_list, [:string, :separator, :ignore]
-    declare :replace_substring, [:string, :find, :replace]
+    declare :flint_ruby_replace_substring, :args => [:string, :find, :replace]
 
 end

stylesheets/flint/config/_config.scss

@@ -1,10 +1,13 @@
 /**
  * Configuration map
  *
+ * @type Map
+ *
  * @prop {Map}    breakpoints                  - map of breakpoints, follow DSC order
  * @prop {Map}    breakpoints.alias            - named map of breakpoint settings
  * @prop {Number} breakpoints.alias.columns    - column count for breakpoint
  * @prop {Number} breakpoints.alias.breakpoint - breakpoint value for breakpoint
+ *
  * @prop {Map}    settings                     - map of settings for grid
  * @prop {String} settings.default             - alias of breakpoint to be grid default
  * @prop {String} settings.grid                - type of grid

stylesheets/flint/functions/lib/_instance.scss

@@ -39,5 +39,5 @@
 		)
     );
 
-    @return map-merge($flint__instances, $flint__instance);
+    @return map-merge($flint__instance, $flint__instances);
 }

stylesheets/flint/functions/lib/_map-fetch.scss

@@ -9,11 +9,21 @@
  * @return {String | False}
  */
 @function flint-map-fetch($map, $keys...) {
-	$result: $map;
 
-	@each $key in $keys {
-		$result: flint-is-map($result) and map-has-key($result, $key) and map-get($result, $key) or false;
-	}
+	// Use Ruby function if available
+	@if $flint__use-ruby-functions {
+		@return flint_ruby_map_fetch($map, $keys...);
+	} @else {
+		$result: $map;
+
+		@each $key in $keys {
+			@if $result {
+				$result: flint-is-map($result) and map-has-key($result, $key) and map-get($result, $key) or false;
+			} @else {
+				@return false;
+			}
+		}
 
-	@return $result;
+		@return $result;
+	}
 }

stylesheets/flint/functions/lib/_replace-substring.scss

@@ -13,7 +13,7 @@
 
 	// Use Ruby function if available
 	@if $flint__use-ruby-functions {
-		@return replace_substring($string, $substring, $new-substring);
+		@return flint_ruby_replace_substring($string, $substring, $new-substring);
 	} @else {
 		// Loop through length of string
 		@for $i from 1 through str-length($string) {

stylesheets/flint/functions/lib/_string-to-list.scss

@@ -3,7 +3,7 @@
  *
  * @access private
  *
- * @param {String} $string
+ * @param {String} $string       - string to perform on
  * @param {String} $find   (" ") - item to find which separates substrings
  * @param {String} $ignore (",") - removes remaining string beyond item
  *
@@ -14,7 +14,7 @@
 
 		// Use Ruby function if available
 		@if $flint__use-ruby-functions {
-			@return string_to_list($string, $find, $ignore);
+			@return flint_ruby_string_to_list($string, $find, $ignore);
 		} @else {
 			$string-list: ();
 			$space-indexes: ();

stylesheets/flint/functions/lib/_support-syntax.scss

@@ -12,13 +12,11 @@
     $syntax: to-lower-case($syntax);
 
     // Make sure syntax is supported
-    // ----
     @if function-exists("flint-support-syntax-#{$syntax}") {
 
         // Support syntax
-        // ----
-        // @warning : be sure you have created a custom function to support an unknown syntax
-        // ----
+        //
+        // WARNING: Be sure you have created a custom function to support an unknown syntax
         @return call("flint-support-syntax-#{$syntax}", $selectors);
 
     } @else {

stylesheets/flint/functions/lib/_types-in-list.scss

@@ -13,11 +13,9 @@
     @if flint-is-list($list) {
 
         // Assert types in list?
-        // ----
         @if $assert-types {
 
             // Assert length of list?
-            // ----
             @if $assert-length {
                 // Get length of list
                 $length: length($list);
@@ -28,11 +26,9 @@
                     $types: ();
 
                     // List of asserted types?
-                    // ----
                     @if flint-is-list($assert-types) {
 
                         // Make sure length of types match list
-                        // ----
                         @if length($assert-types) == $length {
 
                             // Loop over each item in list
@@ -49,13 +45,11 @@
                             }
 
                         // Lengths did not match
-                        // ----
                         } @else {
                             @return false;
                         }
 
                     // Assert a single type across list
-                    // ----
                     } @else {
                         // Assert single type
                         $type: nth($assert-types, 1);
@@ -82,7 +76,6 @@
                 }
 
             // Just assert types in list, any length
-            // ----
             } @else {
                 // Get asserted type
                 $type: $assert-types;
@@ -100,7 +93,6 @@
             }
 
         // Just assert type of first item in list
-        // ----
         } @else {
             // Get type of first item in list
             $type: type-of(nth($list, 1));
@@ -115,6 +107,7 @@
 
             @return true;
         }
+
     // Was not a list, return false
     } @else {
         @return false;

stylesheets/flint/globals/_globals.scss

@@ -1,100 +1,100 @@
-/*
+/**
  * Use development mode to silence fatal errors
  *
  * @access private
  *
- * @type {Bool}
+ * @type Bool
  */
 $flint__development-mode: false !global;
 
-/*
+/**
  * Set global variable to check if foundation has been set
  *
  * @access private
  *
- * @type {String}
+ * @type String
  */
 $flint__foundation: "non-existent" !global;
 
-/*
- * Gather all keys, breakpoints and column counts
- *
- * @access private
- *
- * @type {List}
- */
-$flint__all-keys: flint-get-all-keys() !global;
-$flint__all-breakpoints: flint-get-all-breakpoints() !global;
-$flint__all-columns: flint-get-all-columns() !global;
-
-/*
+/**
  * Keep count of all instances
  *
  * @access private
  *
- * @type {Number}
+ * @type Number
  */
 $flint__instance-count: 0 !global;
 
-/*
+/**
  * Keep map of all instances
  *
  * @access private
  *
- * @type {Map}
+ * @type Map
  */
 $flint__instances: () !global;
 
-/*
+/**
  * Font size for em calculation
  *
  * @access private
  *
- * @type {Number}
+ * @type Number
  */
 $flint__base-font-size: 16px !global;
 
-/*
+/**
+ * Detect if Ruby functions are available
+ *
+ * @access private
+ *
+ * @type Bool
+ */
+$flint__use-ruby-functions: if(flint-use-ruby-functions() == true, true, false) !global;
+
+/**
  * Global syntax support
  *
  * @access private
  *
- * @type {String}
+ * @type String
  */
 $flint__support-syntax: flint-get-value("settings", "support-syntax") !global;
 
-/*
- * Detect if Ruby functions are available
+/**
+ * Gather all keys, breakpoints and column counts
  *
  * @access private
  *
- * @type {Bool}
+ * @type List
  */
-$flint__use-ruby-functions: if(flint-use-ruby-functions() == true, true, false) !global;
+$flint__all-keys: flint-get-all-keys() !global;
+$flint__all-breakpoints: flint-get-all-breakpoints() !global;
+$flint__all-columns: flint-get-all-columns() !global;
 
-/*
+/**
  * Cache selector instance lists
  *
  * @access private
  *
- * @type {Map}
+ * @type Map
  */
 $flint__cached-instances: () !global;
 
-/*
+/**
  * Cache calculated values
  *
  * @access private
  *
- * @type {Map}
+ * @type Map
  */
 $flint__cached-values: () !global;
 
-/*
+/**
  * Cache calculation results
  *
  * @access private
  *
- * @type {Map}
+ * @type Map
  */
 $flint__cache-results: () !global;