bem-constructor 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8d21417bbbbf72744f4f58dbf75f61313f4f0c0f
+  data.tar.gz: 4e6598835ffaaac7ed06cb3cfea6d8b9f14b0e7c
+SHA512:
+  metadata.gz: b6ea8f0194709514cf397580c63858d5c5a4ea54e2e2d9f3db9de0f049db8dcf1df6399267aa19a96020d6b022a16aafbe9da568d45748bf04fc5c2a0e9e988d
+  data.tar.gz: 6e1f86e490a5d18ece7bfc4d9f68f9402b42de7f6595220fb0623f66daac14350a7c09db82f1ebceb2458c241f894d7b6063dc7bc9f512f0c223c519a382ddb5

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+* Initial release

data/README.md

@@ -0,0 +1,282 @@
+# BEM Constructor
+
+BEM Constructor is a Sass library for building immutable and namespaced BEM-style CSS objects.
+
+By enforcing a consistent and programatic way of defining objects (blocks, elements and modifiers) it ensures a more structured, robust and secure object codebase that is easy to understand and maintain. Objects defined using the constructor are impossible to modify and reassign by mistake or omission.
+
+Jump to [🍔 The Burger Example™](#example) to see the mixins in action.
+
+----
+
+## Key ideas
+
+The key ideas behind this library are well explained by Harry Roberts in his articles [Immutable CSS](http://csswizardry.com/2015/03/immutable-css/), [More Transparent UI Code with Namespaces](http://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/) and [MindBEMding – getting your head ’round BEM syntax](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/),
+
+### 1. Immutability
+
+Some CSS objects in your project shouldn't be able to change (mutate). They have a very specific role and you need to make sure they're not reassigned somewhere else in your codebase. In order to ensure immutability you'll need three things: a way of defining those objects, a way of recognising them and a way to guarantee you won't be able to modify them later on. By constructing objects programatically you can be confident that they are assigned once and just once.
+
+### 2. Namespacing
+
+Objects have a clear function. Whethere they are components, utilities o dirty hacks, we need a consistent way of telling them apart. By namespacing objects, our UI code becomes more transparent and understandable.  BEM Constructor supports the following object types:
+
+- Objects
+- Components
+- Utilities
+- Themes
+- States
+- Scopes
+- Hacks
+
+Read [Harry's post on namespaces](http://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/) to get a deep look at why and how they are used.
+
+
+### 3. BEM structure
+
+BEM objects are composed of a block and any number of elements and/or modifiers. Using the BEM syntax for naming classes you'll produce structured code that helps you and other developers understand at a glance the relationship between those classes. The BEM constructor takes care of generating bem-compliant selectors.
+
+----
+
+## Installation
+
+There are 3 ways of installing BEM Constructor:
+
+### Download
+
+Download the Sass files in [stylesheets/](/stylesheets/) and place them in your Sass directory.
+
+### Bower
+
+Run the following command:
+
+    bower install --save-dev bem-constructor
+
+### Compass extension
+
+1. `gem install bem-constructor`
+2. Add `require 'bem-constructor'` to your `config.rb`
+
+----
+
+## Usage
+
+Import it into your main stylesheet:
+
+    @import 'bem-constructor';
+
+### block($name, $type)
+
+Constructs a new block element of a given type. `$type` being one of: `'object'`, `'component'` or `'utility'`.
+
+    @include block($name, $type) { ... }
+
+
+#### object($name)
+
+A shortcut for `block($name, $type: 'object')`
+
+#### component($name)
+
+A shortcut for `block($name, $type: 'component')`
+
+#### utility($name)
+
+A shortcut for `block($name, $type: 'utility')`
+
+
+### element($name...)
+
+Creates a new element of the parent block. It should always be nested within a block constructor. You can create multiple elements at once by passing a comma separated list (Arglist) of element names.
+
+    @include element($name...) { ... }
+
+
+### modifier($name...)
+
+Creates a new modifier of the parent block or element. Should always be nested within a block or element constructor. You can declare multiple modifiers at once by passing a comma separated list (Arglist) of modifier names.
+
+    @include modifier($name...) { ... }
+
+
+### modifies-element($modified-elements...)
+
+When declaring a block modifier, a state you may need to target and modify some of the block elements too. Use the following mixin to scope the ruleset to those elements.
+
+    @include modifies-element($modified-elements...) { ... }
+
+
+### theme($themes...)
+
+Style your objects given a parent theme class.
+
+    @include theme($themes...) { ... }
+
+### state($states...)
+
+Modifies objects by appending a state class
+
+    @include state($states...) { ... }
+
+### hack()
+
+Signals that the following code is a hack.
+
+    @include hack() { ... }
+
+
+### scope($name)
+
+Creates a new scope
+
+Scopes allow you to isolate code you don't have control over.
+
+    @include scope($name) { ... }
+
+
+----
+
+## Options
+
+### Namespaces
+
+Switch namespaces on/off by setting the following variable:
+
+	$bem-use-namespaces: false; // defaults to true
+
+Override the default block namespaces:
+
+	$bem-block-namespaces: (
+	    'object': 'obj',     // defaults to 'o'
+	    'component': 'comp', // defaults to 'c'
+	    'utility': 'helper', // defaults to 'u'
+	);
+
+Override the default theme namespace:
+
+	$bem-theme-namespace: 'theme'; // defaults to 't'
+
+Override the default state namespace:
+
+	$bem-state-namespace: 'has'; // defaults to 'is'
+
+Override the default hack namespace:
+
+	$bem-hack-namespace: 'it-wasnt-me-'; // defaults to '_'
+
+
+
+### BEM separators
+
+By default BEM Constructor uses the following BEM convention:
+- Two underscores (__) for elements
+- Two hyphens for modifiers (--).
+
+You can customize them to whatever fits you needs:
+
+	$bem-element-separator: '-'; // Defaults to '__'
+
+	$bem-modifier-separator: '-_-_'; // Defaults to '--'
+
+
+
+----
+
+##<a name="example"></a> 🍔 The Burger Example™
+
+
+*Disclaimer: the following Sass code may not compile into a real burger.*
+
+```` scss
+
+    @include object('burger') {
+        texture: juicy;
+
+        @include element('lettuce', 'tomato') {
+            quality: fresh;
+        }
+
+        @include element('cheese') {
+            type: gouda;
+
+            @include modifier('parmigiano') {
+                type: parmigiano;
+            }
+        }
+
+        @include element('extra-topping') {
+            ingredient: bacon;
+        }
+
+        @include element('meat') {
+            type: beef;
+        }
+
+        @include modifier('veggie') {
+            texture: smooth;
+
+            @include modifies-element('meat') {
+                type: lentils;
+            }
+
+            @include modifies-element('extra-topping') {
+                ingredient: avocado;
+
+                @include hack() {
+                    ingredient: bacon;
+                }
+            }
+        }
+
+        @include theme('mexican') {
+            spicy: hell-yeah;
+        }
+
+        @include state('cold') {
+            taste: terrible;
+        }
+    }
+
+The compiled CSS:
+
+```` css
+
+    /* The main Burger object */
+    .o-burger { texture: juicy; }
+
+    /* lettuce and Tomato elements */
+    .o-burger__lettuce, .o-burger__tomato { quality: fresh; }
+
+    /* Cheese element */
+    .o-burger__cheese { type: gouda; }
+
+    /* Cheese modifier */
+    .o-burger__cheese--parmigiano { type: parmigiano; }
+
+    /* Extra topping element */
+    .o-burger__extra-topping { ingredient: bacon; }
+
+    /* Meat element */
+    .o-burger__meat { type: beef; }
+
+    /* Veggie Burger block modifier */
+    .o-burger--veggie { texture: smooth; }
+
+    /* Veggie Burger block modifier modifies the Meat element too */
+    .o-burger--veggie .o-burger__meat { type: lentils; }
+
+    /* Veggie Burger block modifier modifies the Extra Topping element too */
+    .o-burger--veggie .o-burger__extra-topping { ingredient: avocado; }
+
+    /* But we are hackers and couldn't resist adding some Bacon back */
+    ._o-burger--veggie .o-burger__extra-topping { ingredient: bacon; }
+
+    /* When the party Theme is Mexican, we make everything spicy */
+    .t-mexican .o-burger { spicy: hell-yeah; }
+
+    /* And we're all sad when the burge Is Cold */
+    .o-burger.is-cold { taste: terrible; }
+
+
+## This is overkill, who is this for?
+
+If constructing objects programatically seems too verbose or abstract to you that's perfectly OK. This tool is not for everybody. However if you need to enforce a strict way of writing BEM objects in your project, want to make sure they won't mutate and thus produce more secure CSS, then this tool might help you.

data/lib/bem-constructor.rb

@@ -0,0 +1,8 @@
+require 'compass'
+extension_path = File.expand_path(File.join(File.dirname(__FILE__), ".."))
+Compass::Frameworks.register('bem-constructor', :path => extension_path)
+
+module QuantityQueries
+  VERSION = "0.1"
+  DATE = "2015-03-24"
+end

data/stylesheets/_bem-constructor.scss

@@ -0,0 +1,37 @@
+// -----------------------------------------------------------------------------
+// BEM constructor
+// -----------------------------------------------------------------------------
+// Table of contents
+// 1. Default settings
+// 2. Imports
+
+// -----------------------------------------------------------------------------
+// 1. Default settings
+// -----------------------------------------------------------------------------
+
+/// Use namespaced class names
+/// @public
+$bem-use-namespaces: true !default;
+
+/// Bem style element separator
+/// @public
+$bem-element-separator: '__' !default;
+
+/// Bem style modifier separator
+/// @public
+$bem-modifier-separator: '--' !default;
+
+// -----------------------------------------------------------------------------
+// 2. Imports
+// -----------------------------------------------------------------------------
+
+@import 'logger';
+@import 'error-checks';
+@import 'block';
+@import 'element';
+@import 'modifier';
+@import 'modifies-element';
+@import 'scope';
+@import 'theme';
+@import 'state';
+@import 'hack';

data/stylesheets/_block.scss

@@ -0,0 +1,91 @@
+// -----------------------------------------------------------------------------
+// Block constructor
+// -----------------------------------------------------------------------------
+
+/// Set namespaces for each block type
+/// @public
+
+$bem-block-namespaces: (
+    'utility': 'u',
+    'object': 'o',
+    'component': 'c',
+) !default;
+
+/// Initializes a new block object
+/// @private
+/// @param {String} $block  - Name for the new block
+/// @param {String} $type   - Block type: (utility, object or component)
+/// @returns The final selector for the new block object
+
+@function _block($name, $type) {
+
+    // Log new block
+    $new-block: _bem-log-block($name);
+
+    // Error check
+    $outside-check: should-not-be-called-within('scope', 'block');
+
+    // Set namespace
+    $namespace: '';
+
+    @if $bem-use-namespaces {
+        @if not map-has-key($bem-block-namespaces, $type) {
+            @error '`#{$type}` is not a valid `$type` for `block()`';
+        }
+        $namespace: map-get($bem-block-namespaces, $type) + '-';
+    }
+
+    $selector: '.' + $namespace + $name;
+    $set-current: set-current-context('block', $name, $selector);
+
+    @return $selector;
+}
+
+
+/// Creates a block object with the given type
+/// @param {String} $block  - Name for the new block
+/// @param {String} $type   - Block type: (utility, object or component)
+
+@mixin block($name, $type) {
+
+    // Write block selector
+    @at-root #{_block($name, $type)} {
+        @content;
+    }
+
+    // Clear $_bem-current-context block after creation
+    $unset-current: unset-current-context('block');
+}
+
+
+// -----------------------------------------------------------------------------
+// 2. Utility alias
+// -----------------------------------------------------------------------------
+
+@mixin utility($name) {
+    @include block($name, 'utility') {
+        @content;
+    }
+}
+
+
+// -----------------------------------------------------------------------------
+// 3. Object alias
+// -----------------------------------------------------------------------------
+
+@mixin object($name) {
+  @include block($name, 'object') {
+    @content;
+  }
+}
+
+
+// -----------------------------------------------------------------------------
+// 4. Component alias
+// -----------------------------------------------------------------------------
+
+@mixin component($name) {
+  @include block($name, 'component') {
+    @content;
+  }
+}

data/stylesheets/_element.scss

@@ -0,0 +1,43 @@
+// ----------------------------------------------------------------------
+// Element constructor
+// ----------------------------------------------------------------------
+
+/// Initializes a new element for the current block
+/// @private
+/// @param {String | Arglist} $elements - List of new element names
+/// @returns The final selector for the new element(s)
+
+@function _element($elements...) {
+
+    // Log new element(s)
+    $new-element: _bem-log-element($elements...);
+
+    // Error checks
+    $inside-check: should-be-called-within('block');
+    $outside-check: should-not-be-called-within('modifier', 'state', 'element');
+
+    $selector: ();
+
+    @each $element in $elements {
+        $e: #{&}#{$bem-element-separator}#{$element};
+        $selector: append($selector, $e, 'comma');
+    }
+
+    $set-current: set-current-context('element', $elements, $selector);
+
+    @return $selector;
+}
+
+
+/// Creates new element(s)
+/// @param {String | Arglist} $elements  - Name of the new element(s)
+
+@mixin element($elements...) {
+
+    @at-root #{_element($elements...)} {
+        @content;
+    }
+
+    // Clear $_bem-current-context element after creation
+    $unset-current: unset-current-context('element');
+}

data/stylesheets/_error-checks.scss

@@ -0,0 +1,50 @@
+// -----------------------------------------------------------------------------
+// Error checks
+// -----------------------------------------------------------------------------
+// Table of contents:
+// 1. Within
+// 2. Outside
+
+// -----------------------------------------------------------------------------
+// 1. Within
+// -----------------------------------------------------------------------------
+
+/// Checks that it's being created within all of the passed $objs...
+@function _should-be-called-within($objs...) {
+
+    $found: false;
+
+    @each $obj in $objs {
+        @if map-get($_bem-current-context, $obj) != null {
+            $found: true;
+        }
+    }
+
+    @if not $found {
+        @error 'It should be called within #{inspect($objs)}';
+    }
+
+    @return true;
+}
+
+
+// -----------------------------------------------------------------------------
+// 2. Outside
+// -----------------------------------------------------------------------------
+
+/// Checks that it's being created outside all of the passed $objs...
+@function _should-not-be-called-within($objs...) {
+
+  $found: false;
+
+  @each $obj in $objs {
+    @if map-get($_bem-current-context, $obj) != null {
+      $found: true;
+    }
+  }
+  @if $found {
+    @error 'It should not be called within #{inspect($objs)}';
+  }
+
+  @return true;
+}

data/stylesheets/_hack.scss

@@ -0,0 +1,38 @@
+// -----------------------------------------------------------------------------
+// 11. Hack constructor
+// -----------------------------------------------------------------------------
+
+/// Hack namespace prepended to the selector
+$hack-namespace: '_' !default;
+
+@function _hack() {
+
+    // You may not hack a hack
+    $recursive-check: should-not-be-called-recursively('hack');
+
+    $selector: ();
+    $namespace: if($bem-use-namespaces, $hack-namespace, '');
+
+    @each $s in & {
+        $selector-to-str: inspect(nth($s, 1));
+        $selector-without-dot: str-slice($selector-to-str, 2, -1);
+        $new-selector: '.' + $namespace + $selector-without-dot;
+        $sl: selector-replace($s, nth($s, 1), $new-selector);;
+        $selector: append($selector, $sl, 'comma');
+    }
+
+    $set-current: set-current-context('hack', 'some-hack', $selector);
+
+    @return $selector;
+
+}
+
+@mixin hack() {
+
+    @at-root #{_hack()} {
+        @content;
+    }
+
+    $unset-current: unset-current-context('hack');
+
+}

data/stylesheets/_index.scss

@@ -0,0 +1,7 @@
+// -----------------------------------------------------------------------------
+// Logger
+// -----------------------------------------------------------------------------
+
+@import '_block';
+@import '_element';
+@import '_modifier';

data/stylesheets/_logger.scss

@@ -0,0 +1,12 @@
+// -----------------------------------------------------------------------------
+// Logger
+// -----------------------------------------------------------------------------
+
+/// Stores the whole BEM structure
+$_bem-log: () !global;
+
+@import 'logger/_context-logger';
+@import 'logger/_block-logger';
+@import 'logger/_element-logger';
+@import 'logger/_modifier-logger';
+@import 'logger/_scope-logger';

data/stylesheets/_modifier.scss

@@ -0,0 +1,49 @@
+// ----------------------------------------------------------------------
+// Modifier constructor
+// ----------------------------------------------------------------------
+
+/// Initializes a new modifier for the current block or element(s)
+/// @private
+/// @param {String | Arglist} $modifiers - List of new modifier names
+/// @returns The final selector for the new modifier(s)
+
+
+@function _modifier($modifiers...) {
+
+    // Log new modifier(s)
+    $new-modifier: _bem-log-modifier($modifiers...);
+
+    // Error checks
+    $inside-check: _should-be-called-within('block');
+    $outside-check: _should-not-be-called-within('modifier');
+
+    $selector: ();
+
+    @each $modifier in $modifiers {
+        $new-selector: ();
+
+        @each $sel in & {
+            $modified-selector: #{$sel}#{$bem-modifier-separator}#{$modifier};
+            $new-selector: append($new-selector, $modified-selector, 'comma');
+        }
+
+        $selector: append($selector, $new-selector, 'comma');
+    }
+
+    $set-current: set-current-context('modifier', $modifiers, $selector);
+
+    @return $selector;
+}
+
+
+/// Creates new modifier(s)
+/// @param {String | Arglist} $modifiers  - Name of the new modifier(s)
+
+@mixin modifier($modifiers...) {
+
+    @at-root #{_modifier($modifiers...)} {
+        @content;
+    }
+
+    $unset-current: unset-current-context('modifier');
+}

data/stylesheets/_modifies-element.scss

@@ -0,0 +1,37 @@
+// ----------------------------------------------------------------------
+// Element modifier
+// ----------------------------------------------------------------------
+
+/// Scopes the @content ruleset to an element of the block being modified
+/// @private
+/// @param {String | Arglist} $modified-elements - List of elements that should be modified
+/// @returns The final selector for the element(s) modified by the block modifier
+
+@function _modifies-element($modified-element...) {
+
+    $inside-check: should-be-called-within('modifier', 'state');
+    $outside-check: should-not-be-called-within('element');
+
+    $selectors: ();
+
+    @each $element in $modified-element {
+        $element: map-get(map-get($_bem-current-context, 'block'), 'selector') + $bem-element-separator + $element;
+        $selectors: append($selectors, $element, 'comma');
+    }
+
+    $selector: selector-nest(&, $selectors);
+
+    $set-current: set-current-context('modifies-element', $modified-element, $selector);
+
+    @return $selector;
+}
+
+
+/// Scopes the @content ruleset to an element of the block being modified
+/// @param {String | Arglist} $modified-elements - Name of the element(s) that should be modified
+
+@mixin modifies-element($modified-elements...) {
+    @at-root #{_modifies-element($modified-elements...)} {
+        @content;
+    }
+}

data/stylesheets/_scope.scss

@@ -0,0 +1,40 @@
+// -----------------------------------------------------------------------------
+// Scope constructor
+// -----------------------------------------------------------------------------
+
+/// Set namespace for scopes
+/// @public
+
+$bem-scope-namespace: 's';
+
+/// Initializes a new scope object
+/// @private
+/// @param {String} $scope  - Name for the new scope
+/// @returns The final selector for the new scope object
+
+@function _scope($scope) {
+
+    // Log new block
+    $new-scope: _bem-log-scope($scope);
+
+    // Check it's not called inside another scope
+    // and it's called at the root-level
+    $recursive-check: should-not-be-called-recursively('scope');
+    $outside-check: should-not-be-called-within('block');
+
+    $namespace: if($bem-use-namespaces, $bem-scope-namespace + '-', '');
+    $selector: '.' + $namespace + $scope;
+
+    $set-current: set-current-context('scope', $scope, $selector);
+
+    @return $selector;
+}
+
+@mixin scope($scope) {
+
+    @at-root #{_scope($scope)} {
+        @content;
+    }
+
+    $unset-current: unset-current-context('scope');
+}

data/stylesheets/_state.scss

@@ -0,0 +1,28 @@
+// -----------------------------------------------------------------------------
+// State constructor
+// -----------------------------------------------------------------------------
+
+$state-namespace: 'is' !default;
+
+@function _state($states...) {
+    $selector: ();
+    $namespace: if($bem-use-namespaces, $state-namespace + '-', '');
+
+    @each $state in $states {
+      $s: selector-append(&, '.#{$namespace}#{$state}');
+      $selector: append($selector, $s, 'comma');
+    }
+
+    $set-current: set-current-context('state', $states, $selector);
+
+    @return $selector;
+}
+
+@mixin state($states...) {
+
+    @at-root #{_state($states...)} {
+      @content;
+    }
+
+    $unset-state: unset-current-context('state');
+}

data/stylesheets/_theme.scss

@@ -0,0 +1,33 @@
+// -----------------------------------------------------------------------------
+// Theme constructor
+// -----------------------------------------------------------------------------
+
+$bem-theme-namespace: 't' !default;
+
+@function _theme($themes...) {
+
+    // If you try to hack a hack you can break the internet.
+    // So please, no one try it.
+    $recursive-test: should-not-be-called-recursively('theme');
+
+    $selector: ();
+    $namespace: if($bem-use-namespaces, $bem-theme-namespace + '-', '');
+
+    @each $theme in $themes {
+      $t: selector-nest('.#{$namespace}#{$theme}', &);
+      $selector: append($selector, $t, 'comma');
+    }
+
+    $set-current: set-current-context('theme', $themes, $selector);
+
+    @return $selector;
+}
+
+@mixin theme($themes...) {
+
+    @at-root #{_theme($themes...)} {
+      @content;
+    }
+
+    $unset-current: unset-current-context('theme');
+}

data/stylesheets/logger/_block-logger.scss

@@ -0,0 +1,30 @@
+// -----------------------------------------------------------------------------
+// Block Logger
+// -----------------------------------------------------------------------------
+
+/// Find if a given $block has already been created
+/// @param {String} $block - Name of the block
+
+@function block-exists($block) {
+    @return map-has-key($_bem-log, $block);
+}
+
+/// Log the new $block
+/// @param {String} $block - Block name
+
+@function _bem-log-block($block) {
+
+    // Check if the block has already been created
+    @if block-exists($block) {
+        @error '`#{$block}` block has already been created';
+    }
+
+    // Initialize a new block map
+    $new-block: ($block: ('elements': (), 'modifiers': ()));
+
+    // Update bem log with new block
+    $_bem-log: map-merge($_bem-log, $new-block) !global;
+
+    // Everything OK
+    @return true;
+}

data/stylesheets/logger/_context-logger.scss

@@ -0,0 +1,40 @@
+// -----------------------------------------------------------------------------
+// Context logger
+// -----------------------------------------------------------------------------
+// Table of contents:
+// 1. Store current context
+// 2. Clear current context
+
+
+/// Used to stores the current object being constructed
+/// @private
+
+$_bem-current-context: () !global;
+
+
+// -----------------------------------------------------------------------------
+// 1. Store current context
+// -----------------------------------------------------------------------------
+
+/// Sets the current object, stores name and generated selector
+
+@function set-current-context($obj, $name, $selector) {
+    $new-current: (#{$obj}: (name: $name, selector: $selector));
+    $_bem-current-context: map-merge($_bem-current-context, $new-current) !global;
+
+    @return $selector;
+}
+
+
+// -----------------------------------------------------------------------------
+// 2. Clear current context
+// -----------------------------------------------------------------------------
+
+/// Clears the current object
+
+@function unset-current-context($obj) {
+    $new-current: (#{$obj}: null);
+    $_bem-current-context: map-merge($_bem-current-context, $new-current) !global;
+
+    @return null;
+}

data/stylesheets/logger/_element-logger.scss

@@ -0,0 +1,59 @@
+// -----------------------------------------------------------------------------
+// Element Logger
+// -----------------------------------------------------------------------------
+
+/// Find if the given $elements have already been created
+/// @param {Arglist | String} $elements - A single or multiple element names
+
+@function element-exists($elements...) {
+
+    // Get the current block name
+    // Then get the current block map
+    // Then get the current block element map
+    $current-block-name: map-get(map-get($_bem-current-context, 'block'), 'name');
+    $current-block: map-get($_bem-log, $current-block-name);
+    $current-elements: map-get($current-block, 'elements');
+
+    @each $element in $elements {
+        @if map-has-key($current-elements, $element) {
+            @return true;
+        }
+    }
+
+    @return false;
+}
+
+
+/// Log the new $elements
+/// @param {Arglist | String} $elements - A single or multiple element names
+
+@function _bem-log-element($elements...) {
+
+    // Check any $elements has already been defined for the current block
+    @if element-exists($elements...) {
+        @error 'One or more elements from `#{inspect($elements)}` have already been created';
+    }
+
+    // Find the current block name
+    // Then get the map for the current block
+    // Then get the element list
+    $current-block-name: map-get(map-get($_bem-current-context, 'block'), 'name');
+    $current-block: map-get($_bem-log, $current-block-name);
+    $current-elements: map-get($current-block, 'elements');
+
+    // For each possible name in $name
+    // Create an updated block map
+    // Add it to the list of elements
+    @each $element in $elements {
+        $updated: ($element: ('modifiers': ()));
+        $current-elements: map-merge($current-elements, $updated);
+    }
+
+    // Update the block
+    $updated-block: ($current-block-name: ('elements': ($current-elements), 'modifiers': map-get($current-block, 'modifiers')));
+
+    // Update the log
+    $_bem-log: map-merge($_bem-log, $updated-block) !global;
+
+    @return true;
+}

data/stylesheets/logger/_modifier-logger.scss

@@ -0,0 +1,94 @@
+// -----------------------------------------------------------------------------
+// Modifier Logger
+// -----------------------------------------------------------------------------
+
+/// Find if the given $modifiers have already been created
+/// @param {Arglist | String} $modifiers - A single or multiple modifier names
+
+@function modifier-exists($modifiers...) {
+
+    // Get the current block name
+    // Then get the current block map
+    // Then get the current block modifiers map
+    $current-block-name: map-get(map-get($_bem-current-context, 'block'), 'name');
+    $current-block: map-get($_bem-log, $current-block-name);
+    $current-modifiers: map-get($current-block, 'modifiers');
+
+    @each $modifier in $modifiers {
+        @if map-has-key($current-modifiers, $modifier) {
+            @return true;
+        }
+    }
+
+    @return false;
+}
+
+/// Log the new $modifiers
+/// @param {Arglist | String} $modifiers - A single or multiple modifier names
+
+
+@function _bem-log-modifier($modifiers...) {
+
+    // Check if the modifier has already been defined for the current block or element
+    @if modifier-exists($modifiers...) {
+        @error 'One or more elements from `#{inspect($modifiers)}` have already been created';
+    }
+
+    // Find the current block name
+    $current-block-name: map-get(map-get($_bem-current-context, 'block'), 'name');
+    $current-item-name: $current-block-name;
+
+    // Get the map for the current block
+    $current-block: map-get($_bem-log, $current-block-name);
+    $current-item: $current-block;
+
+    // Get the map for the current block modifiers
+    $current-block-modifiers: map-get($current-block, 'modifiers');
+    $current-item-modifiers: $current-block-modifiers;
+
+    // Check whether the current context is a block or an element
+    $context-type: if(map-get($_bem-current-context, 'element') == null, 'block', 'element');
+
+    // Update item modifier list if within an Element
+    @if $context-type == 'element' {
+        // @todo: should work if there are multiple current items
+        $current-item-name: nth(map-get(map-get($_bem-current-context, 'element'), 'name'),1);
+        $current-item: map-get(map-get($current-block, 'elements'), $current-item-name);
+        $current-item-modifiers: map-get($current-item, 'modifiers');
+    }
+
+    // For each possible name in $name
+    @each $modifier in $modifiers {
+
+        // Create an updated block/element map
+        $updated: ();
+
+        @if $context-type == 'element' {
+            $updated: (#{$modifier}: ('modified-by': ()))
+        } @else {
+            $modifies-element: map-get($_bem-current-context, 'modifies-element');
+            $updated: (#{$modifier}: ('modifies-element': ()));
+        }
+
+        // Add it to the list of modifiers
+        $current-item-modifiers: map-merge($current-item-modifiers, $updated);
+    }
+
+    $updated-block: ();
+
+    @if $context-type == 'element' {
+        // update the element map;
+        $updated-item: (#{$current-item-name}: ('modifiers': $current-item-modifiers));
+        // @error $updated-item;
+        $updated-elements: map-merge(map-get($current-block, 'elements'), $updated-item);
+        $updated-block: (#{$current-block-name}: ('modifiers': map-get($current-block, 'modifiers'), 'elements': $updated-elements));
+    } @else {
+        $updated-block: (#{$current-block-name}: ('modifiers': ($current-item-modifiers), 'elements': map-get($current-block, 'elements')));;
+    }
+
+    // // Update the log
+    $_bem-log: map-merge($_bem-log, $updated-block) !global;
+
+    @return true;
+
+}

data/stylesheets/logger/_scope-logger.scss

@@ -0,0 +1,30 @@
+// -----------------------------------------------------------------------------
+// Scope Logger
+// -----------------------------------------------------------------------------
+
+/// Find if a given $scope has already been created
+/// @param {String} $scope - Name of the scope
+
+@function scope-exists($scope) {
+    @return map-has-key($_bem-log, $scope);
+}
+
+/// Log the new $scope
+/// @param {String} $scope - scope name
+
+@function _bem-log-scope($scope) {
+
+    // Check if the scope has already been created
+    @if scope-exists($scope) {
+        @error '`#{$scope}` scope has already been created';
+    }
+
+    // Initialize a new scope map
+    $new-scope: ($scope: ());
+
+    // Update bem log with new scope
+    $_bem-log: map-merge($_bem-log, $new-scope) !global;
+
+    // Everything OK
+    @return true;
+}

data/stylesheets/test.css

@@ -0,0 +1,26 @@
+.o-burger {
+  texture: juicy; }
+  .o-burger__letuce, .o-burger__tomato {
+    quality: fresh; }
+  .o-burger__cheese {
+    type: gouda; }
+    .o-burger__cheese--parmigiano {
+      type: parmigiano; }
+  .o-burger__extra-topping {
+    ingredient: bacon; }
+  .o-burger__meat {
+    type: beef; }
+  .o-burger--veggie {
+    texture: smooth; }
+    .o-burger--veggie .o-burger__meat {
+      type: lentils; }
+    .o-burger--veggie .o-burger__extra-topping {
+      ingredient: avocado; }
+      ._o-burger--veggie .o-burger__extra-topping {
+        ingredient: bacon; }
+  .t-mexican .o-burger {
+    spicy: hell-yeah; }
+  .o-burger.is-cold {
+    taste: terrible; }
+
+/*# sourceMappingURL=test.css.map */

data/stylesheets/test.css.map

@@ -0,0 +1,7 @@
+{
+"version": 3,
+"mappings": "AAmDa,SAAwB;EC9CjC,OAAO,EAAE,KAAK;EC+BL,oCAA0B;ID5B/B,OAAO,EAAE,KAAK;EC4BT,iBAA0B;IDxB/B,IAAI,EAAE,KAAK;IE+BN,6BAA4B;MF5B7B,IAAI,EAAE,UAAU;ECqBf,wBAA0B;IDhB/B,UAAU,EAAE,KAAK;ECgBZ,eAA0B;IDZ/B,IAAI,EAAE,IAAI;EEmBL,iBAA4B;IFfjC,OAAO,EAAE,MAAM;IGKV,iCAA4C;MHF7C,IAAI,EAAE,OAAO;IGEZ,0CAA4C;MHE7C,UAAU,EAAE,OAAO;MIJlB,2CAAW;QJOR,UAAU,EAAE,KAAK;EKXpB,oBAAsB;ILiB3B,KAAK,EAAE,SAAS;EMtBX,iBAAsB;IN0B3B,KAAK,EAAE,QAAQ",
+"sources": ["_block.scss","test.scss","_element.scss","_modifier.scss","_modifies-element.scss","_hack.scss","_theme.scss","_state.scss"],
+"names": [],
+"file": "test.css"
+}

data/stylesheets/test.scss

@@ -0,0 +1,59 @@
+@import 'bem-constructor';
+
+// The Burger Test™
+
+@include object('burger') {
+    texture: juicy;
+
+    @include element('letuce', 'tomato') {
+        quality: fresh;
+    }
+
+    @include element('cheese') {
+        type: gouda;
+
+        @include modifier('parmigiano') {
+            type: parmigiano;
+        }
+    }
+
+    @include element('extra-topping') {
+        ingredient: bacon;
+    }
+
+    @include element('meat') {
+        type: beef;
+    }
+
+    @include modifier('veggie') {
+        texture: smooth;
+
+        @include modifies-element('meat') {
+            type: lentils;
+        }
+
+        @include modifies-element('extra-topping') {
+            ingredient: avocado;
+
+            @include hack() {
+                ingredient: bacon;
+            }
+        }
+    }
+
+    @include theme('mexican') {
+        spicy: hell-yeah;
+    }
+
+    @include state('cold') {
+        taste: terrible;
+    }
+}
+
+// @include scope(test) {
+//     a: shite
+// }
+
+// .bem-log {
+//     log: inspect($_bem-log);
+// }

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: bem-constructor
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Daniel Guillan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sass
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: compass
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A Sass library for building immutable and namespaced BEM-style CSS objects
+email:
+- daniel.guillan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/bem-constructor.rb
+- stylesheets/_bem-constructor.scss
+- stylesheets/_block.scss
+- stylesheets/_element.scss
+- stylesheets/_error-checks.scss
+- stylesheets/_hack.scss
+- stylesheets/_index.scss
+- stylesheets/_logger.scss
+- stylesheets/_modifier.scss
+- stylesheets/_modifies-element.scss
+- stylesheets/_scope.scss
+- stylesheets/_state.scss
+- stylesheets/_theme.scss
+- stylesheets/logger/_block-logger.scss
+- stylesheets/logger/_context-logger.scss
+- stylesheets/logger/_element-logger.scss
+- stylesheets/logger/_modifier-logger.scss
+- stylesheets/logger/_scope-logger.scss
+- stylesheets/test.css
+- stylesheets/test.css.map
+- stylesheets/test.scss
+homepage: https://github.com/danielguillan/bem-constructor
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: bem-constructor
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: BEM Constructor is a Sass library for building immutable and namespaced BEM-style
+  CSS objects. By enforcing a consistent and programatic way of defining objects (blocks,
+  elements and modifiers) it ensures a more structured, robust and secure object codebase
+  that is easy to understand and maintain. Objects defined using the constructor are
+  impossible to modify and reassign by mistake or omission.
+test_files: []