archetype 0.0.1.pre.13 → 1.0.0.alpha.1

data/lib/archetype/sass_extensions/functions/locale.rb

@@ -11,16 +11,12 @@ module Archetype::SassExtensions::Locale
   # - {String|Boolean} the current locale or whether or not the current locale is in the test set
   #
   def locale(locales = nil)
-    locale = (Compass.configuration.locale || 'en_US').to_s
+    locale = get_locale(locale)
     # if the locales are nil, just return the current locale
-    return Sass::Script::String.new(locale) if locales.nil?
+    return identifier(locale) if locales.nil?
     locales = locales.to_a.collect{|i| i.to_s}
-    # add wild card support for language or territory
-    match = locale.match(LOCALE_PATTERN)
-    # language with wildcard territory
-    language = match[1] + '_'
-    # territory with wildcard language
-    territory = '_' + match[2]
+    # normalize the pieces of the locale
+    locale = normalize_locale(locale)
     # for each item, look it up in the alias list
     locales.each do |key|
       if a = locale_aliases[key]
@@ -28,35 +24,123 @@ module Archetype::SassExtensions::Locale
         locales.concat(a)
       end
     end
-    return Sass::Script::Bool.new(locales.include?(locale) || locales.include?(language) || locales.include?(territory))
+    return Sass::Script::Bool.new(
+      locales.include?(locale) ||
+      locales.include?("#{locale[:language]}_#{locale[:territory]}") ||
+      locales.include?(locale[:language] + '_') ||
+      locales.include?('_' + locale[:territory])
+    )
   end
+  alias_method :lang, :locale
 
   #
-  # test a list of locales against the current locale (this is now just an alias for locales(), for back-compat)
+  # returns the locale language code
   #
   # *Parameters*:
-  # - <tt>$locales</tt> {List} the list of locales to test
+  # - <tt>$locale</tt> {String} the locale to examine
+  # *Returns*:
+  # - {String|Null} the language code within the locale string
+  #
+  def locale_language(locale = nil)
+    return get_locale_piece(locale, :language)
+  end
+
+  #
+  # returns the locale territory code
+  #
+  # *Parameters*:
+  # - <tt>$locale</tt> {String} the locale to examine
+  # *Returns*:
+  # - {String|Null} the territory code within the locale string
+  #
+  def locale_territory(locale = nil)
+    return get_locale_piece(locale, :territory)
+  end
+  alias_method :locale_country, :locale_territory
+
+  #
+  # returns the locale modifier
+  #
+  # *Parameters*:
+  # - <tt>$locale</tt> {String} the locale to examine
   # *Returns*:
-  # - {Boolean} is the current locale in the list or not
+  # - {String|Null} the modifier code within the locale string
   #
-  def lang(locales)
-    return locale(locales)
+  def locale_modifier(locale = nil)
+    return get_locale_piece(locale, :modifier)
   end
 
   #
-  # get the current reading direction
+  # temporarily switch the interface locale
   #
+  # *Parameters*:
+  # - <tt>$code</tt> {String} the locale code to switch to
   # *Returns*:
-  # - {String} is the current reading direction [ltr|rtl]
+  # - {String} the previously set locale code
   #
-  def reading_direction
-    direction = Compass.configuration.reading || 'ltr'
-    return Sass::Script::String.new(direction == 'rlt' ? 'rtl' : 'ltr')
+  def switch_locale(locale)
+    previous = identifier(get_locale())
+    environment.global_env.set_var('CONFIG_LOCALE', locale)
+    return previous
   end
 
 private
 
-  LOCALE_PATTERN = /([a-z]{2})[-_]?([a-z]{2}?)/i
+  # pieces of the locale code
+  #  (1) language
+  #  (2) territory
+  #  (3) encoding (not currently used)
+  #  (4) modifier (e.g. @Cyrillic)
+  LOCALE_PATTERN = /\"?([a-z]{2})?[-_]?([a-z]{2})?(\.[^@]*)?(?:\@([^\"]+))?\"?/i
+
+  #
+  # normalizes the locale string into an object
+  #
+  # *Parameters*:
+  # - <tt>locale</tt> {String} the locale to normalize
+  # *Returns*:
+  # - {Hash} the normalized locale object
+  #
+  def normalize_locale(locale = nil)
+    match = get_locale(locale).match(LOCALE_PATTERN) || []
+    return {
+      :language   => match[1].nil? ? nil : match[1].downcase,
+      :territory  => match[2].nil? ? nil : match[2].upcase,
+      :encoding   => match[3],
+      :modifier   => match[4]
+    }
+  end
+
+  #
+  # get the locale from the given input
+  # if nil, will use either the current global locale in $CONFIG_LOCALE or the locale set on the compiler
+  #
+  # *Parameters*:
+  # - <tt>locale</tt> {Sass::String} the locale to use
+  # *Returns*:
+  # - {String} the locale string
+  #
+  def get_locale(locale = nil)
+    return (locale || environment.var('CONFIG_LOCALE') || Compass.configuration.locale || 'en_US').to_s
+  end
+
+  #
+  # returns a normalized piece of the locale
+  #
+  # *Parameters*:
+  # - <tt>locale</tt> {String} the locale to examine
+  # - <tt>piece</tt> {Symbol} the piece of the locale to extract
+  # *Returns*:
+  # - {Sass::String} a string of the locale piece requested
+  #
+  def get_locale_piece(locale = nil, piece = :language)
+    piece = normalize_locale(locale)[piece]
+    if piece.nil?
+      return null
+    else
+      return identifier(piece)
+    end
+  end
 
   #
   # provides an alias mapping for locale names
@@ -64,14 +148,9 @@ private
   # *Returns*:
   # - {Hash} a hash of aliases
   #
-  # TODO - make this easily extensible
   def locale_aliases
-    if @locale_aliases.nil?
-      a = {
-        'CJK' => ['ja_JP', 'ko_KR', 'zh_TW', 'zh_CN']
-      }
-      @locale_aliases = a
-    end
-    return @locale_aliases
+    @locale_aliases ||= {
+      'CJK' => ['ja_JP', 'ko_KR', 'zh_TW', 'zh_CN']
+    }.merge(Compass.configuration.locale_aliases || {})
   end
 end

data/lib/archetype/sass_extensions/functions/numbers.rb

@@ -1,7 +1,14 @@
 #
-# This module provides a set of Sass functions for working with Sass::Number
+# This module provides a set of Sass functions for working with Sass::Script::Value::Number
 #
 module Archetype::SassExtensions::Numbers
+
+  RESOLUTIONS = {
+    'dpi'  => 96.0,         # dots per inch
+    'dpcm' => 2.54 * 96.0,  # dots per centimeter
+    'dppx' => 1.0           # dots per pixel
+  }
+
   #
   # remove the units from a number
   #
@@ -12,8 +19,115 @@ module Archetype::SassExtensions::Numbers
   #
   def strip_units(number)
     value = 0
-    value = number.value.to_f if number.is_a?(Sass::Script::String)
-    value = number.value if number.is_a?(Sass::Script::Number)
-    return Sass::Script::Number.new(value)
+    value = number.value.to_f if number.is_a?(Sass::Script::Value::String)
+    value = number.value if number.is_a?(Sass::Script::Value::Number)
+    return number(value)
+  end
+
+  #
+  # converts a decimal number into a fraction
+  #  credit goes to Christopher Lord (https://github.com/clord/fraction)
+  #
+  # *Parameters*:
+  # - <tt>$number</tt> {Number} the number to convert
+  # *Returns*:
+  # - {String} the number represented as a fraction
+  #
+  def to_fraction(number)
+    assert_type number, :Number
+    numerator = m22 = 1
+    m12 = denominator = 0
+    x = number.value
+    while denominator * (ai = x.to_i) + m22 <= 10
+      m12, numerator = [numerator, (numerator * ai + m12).to_i]
+      m22, denominator = [denominator, (denominator * ai + m22).to_i]
+      break if (x == ai) || (x - ai).abs < 0.000000000001
+      x = 1.0 / (x - ai)
+    end
+    return identifier(numerator.to_s + '/' + denominator.to_s)
+  end
+
+  #
+  # converts any valid resolution value into a given resolution
+  #
+  # *Parameters*:
+  # - <tt>$number</tt> {Number} the resolution to convert from
+  # - <tt>$unit</tt> {String} the destination unit to convert to
+  # *Returns*:
+  # - {Number} the resolution in the destination unit
+  #
+  def resolution_to_x(number, unit = 'ratio')
+    assert_type number, :Number
+    ratio = 'ratio'
+
+    to = (unit.respond_to?(:value) ? unit.value : unit).to_s
+    from = number.unit_str.to_s
+    unitless = number.unitless?
+
+    # nothing to do if we're already in the correct format
+    return number if ((from == to) || (unitless && to == ratio))
+
+    # if we don't understand the unit...
+    if RESOLUTIONS[from].nil? and not unitless
+      # warn
+      helpers.warn("[#{Archetype.name}:resolution] don't know how to convert `#{number}` to a #{to}")
+      # and return zero
+      return number(0)
+    end
+
+    # convert it to a unitless ratio
+    number = number.value.to_f / (RESOLUTIONS[from] || 1.0)
+    # return early if we're looking for a ratio
+    return number(number) if to == ratio
+    # otherwise convert to desination unit
+    return number(number * RESOLUTIONS[to], to)
+  end
+
+  #
+  # converts any valid resolution value into a ratio
+  #
+  # *Parameters*:
+  # - <tt>$number</tt> {Number} the resolution to convert
+  # *Returns*:
+  # - {Number} the resolution as a ratio
+  #
+  def resolution_to_ratio(number)
+    return resolution_to_x(number, 'ratio')
+  end
+
+  #
+  # converts any valid resolution value into dppx (dots per pixel)
+  #
+  # *Parameters*:
+  # - <tt>$number</tt> {Number} the resolution to convert
+  # *Returns*:
+  # - {Number} the resolution as dppx
+  #
+  def resolution_to_dppx(number)
+    return resolution_to_x(number, 'dppx')
+  end
+
+  #
+  # converts any valid resolution value into dpi (dots per inch)
+  #
+  # *Parameters*:
+  # - <tt>$number</tt> {Number} the resolution to convert
+  # *Returns*:
+  # - {Number} the resolution as dpi
+  #
+  def resolution_to_dpi(number)
+    return resolution_to_x(number, 'dpi')
+  end
+
+  #
+  # converts any valid resolution value into dpcm (dots per centimeters)
+  #
+  # *Parameters*:
+  # - <tt>$number</tt> {Number} the resolution to convert
+  # *Returns*:
+  # - {Number} the resolution as dpcm
+  #
+  def resolution_to_dpcm(number)
+    return resolution_to_x(number, 'dpcm')
   end
 end

data/lib/archetype/sass_extensions/functions/strings.rb

@@ -0,0 +1,53 @@
+#
+# This module provides a set of Sass functions for working with Sass::Script::Value::String
+#
+module Archetype::SassExtensions::Strings
+  #
+  # replace a substring within a string
+  #
+  # *Parameters*:
+  # - <tt>$haystack</tt> {String} the string to search within
+  # - <tt>$needle</tt> {String} the string to match
+  # - <tt>$replacement</tt> {String} the string to substitute in
+  # - <tt>$all</tt> {Boolean} whether or not to replace all occurances
+  # *Returns*:
+  # - {String} the string with replaced value
+  #
+  def str_replace(haystack, needle, replacement, all = false)
+    method = all ? :gsub : :sub
+    str = helpers.to_str(haystack, ' ', :quotes)
+    needle = helpers.to_str(needle, ' ', :quotes)
+    replacement = helpers.to_str(replacement, ' ', :quotes)
+    str = str.method(method).call(needle, replacement)
+    return identifier(str)
+  end
+  Sass::Script::Functions.declare :str_replace, [:haystack, :needle, :replacement]
+  Sass::Script::Functions.declare :str_replace, [:haystack, :needle, :replacement, :all]
+
+  #
+  # given a string and a map of key-values, replace any {key}'s with the associated value
+  #
+  # *Parameters*:
+  # - <tt>$str</tt> {String} the string to subsititute within
+  # - <tt>$subsitutions</tt> {Map} the map of key-value pairs to substitute
+  # *Returns*:
+  # - {String} the string with substituted values
+  #
+  def str_substitute(str, subsitutions = nil)
+    return identifier('') if str == null
+    return str if subsitutions.nil?
+    subsitutions = subsitutions.to_h
+    str = helpers.to_str(str, ' ', :quotes)
+    # for each key-value pair...
+    subsitutions.each do |key, value|
+      # replace all instances of the placeholder `{key}` with the value
+      begin
+        str = str.gsub("{#{key}}", helpers.to_str(value, ' ', :quotes))
+      rescue
+      end
+    end
+    identifier(str)
+  end
+  Sass::Script::Functions.declare :str_substitute, [:string]
+  Sass::Script::Functions.declare :str_substitute, [:string, :subsitutions]
+end

data/lib/archetype/sass_extensions/functions/styleguide.rb

@@ -1,37 +1,23 @@
-require 'archetype/functions/helpers'
 require 'archetype/functions/styleguide_memoizer'
 require 'thread'
 
+%w(components constants grammar helpers resolve styles themes).each do |dep|
+  require "archetype/sass_extensions/functions/styleguide/#{dep}"
+end
+
 #
 # This is the magic of Archetype. This module provides the interfaces for constructing,
 # extending, and retrieving reusable UI components
 #
 module Archetype::SassExtensions::Styleguide
 
-  # :stopdoc:
-  INHERIT     = 'inherit'
-  STYLEGUIDE  = 'styleguide'
-  DROP        = 'drop'
-  DEFAULT     = 'default'
-  REGEX       = 'regex'
-  SPECIAL     = %w(states selectors)
-  DROPALL     = %w(all true)
-  # these are unique CSS keys that can be exploited to provide fallback functionality by providing a second value
-  # e.g color: red; color: rgba(255,0,0, 0.8);
-  FALLBACKS   = %w(background background-image background-color border border-bottom border-bottom-color border-color border-left border-left-color border-right border-right-color border-top border-top-color clip color layer-background-color outline outline-color white-space extend)
-  # these are mixins that make sense to run multiple times within a block
-  MULTIMIXINS = %w(target-browser)
-  ADDITIVES   = FALLBACKS + [DROP, INHERIT, STYLEGUIDE] + MULTIMIXINS
-  @@archetype_styleguide_mutex = Mutex.new
-  # :startdoc:
-
   #
   # interface for adding new components to the styleguide structure
   #
   # *Parameters*:
   # - <tt>$id</tt> {String} the component identifier
-  # - <tt>$data</tt> {List} the component data object
-  # - <tt>$default</tt> {List} the default data object (for extending)
+  # - <tt>$data</tt> {Map|List} the component data object
+  # - <tt>$default</tt> {Map|List} the default data object (for extending)
   # - <tt>$theme</tt> {String} the theme to insert the component into
   # - <tt>$force</tt> {Boolean} if true, forcibly insert the component
   # *Returns*:
@@ -47,7 +33,7 @@ module Archetype::SassExtensions::Styleguide
       # if we already have the component, don't create it again
       return Sass::Script::Bool.new(false) if component_exists(id, theme, nil, force)
       # otherwise add it
-      components[id] = helpers.list_to_hash(default, 1, SPECIAL, ADDITIVES).merge(helpers.list_to_hash(data, 1, SPECIAL, ADDITIVES))
+      components[id] = helpers.data_to_hash(default, 1, SPECIAL, ADDITIVES).merge(helpers.data_to_hash(data, 1, SPECIAL, ADDITIVES))
       return Sass::Script::Bool.new(true)
     end
   end
@@ -75,11 +61,11 @@ module Archetype::SassExtensions::Styleguide
       # if force was set, we'll create a random token for the name
       extension = rand(36**8).to_s(36) if force
       # convert the extension into a hash (if we don't have an extension, compose one out of its data)
-      extension = helpers.to_str(extension || data)
+      extension = helpers.to_str(extension || data).hash
       extensions = theme[:extensions]
       return Sass::Script::Bool.new(false) if component_exists(id, theme, extension, force)
       extensions.push(extension)
-      components[id] = (components[id] ||= Archetype::Hash.new).rmerge(helpers.list_to_hash(data, 1, SPECIAL, ADDITIVES))
+      components[id] = (components[id] ||= Archetype::Hash.new).rmerge(helpers.data_to_hash(data, 1, SPECIAL, ADDITIVES))
       return Sass::Script::Bool.new(true)
     end
   end
@@ -101,7 +87,7 @@ module Archetype::SassExtensions::Styleguide
   #
   def styleguide_component_exists(id, theme = nil, extension = nil, force = false)
     @@archetype_styleguide_mutex.synchronize do
-      extension = helpers.to_str(extension) if not extension.nil?
+      extension = helpers.to_str(extension).hash if not extension.nil?
       return Sass::Script::Bool.new( component_exists(id, theme, extension, force) )
     end
   end
@@ -114,381 +100,63 @@ module Archetype::SassExtensions::Styleguide
   # given a description of the component, convert it into CSS
   #
   # *Parameters*:
-  # - <tt>$description</tt> {String|List} the description of the component
+  # - <tt>$description</tt> {String|List|Map} the description of the component
   # - <tt>$theme</tt> {String} the theme to use
   # *Returns*:
-  # - {List} a key-value paired list of styles
+  # - {Map} a map of styles
   #
-  def styleguide(description, state = 'false', theme = nil)
+  def _styleguide(description, state = nil, theme = nil)
     @@archetype_styleguide_mutex.synchronize do
-      # convert it back to a Sass:List and carry on
-      return helpers.hash_to_list(get_styles(description, theme, state), 0)
+      styles = get_styles(description, theme, state)
+      styles = resolve_runtime_locale_values(styles)
+      # convert it back to a Sass:Map and carry on
+      return helpers.hash_to_map(styles)
     end
   end
 
   #
-  # output the CSS differences between components
+  # returns the CSS differences between components
   #
   # *Parameters*:
-  # - <tt>$original</tt> {String|List} the description of the original component
-  # - <tt>$other</tt> {String|List} the description of the new component
-  # - <tt>$theme</tt> {String} the theme to use
+  # - <tt>$original</tt> {String|List|Map} the description or map representation of the original component
+  # - <tt>$other</tt> {String|List|Map} the description or map representation of the new component
   # *Returns*:
   # - {List} a key-value paired list of styles
   #
-  def styleguide_diff(original, other, theme = nil)
+  def styleguide_diff(original, other)
     @@archetype_styleguide_mutex.synchronize do
-      original = get_styles(original, theme)
-      other = get_styles(other, theme)
+      # normalize our input (for back-compat)
+      original = normalize_styleguide_definition(original)
+      other = normalize_styleguide_definition(other)
+      # compute the difference
       diff = original.diff(other)
-      return helpers.hash_to_list(diff, 0)
-    end
-  end
-
-private
-  def helpers
-    @helpers ||= Archetype::Functions::Helpers
-  end
-  def memoizer
-    Archetype::Functions::StyleguideMemoizer
-  end
-
-  #
-  # given a sentence, deconstruct it into it's identifier and verbages
-  #
-  # *Parameters*:
-  # - <tt>sentence</tt> {String|List} the sentence describing the component
-  # - <tt>theme</tt> {String} the theme to use
-  # - <tt>state</tt> {String} the name of a state to return
-  # *Returns*:
-  # - {Array} an array containing the identifer, modifiers, and a token
-  #
-  def grammar(sentence, theme = nil, state = 'false')
-    theme = get_theme(theme)
-    components = theme[:components]
-    # get a list of valid ids
-    styleguideIds = components.keys
-    sentence = sentence.split if sentence.is_a? String
-    sentence = sentence.to_a
-    id = nil
-    modifiers = []
-    if not sentence.empty?
-      prefix = ''
-      order = ''
-      # these define various attributes for modifiers (e.g. `button with a shadow`)
-      extras = %w(on with without)
-      # these are things that are useless to us, so we just leave them out
-      ignore = %w(a an also the this that is was it)
-      # these are our context switches (e.g. `headline in a button`)
-      contexts = %w(in)
-      sentence.each do |item|
-        item = item.value
-        # find the ID
-        if id.nil? and styleguideIds.include?(item) and prefix.empty? and order.empty?
-          id = item
-        # if it's a `context`, we need to increase the depth and reset the prefix
-        elsif contexts.include?(item)
-          order = "#{item}-#{order}"
-          prefix = ''
-        # if it's an `extra`, we update the prefix
-        elsif extras.include?(item)
-          prefix = "#{item}-"
-        # finally, check that it's not on the ignore (useless) list. if it is, we just skip over it
-        # (maybe this should be the first thing we check?)
-        elsif not ignore.include?(item)
-          modifiers.push("#{order}#{prefix}#{item}")
-        end
-      end
-    end
-    # if there was no id, return a list of valid IDs for reporting
-    modifiers = styleguideIds if id.nil?
-    # get the list of currenty installed component extensions
-    extensions = theme[:extensions] if not id.nil?
-    # TODO - low - eoneill: make sure we always want to return unique modifiers
-    # i can't think of a case where we wouldn't want to remove dups
-    # maybe in the case where we're looking for strict keys on the lookup?
-    modifiers = modifiers.uniq
-    token = memoizer.tokenize(theme[:name], extensions, id, modifiers, state)
-    return id, modifiers, token
-  end
-
-  #
-  # interface for extracting styles in the styleguide references
-  #
-  # *Parameters*:
-  # - <tt>id</tt> {String} the component identifier
-  # - <tt>modifiers</tt> {Array} the component modifiers
-  # - <tt>strict</tt> {Boolean} is it a strict lookup?
-  # - <tt>theme</tt> {String} the theme to use
-  # - <tt>context</tt> {Hash} the context to work in
-  # *Returns*:
-  # - {Hash} a hash of the extracted styles
-  #
-  def extract_styles(id, modifiers, strict = false, theme = nil, context = nil)
-    theme = get_theme(theme)
-    context ||= theme[:components][id] || Archetype::Hash.new
-    modifiers = helpers.to_str(modifiers)
-    return Archetype::Hash.new if context.nil? or context.empty?
-    # push on the defaults first
-    out = (strict ? resolve_dependents(id, context[modifiers], theme[:name], context) : context[DEFAULT]) || Archetype::Hash.new
-    out = out.clone
-    # if it's not strict, find anything that matched
-    if not strict
-      modifiers = modifiers.split
-      context.each do |key, definition|
-        definition = [key, definition]
-        modifier = definition[0]
-        if modifier != DEFAULT
-          match = true
-          modifier = modifier.split
-          if modifier[0] == REGEX
-            # if it's a regex pattern, test if it matches
-            match = modifiers.join(' ') =~ /#{modifier[1].gsub(/\A"|"\Z/, '')}/i
-          else
-            # otherwise, if the modifier isn't in our list of modifiers, it's not valid and just move on
-            modifier.each { |i| match = false if not modifiers.include?(i) }
-          end
-          # if it matched, process it
-          if match
-            tmp = resolve_dependents(id, definition[1], theme[:name], nil, out)
-            out, tmp = post_resolve_drops(out, tmp)
-            out = out.rmerge(tmp)
-          end
-        end
-      end
-    end
-    # recompose the special keys and extract any nested/inherited styles
-    # this lets us define special states and elements
-    SPECIAL.each do |special_key|
-      if out.is_a? Hash
-        special = out[special_key] || Archetype::Hash.new
-        if special == 'nil'
-          out[special_key] = Archetype::Hash.new
-        else
-          tmp = Archetype::Hash.new
-          special.each { |key, value| tmp[key] = extract_styles(key, key, true, theme[:name], special) }
-          out[special_key] = tmp if not tmp.empty?
-        end
-      end
-    end
-    # check for nested styleguides
-    styleguide = out[STYLEGUIDE]
-    if not (styleguide.nil? or styleguide.empty?)
-      styles = get_styles(styleguide, theme[:name])
-      out.delete(STYLEGUIDE)
-      out = styles.rmerge(out)
-    end
-    return out
-  end
-
-  #
-  # given two objects, resolve the chain of dropped styles
-  #  this runs after having already resolved the dropped styles and merged
-  #
-  # *Parameters*:
-  # - <tt>obj</tt> {Hash} the source object
-  # - <tt>merger</tt> {Hash} the object to be merged in
-  # *Returns*:
-  # - {Array.<Hash>} the resulting `obj` and `merger` objects
-  #
-  def post_resolve_drops(obj, merger)
-    return [obj, merger] if obj.nil? or merger.nil?
-    drop = merger[DROP]
-    keys = obj.keys
-    if not drop.nil?
-      drop.to_a.each do |key|
-        key = helpers.to_str(key)
-        obj.delete(key) if not SPECIAL.include?(key)
-      end
-      merger.delete(DROP)
-    else
+      # convert the individual messages in a comparison
+      original_message = helpers.get_meta_message(original).sub(MESSAGE_PREFIX, '').sub(MESSAGE_SUFFIX, '')
+      other_message = helpers.get_meta_message(other).sub(MESSAGE_PREFIX, '').sub(MESSAGE_SUFFIX, '')
+      diff = helpers.add_meta_message(diff, "#{MESSAGE_PREFIX}#{original_message}` vs `#{other_message}#{MESSAGE_SUFFIX}")
+      # and return it as a map
+      return helpers.hash_to_map(diff)
     end
-    SPECIAL.each do |special|
-      if obj[special].is_a?(Hash) and merger[special].is_a?(Hash)
-        obj[special], merger[special] = post_resolve_drops(obj[special], merger[special])
-      end
-    end
-    return [obj, merger]
   end
 
   #
-  # given two objects, resolve the chain of dropped styles
+  # given a styleguide definition or object, extract specified styles
   #
   # *Parameters*:
-  # - <tt>value</tt> {Hash} the source object
-  # - <tt>obj</tt> {Hash} the object to be merged in
-  # - <tt>is_special</tt> {Boolean} whether this is from a SPECIAL branch of a Hash
+  # - <tt>$definition</tt> {String|List} the description of the component
+  # - <tt>$properties</tt> {String|List} the properties to extract the derived styles for
+  # - <tt>$format</tt> {String} the format to return the results in [auto|map|list]
+  # - <tt>$strict</tt> {Boolean} if true, will only return an exact match, and not try to extrapolate the value
   # *Returns*:
-  # - {Array.<Hash>} the resulting value
+  # - {List|Map|*} either a list/map of the values or the individual value itself
   #
-  def resolve_drops(value, obj, is_special = false)
-    return value if not (value.is_a?(Hash) and obj.is_a?(Hash))
-    keys = obj.keys
-    drop = value[DROP]
-    if not drop.nil?
-      tmp = Archetype::Hash.new
-      if DROPALL.include?(helpers.to_str(drop))
-        if not keys.nil?
-          keys.each do |key|
-            if SPECIAL.include?(key)
-              if not (obj[key].nil? or obj[key].empty?)
-                tmp[key] = Archetype::Hash.new
-                tmp[key][DROP] = obj[key].keys
-              end
-            else
-              tmp[key] = 'nil'
-            end
-          end
-        end
-      else
-        drop.to_a.each do |key|
-          key = helpers.to_str(key)
-          if SPECIAL.include?(key)
-            if not (obj[key].nil? or obj[key].empty?)
-              tmp[key] = Archetype::Hash.new
-              tmp[key][DROP] = obj[key].keys
-            end
-          else
-            tmp[key] = 'nil'
-          end
-        end
-      end
-      value.delete(DROP) if not is_special
-      value = tmp.rmerge(value)
-    end
-    value.each do |key|
-      value[key] = resolve_drops(value[key], obj[key], key, SPECIAL.include?(key)) if not value[key].nil?
-    end
-    return value
-  end
-
-  #
-  # resolve any dependent references from the component
-  #
-  # *Parameters*:
-  # - <tt>id</tt> {String} the component identifier
-  # - <tt>value</tt> {Hash} the current value
-  # - <tt>theme</tt> {String} the theme to use
-  # - <tt>context</tt> {Hash} the context to work in
-  # - <tt>keys</tt> {Array} list of the external keys
-  # *Returns*:
-  # - {Hash} a hash of the resolved styles
-  #
-  def resolve_dependents(id, value, theme = nil, context = nil, obj = nil)
-    # we have to create a clone here as the passed in value is volatile and we're performing destructive changes
-    value = value.clone
-    # check that we're dealing with a hash
-    if value.is_a?(Hash)
-      # check for dropped styles
-      value = resolve_drops(value, obj)
-
-      # check for inheritance
-      inherit = value[INHERIT]
-      if not (inherit.nil? or inherit.empty?)
-        # create a temporary object and extract the nested styles
-        tmp = Archetype::Hash.new
-        inherit.each { |related| tmp = tmp.rmerge(extract_styles(id, related, true, theme, context)) }
-        # remove the inheritance key and update the styles
-        value.delete(INHERIT)
-        value = tmp.rmerge(value)
-      end
-    end
-    # return whatever we got
-    return value
-  end
-
-  #
-  # keep a registry of styleguide themes
-  #
-  # *Parameters*:
-  # - <tt>theme</tt> {String} the theme to use
-  # *Returns*:
-  # - {Hash} the theme
-  #
-  def get_theme(theme)
-    theme_name = helpers.to_str(theme || 'archetype')
-    @@styleguide_themes ||= {}
-    themes = @@styleguide_themes[theme_name] ||= {}
-    cleanup_old_themes!(themes, options[:css_filename]) if rand < 0.333  # cleanup 1/3 of the time.
-    theme = themes[options[:css_filename]] ||= {}
-    theme[:name] ||= theme_name
-    theme[:components] ||= {}
-    theme[:extensions] ||= []
-    return theme
-  end
-
-  def cleanup_old_themes!(themes, css_filename)
-    themes.keys.each do |key|
-      if key != css_filename
-        themes.delete(key)
-      end
-    end
-    nil
-  end
-
-  #
-  # driver method for converting a sentence into a list of styles
-  #
-  # *Parameters*:
-  # - <tt>description</tt> {String|List} the description of the component
-  # - <tt>theme</tt> {String} the theme to use
-  # - <tt>state</tt> {String} the name of a state to return
-  # *Returns*:
-  # - {Hash} the styles
-  #
-  def get_styles(description, theme = nil, state = 'false')
-    state = helpers.to_str(state)
-    styles = Archetype::Hash.new
-    description.to_a.each do |sentence|
-      # get the grammar from the sentence
-      id, modifiers, token = grammar(sentence, theme, state)
-      if id
-        # check memoizer
-        memoized = memoizer.fetch(theme, token)
-        if memoized
-          styles = styles.rmerge(memoized)
-        else
-          # fetch additional styles
-          extracted = extract_styles(id, modifiers, false, theme)
-          # we can delete anything that had a value of `nil` as we won't be outputting those
-          extracted.delete_if { |k,v| helpers.is_value(v, :nil) }
-          styles = styles.rmerge(extracted)
-          memoizer.add(theme, token, extracted)
-        end
-      elsif not helpers.is_value(sentence, :nil)
-        helpers.logger.record(:warning, "[archetype:styleguide:missing_identifier] `#{helpers.to_str(sentence)}` does not contain an identifier. please specify one of: #{modifiers.sort.join(', ')}")
-      end
-    end
-    # now that we've collected all of our styles, if we requested a single state, merge that state upstream
-    if state != 'false' and styles['states']
-      state = styles['states'][state]
-      # remove any nested/special keys
-      SPECIAL.each do |special|
-        styles.delete(special)
-      end
-      styles = styles.merge(state) if not (state.nil? or state.empty?)
+  def styleguide_derived_style(definition, properties = [], format = 'auto', strict = false)
+    @@archetype_styleguide_mutex.synchronize do
+      # normalize our input
+      definition = normalize_styleguide_definition(definition)
+      # get the computed styles
+      return derived_style(definition, properties, format, strict)
     end
-    return styles
   end
 
-  #
-  # check whether or not a component (or a component extension) has already been defined
-  #
-  # *Parameters*:
-  # - <tt>$id</tt> {String} the component identifier
-  # - <tt>$data</tt> {List} the component data object
-  # - <tt>$theme</tt> {String} the theme to insert the component into
-  # - <tt>$extension</tt> {String} the name of the extension
-  # - <tt>$force</tt> {Boolean} if true, forcibly extend the component
-  # *Returns*:
-  # - {Boolean} whether or not the component/extension exists
-  #
-  def component_exists(id, theme = nil, extension = nil, force = false)
-    status = false
-    theme = get_theme(theme) if not theme.is_a? Hash
-    id = helpers.to_str(id)
-    # determine the status of the component
-    status = (extension.nil?) ? (not theme[:components][id].nil?) : theme[:extensions].include?(extension)
-    return (status and not force and Compass.configuration.memoize)
-  end
 end