core.scss

/*!  Force output of above line by adding a unicode character. ♫ */

@import "sass-import-once/sass-import-once";
@import "compass-breakpoint/stylesheets/breakpoint";

$settings: () !default;
$debug: false !default;

// Internal caching get sass iteration be slow!
$__a__cache-enabled: true !default;
$__a__map-cache: () !default;


// TODO(xzyfer): split this up into small files.
// This is currently blocked performance issues with sass' @import
// https://github.com/nex3/sass/issues/1019#issuecomment-29128022

// // ==========================================================================
// // Internal caching API
// // ==========================================================================

// @function cache-get($key) {
//     @if $debug {
//         @debug("cache get #{$key} as");
//         @debug(map-get($__a__map-cache, $key));
//     }

//     @return map-get($__a__map-cache, $key);
// }

// @function cache-set($key, $value) {
//     $__a__map-cache: map-merge($__a__map-cache, ($key: $value)) !global;

//     @if $debug {
//         @debug("cache set #{$key} to");
//         @debug($value);
//     }

//     @return $__a__map-cache;
// }

// // Clears the internal cache. If $key is supplied only that key is cleared
// // Returned the new state of the cache
// // -----------------------------------------------------------------------------
// // @param $key [String] : an optional key to clear
// // -----------------------------------------------------------------------------
// // @return [Map]
// @function cache-clean($key:null) {
//     @if $key {
//         $__a__map-cache: map-merge($__a__map-cache, ($key: null)) !global;
//     } @else {
//         $__a__map-cache: () !global;
//     }

//     @return $__a__map-cache;
// }


// // Returns whether the internal cache is enabled or not
// // -----------------------------------------------------------------------------
// // @return [Bool] true if the cache is enabled, otherwise false
// @function cache-status() {
//     @return $__a__cache-enabled;
// }


// // Disables the internal cache
// // -----------------------------------------------------------------------------
// // @return [Bool] true if the cache is enabled, otherwise false
// @function cache-disable() {
//     $__a__cache-enabled: false !global;
//     @return cache-status();
// }


// // Disables the internal cache
// // -----------------------------------------------------------------------------
// // @return [Bool] true if the cache is enabled, otherwise false
// @function cache-enable() {
//     $__a__cache-enabled: true !global;
//     @return cache-status();
// }


// ==========================================================================
// Debug API
// ==========================================================================

// @function timer($label) {
//     @if function-exists("current-time") {
//         $time: current-time("%H:%M:%S.%L");
//         @debug($label);
//         @debug($time);
//         @debug("--------------------");
//         @return $time;
//     }

//     @return 0;
// }


// ==========================================================================
// Lazy API
// ==========================================================================

// Serializes function metadata so that it can be evaluated by `get()`.
// The primary use cause for this is to evaluate aliased values in realtime.
// -----------------------------------------------------------------------------
// @param $func [String] : the name of the function to call
// @param $$args [Map] : a map of named arguments to pass to $func
// -----------------------------------------------------------------------------
// @return [Map]
@function lazy($func, $args:()) {
    @return (
        "_type": "function",
        "_func": $func,
        "_args": $args,
    );
}


// Is $map a serialized lazy?
// -----------------------------------------------------------------------------
// @param $map [Map] : $map
// -----------------------------------------------------------------------------
// @return [Bool]
@function is-lazy($map) {
    @return type-of($map) == map
        and map-has-key($map, "_type")
        and map-get($map, "_type") == "function";
}


// Execute a lazy function after resolving any aliases in it's arguments
// -----------------------------------------------------------------------------
// @param $map [Map] : $map
// -----------------------------------------------------------------------------
// @return [Literal]
@function exec-lazy($map) {
    @if is-lazy($map) == false {
        @return $map;
    }

    $name: map-get($map, "_func");
    $args: resolve-aliases(map-get($map, "_args"), $settings);

    // allow lazy's as parameters to lazy's
    @each $k, $v in $args {
        @if is-lazy($v) {
            $v: exec-lazy($v);
        }
        $args: map-merge($args, ($k: $v));
    }

    @return call($name, $args...);
}


// ==========================================================================
// Settings API
// ==========================================================================

// Gets $key's value from the core $settings map
// -----------------------------------------------------------------------------
// @param $key [String] : flattened key to lookup
// @param $_root [Map] : for internal use only
// -----------------------------------------------------------------------------
// @return [Literal]
@function get($key, $_root:null) {
    // $_root won't exist the first time around, default it to $settings
    @if $_root == null {
        $_root: $settings;
    }

    @while (str-index($key, "/") or 0) > 0 {
        $child-key: str-slice($key, 1, str-index($key, "/") - 1);
        $key: str-slice($key, str-index($key, "/") + 1);
        $_root: map-get($_root, $child-key) or ();
    }

    $value: map-get($_root, $key);

    @if is-lazy($value) {
        @return exec-lazy($value);
    } @else if type-of($value) == map {
        @return resolve-aliases($value, $settings);
    } @else {
        @return resolve-alias($value);
    };
}


// Sets $key's to $value in the core $settings map if it currently has no value
// If $key was a string it's new value is returned
// If $key was a map the core $settings map is returned
// -----------------------------------------------------------------------------
// @param $key [String|Map] : key to lookup or map to merge with $settings
// @param $value [Literal] : value to set $key to it was a string
// -----------------------------------------------------------------------------
// @return [Literal]
@function set-default($key, $value:null) {
    @if type-of($key) == map {
        // Reverse the merge order so we don't over write anything
        $settings: _set($settings, null, $key) !global;
        $value: $settings;
    } @else if not get($key) {
        $settings: _set($key, $value, $settings);
        $value: get($key);
    } @else {
        // $key exists in $settings, do nothing!
        $value: get($key);
    }

    @return $value;
}


// Sets $key's to $value in the core $settings map
// If $key was a string it's new value is returned
// If $key was not a string the core $settings map is returned
// -----------------------------------------------------------------------------
// @param $key [String|Map] : key to lookup or map to merge with $settings
// @param $value [Literal] : value to set $key to it was a string
// -----------------------------------------------------------------------------
// @return [Literal|Null]
@function set($key, $value:null) {
    $settings: _set($key, $value, $settings) !global;

    @if type-of($key) == map or type-of($key) == list {
        @return $settings;
    }

    @return get($key);
}


// Sets $key's to $value in the core $settings map
// Returning the value of $key after it's been updated. If $key was a map the
// root node is returned
// -----------------------------------------------------------------------------
// @param $key [String|Map] : key to lookup or map to merge with $settings
// @param $value [Literal] : value to set $key to it was a string
// @param $_root [Map] : for internal use only
// -----------------------------------------------------------------------------
// @return [Literal]
@function _set($key, $value:null, $_root:null) {
    // Clear out caches, or bad things will happen
    @if cache-status() and cache-clean() {}

    // $_root won't exist in recursive calls if $key is a new branch
    @if $_root == null {
        $_root: ($key: ());
    }

    // If $key is a map just merge it and move on
    //
    // 1: this allows use to use () as the default $settings value
    @if type-of($key) == map or
        type-of($key) == list // 1
    {
        // $ret: ();
        // @each $k, $v in $_root {
        //     $ret: map-merge($ret, ($k: map-get($key, $k) or $v));
        // }
        @return map-merge-recursive($_root, $key);
    }

    @if (str-index($key, "/") or 0) > 0 {
        // Determin the $new key for the recursion
        $child-key: str-slice($key, str-index($key, "/") + 1);

        // Override the original $key and $value we can have one @return
        $key: str-slice($key, 1, str-index($key, "/") - 1);
        $value: _set($child-key, $value, map-get($_root, $key))
    }

    @return map-merge($_root, ($key: $value));
}


// ==========================================================================
// List functions
// ==========================================================================

// All we can do is guess. If $name looks like an alias and smells like an
// alias, it could be an alias.
// -----------------------------------------------------------------------------
// @param $name [List|String] : $name
// -----------------------------------------------------------------------------
// @return [Bool]
@function looks-like-an-alias($name) {
    @return type-of($name) == string and (str-index($name, "/") or 0) > 1;
}

// Takes $name and resolves it's alias against $settings.
// If name is a list each item is resolved individually.
// Returns either the resolved values or $name
// -----------------------------------------------------------------------------
// @param $name [List|String] : $name
// -----------------------------------------------------------------------------
// @return [Literal]
@function resolve-alias($name) {
    @if type-of($name) == list {
        $ret:();

        @each $item in $name {
            $ret: append($ret, resolve-alias($item), list-separator($name));
        }

        @return $ret;
    }

    $value: $name;
    $break: false; // Emulate break statements

    @while looks-like-an-alias($value) and $break == false {
        $key: $value;
        $_root: $settings;

        @while (str-index($key, "/") or 0) > 0 {
            $child-key: str-slice($key, 1, str-index($key, "/") - 1);
            $key: str-slice($key, str-index($key, "/") + 1);
            $_root: map-get($_root, $child-key) or ();
        }

        @if length($_root) > 0 {
            $value: map-get($_root, $key);
        } @else {
            $break: true;
        }
    }

    @return if(is-lazy($value), exec-lazy($value), $value);
}


// Takes a one dimensional $map and returns a new map with aliases resolved
// -----------------------------------------------------------------------------
// @param $map [Map] : map
// @param $extras [Map] : an external map to resolve aliases against
// -----------------------------------------------------------------------------
// @return [Map]
@function resolve-aliases($map, $extras:()) {
    $ret: ();
    @each $name, $value in $map {
        // Looks like an alias, try to resolve it, default to $value
        @if type-of($value) == string {
            $value: lookup($ret, $value, lookup($extras, $value, $value));
            $ret: map-merge($ret, ($name: $value));
        } @else
        // Recursion yo!
        if type-of($value) == map {
            $value: resolve-aliases($value, $extras);
            $ret: map-merge($ret, ($name: $value));
        } @else {
            $ret: map-merge($ret, ($name: $value));
        }
    }

    @return $ret;
}


// Takes a one dimensional $map and returns a new map with aliases resolved
// -----------------------------------------------------------------------------
// @param $map [Map] : map
// @param $key [String] : key to lookup in map
// @param $default [Value] : the default value to return if key is not found
// -----------------------------------------------------------------------------
// @return [Literal]
@function lookup($map, $key, $default:null) {
    @if type-of($map) != map {
        @return $default;
    }

    $ret: get($key, $map);
    @if $ret {
        @return $ret;
    }

    @return $default;
}


// Joins all elements of single dimensional $list with $glue
// -------------------------------------------------------------------------------
// @param $list [List] : list
// @param $glue [String] : value to use as a join string
// -------------------------------------------------------------------------------
// @return [String]
@function implode($list, $glue:",") {
    @if length($list) == 1 {
        @return $list;
    }

    $ret: unquote("");
    @for $i from 1 through length($list) {
        $ret: if($ret == "", $ret, $ret + $glue) + nth($list, $i);
    }

    @return $ret;
}


// Joins all elements of single dimensional $list with $glue
// -------------------------------------------------------------------------------
// @param $list [List] : list
// @param $glue [String] : value to use as a join string
// -------------------------------------------------------------------------------
// @return [String]
@function map-merge-recursive($map1, $map2) {
    $ret: $map1;

    @each $key, $value in $map2 {
        @if map-get($ret, $key) != null and type-of($value) == map and type-of(map-get($ret, $key)) == map {
            // Keys that start with `!` override rather than merge
            @if str-index($key, "!") == null {
                $value: map-merge-recursive(map-get($ret, $key), $value);
            }
        }

        // Keys that start with `!` override rather than merge
        @if str-index($key, "!") == 1 {
            // Remove the `!` from $key
            $key: str-slice($key, 2);
            $ret: map-remove($ret, $key);
        }

        $ret: map-merge($ret, ($key: $value));
    }

    @return $ret;
}