renamed placeholders to locals

added new placeholder syntax

Author: sokra

README.md

@@ -2,7 +2,7 @@
 
 ## installation
 
-`npm install css-loader`
+`npm install css-loader --save-dev`
 
 ## Usage
 
@@ -30,24 +30,51 @@ module.exports = {
   module: {
     loaders: [
       { test: /\.css$/, loader: "style-loader!css-loader" },
-      { test: /\.png$/, loader: "url-loader?limit=100000&mimetype=image/png" },
+      { test: /\.png$/, loader: "url-loader?limit=100000" },
       { test: /\.jpg$/, loader: "file-loader" }
     ]
   }
 };
 ```
 
-### Placeholders
+### 'Root-relative' urls
+
+For urls that start with a `/`, the default behavior is to not translate them:
+* `url(/image.png)` => `url(/image.png)`
+
+If a `root` query parameter is set, however, it will be prepended to the url
+and then translated:
+
+With a config like:
+
+``` javascript
+    loaders: [
+      { test: /\.css$/, loader: "style-loader!css-loader?root=." },
+      ...
+    ]
+```
+
+The result is:
+
+* `url(/image.png)` => `require("./image.png")`
+
+### Local scope
 
 (experimental)
 
-Special selectors are automatically replaced with random identifiers, which are exported:
+By default CSS exports all class names into a global selector scope. This is a feature which tries to offer a local selector scope.
+
+The syntax `.local[className]` can be used to declare `className` in the local scope. The local identifiers are exported by the module.
+
+It does it by replacing the selectors by unique identifiers. The choosen unique identifiers are exported by the module.
+
+Example:
 
 ``` css
-.[className] { background: red; }
-#[someId] { background: green; }
-.[className] .[subClass] { color: green; }
-#[someId] .[subClass] { color: blue; }
+.local[className] { background: red; }
+#local[someId] { background: green; }
+.local[className] .local[subClass] { color: green; }
+#local[someId] .local[subClass] { color: blue; }
 ```
 
 is transformed to
@@ -62,33 +89,16 @@ is transformed to
 and the identifiers are exported:
 
 ``` js
-exports.placeholders = {
+exports.locals = {
   className: "ze24205081ae540afa51bd4cce768e8b7",
   someId: "zdf12049771f7fc796a63a3945da3a66d",
   subClass: "z9f634213cd27594c1a13d18554d47a8c"
 }
 ```
 
-### 'Root-relative' urls
-
-For urls that start with a `/`, the default behavior is to not translate them:
-* `url(/image.png)` => `url(/image.png)`
-
-If a `root` query parameter is set, however, it will be prepended to the url
-and then translated:
-
-With a config like:
+You can configure the generated ident with the `localIdentName` query parameter (default `[hash:base64]`). Example: `css-loader?localIdentName=[path][name]---[local]---[hash:base64:5]` for easier debugging.
 
-``` javascript
-    loaders: [
-      { test: /\.css$/, loader: "style-loader!css-loader?root=." },
-      ...
-    ]
-```
-
-The result is:
-
-* `url(/image.png)` => `require("./image.png")`
+Note: For prerendering with extract-text-webpack-plugin you should use `css-loader/locals` instead of `style-loader!css-loader` in the prerendering bundle. It doesn't embed CSS but only exports the identifier mappings.
 
 ### SourceMaps
 

lib/getLocalIdent.js

@@ -0,0 +1,15 @@
+/*
+	MIT License http://www.opensource.org/licenses/mit-license.php
+	Author Tobias Koppers @sokra
+*/
+var loaderUtils = require("loader-utils");
+module.exports = function getLocalIdent(loaderContext, localIdentName, localName, options) {
+	var request = loaderContext.options && typeof loaderContext.options.context === "string" ?
+		loaderUtils.stringifyRequest({ context: loaderContext.options.context }, loaderUtils.getRemainingRequest(loaderContext)) :
+		loaderContext.request;
+	options.content = localName + " " + request;
+	options.context = loaderContext.options && typeof loaderContext.options.context === "string" ? loaderContext.options.context : loaderContext.context;
+	localIdentName = localIdentName.replace(/\[local\]/gi, localName);
+	var hash = loaderUtils.interpolateName(loaderContext, localIdentName, options);
+	return hash.replace(/[^a-zA-Z0-9\-_]/g, "-").replace(/^([^a-zA-Z_])/, "_$1");
+};

lib/getPlaceholderIdent.js

@@ -8,7 +8,7 @@ var ReplaceMany = require("./ReplaceMany");
 var loaderUtils = require("loader-utils");
 var SourceListMap = require("source-list-map").SourceListMap;
 var CleanCSS = require("clean-css");
-var getPlaceholderIdent = require("./getPlaceholderIdent");
+var getLocalIdent = require("./getLocalIdent");
 
 module.exports = function(content, map) {
 	if(this.cacheable) this.cacheable();
@@ -17,6 +17,8 @@ module.exports = function(content, map) {
 	var forceMinimize = query.minimize;
 	var importLoaders = parseInt(query.importLoaders, 10) || 0;
 	var minimize = typeof forceMinimize !== "undefined" ? !!forceMinimize : (this && this.minimize);
+	var localIdentName = query.localIdentName || "[hash:base64]";
+	var localIdentRegExp = query.localIdentRegExp;
 
 	if(typeof map !== "string") {
 		map = JSON.stringify(map);
@@ -47,16 +49,18 @@ module.exports = function(content, map) {
 	stuff.urls.forEach(function(url, idx) {
 		replacer.replace(url.start, url.length, "__CSSLOADERURL_" + idx + "__");
 	});
-	var placeholders = {};
-	stuff.placeholders.forEach(function(placeholder) {
+	var locals = {};
+	stuff.locals.forEach(function(local) {
 		var ident;
-		if(!placeholders[placeholder.name]) {
-			ident = getPlaceholderIdent(this, placeholder.name);
-			placeholders[placeholder.name] = ident;
+		if(!locals[local.name]) {
+			ident = getLocalIdent(this, localIdentName, local.name, {
+				regExp: localIdentRegExp
+			});
+			locals[local.name] = ident;
 		} else {
-			ident = placeholders[placeholder.name];
+			ident = locals[local.name];
 		}
-		replacer.replace(placeholder.start, placeholder.length, placeholder.prefix + ident);
+		replacer.replace(local.start, local.length, local.prefix + ident);
 	}, this);
 
 	var cssContent = replacer.run(content);
@@ -127,8 +131,8 @@ module.exports = function(content, map) {
 		result.push("exports.push([module.id, " + css + ", \"\"]);");
 	}
 
-	if(Object.keys(placeholders).length > 0) {
-		result.push("exports.placeholders = " + JSON.stringify(placeholders) + ";");
+	if(Object.keys(locals).length > 0) {
+		result.push("exports.locals = " + JSON.stringify(locals) + ";");
 	}
 
 	return "exports = module.exports = require(" + loaderUtils.stringifyRequest(this, require.resolve("./css-base.js")) + ")();\n" +

lib/loader.js

@@ -0,0 +1,27 @@
+/*
+	MIT License http://www.opensource.org/licenses/mit-license.php
+	Author Tobias Koppers @sokra
+*/
+var loaderUtils = require("loader-utils");
+var parseSource = require("./parseSource");
+var getLocalIdent = require("./getLocalIdent");
+
+module.exports = function(content) {
+	if(this.cacheable) this.cacheable();
+	var query = loaderUtils.parseQuery(this.query);
+	var localIdentName = query.localIdentName || "[hash:base64]";
+	var localIdentRegExp = query.localIdentRegExp;
+
+	var stuff = parseSource(content);
+
+	var locals = {};
+	stuff.locals.forEach(function(local) {
+		if(!locals[local.name]) {
+			locals[local.name] = getLocalIdent(this, localIdentName, local.name, {
+				regExp: localIdentRegExp
+			});
+		}
+	}, this);
+
+	return "module.exports = " + JSON.stringify(locals) + ";";
+};

lib/localsLoader.js

@@ -13,8 +13,8 @@ function urlMatch(match, textBeforeUrl, replacedText, url, index) {
 	});
 }
 
-function placeholderMatch(match, prefix, name, index) {
-	this.placeholders.push({
+function localMatch(match, prefix, name, index) {
+	this.locals.push({
 		name: name,
 		prefix: prefix,
 		start: index,
@@ -47,10 +47,9 @@ var parser = new Parser({
 		"(url\\s*\\()(\\s*'([^']*)'\\s*)\\)": urlMatch,
 		"(url\\s*\\()(\\s*([^)]*)\\s*)\\)": urlMatch,
 
-		// placeholder
-		"()\\{\\{([A-Za-z_0-9]+)\\}\\}": placeholderMatch,
-		"(\\.)\\[([A-Za-z_0-9]+)\\]": placeholderMatch,
-		"(#)\\[([A-Za-z_0-9]+)\\]": placeholderMatch
+		// local
+		"(\\.)local\\[([A-Za-z_0-9]+)\\]": localMatch,
+		"(#)local\\[([A-Za-z_0-9]+)\\]": localMatch
 	},
 	comment: {
 		"\\*/": "source"
@@ -61,7 +60,7 @@ module.exports = function parseSource(source) {
 	var context = {
 		imports: [],
 		urls: [],
-		placeholders: []
+		locals: []
 	};
 	return parser.parse("source", source, context);
 };

lib/parseSource.js

@@ -2,4 +2,4 @@
 	MIT License http://www.opensource.org/licenses/mit-license.php
 	Author Tobias Koppers @sokra
 */
-module.exports = require("./lib/placeholdersLoader");
+module.exports = require("./lib/localsLoader");

lib/placeholdersLoader.js

@@ -1,8 +1,32 @@
-var should = require("should");
-var path = require("path");
+/*globals describe it */
+
+require("should");
 var cssLoader = require("../index.js");
 var vm = require("vm");
 
+function assetEvaluated(output, result, modules) {
+	try {
+		var fn = vm.runInThisContext("(function(module, exports, require) {" + output + "})", "testcase.js");
+		var m = { exports: {}, id: 1 };
+		fn(m, m.exports, function(module) {
+			if(module === "./lib/css-base.js")
+				return require("../lib/css-base");
+			if(module.indexOf("-!loader!") === 0)
+				module = module.substr(9);
+			if(modules && modules[module])
+				return modules[module];
+			return "{" + module + "}";
+		});
+	} catch(e) {
+		console.error(output);
+		throw e;
+	}
+	delete m.exports.toString;
+	delete m.exports.i;
+	m.exports.should.be.eql(result);
+
+}
+
 function test(name, input, result, query, modules) {
 	it(name, function() {
 		var output = cssLoader.call({
@@ -38,29 +62,6 @@ function testMinimize(name, input, result, query, modules) {
 	});
 }
 
-function assetEvaluated(output, result, modules) {
-	try {
-		var fn = vm.runInThisContext("(function(module, exports, require) {" + output + "})", "testcase.js");
-		var m = { exports: {}, id: 1 };
-		fn(m, m.exports, function(module) {
-			if(module === "./lib/css-base.js")
-				return require("../lib/css-base");
-			if(module.indexOf("-!loader!") === 0)
-				module = module.substr(9);
-			if(modules && modules[module])
-				return modules[module];
-			return "{" + module + "}";
-		});
-	} catch(e) {
-		console.error(output);
-		throw e;
-	}
-	delete m.exports.toString;
-	delete m.exports.i;
-	m.exports.should.be.eql(result);
-
-}
-
 describe("url", function() {
 	test("empty", "", [
 		[1, "", ""]
@@ -142,18 +143,27 @@ describe("url", function() {
 	test("media query", "@media (min-width: 500px) { body { background: url(image.png); } }", [
 		[1, "@media (min-width: 500px) { body { background: url({./image.png}); } }", ""]
 	]);
-	test("placeholder", ".[className] { background: red; }\n#[someId] { background: green; }\n" +
-		".[className] .[subClass] { color: green; }\n#[someId] .[subClass] { color: blue; }", function() { var r = [
-			[1, ".z857c3103f06630f914262cbc4bce752f { background: red; }\n#z5a79ec8f696debd47ffff36ec4ae1eb8 { background: green; }\n" +
-				".z857c3103f06630f914262cbc4bce752f .zaf1bf69321affd3c299f08aee1373fba { color: green; }\n#z5a79ec8f696debd47ffff36ec4ae1eb8 .zaf1bf69321affd3c299f08aee1373fba { color: blue; }", ""]
+	test("locals", ".local[className] { background: red; }\n#local[someId] { background: green; }\n" +
+		".local[className] .local[subClass] { color: green; }\n#local[someId] .local[subClass] { color: blue; }", function() { var r = [
+			[1, "._23_aKvs-b8bW2Vg3fwHozO { background: red; }\n#_1j3LM6lKkKzRIt19ImYVnD { background: green; }\n" +
+				"._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 { color: green; }\n#_1j3LM6lKkKzRIt19ImYVnD ._13LGdX8RMStbBE9w-t0gZ1 { color: blue; }", ""]
 		];
-		r.placeholders = {
-			className: "z857c3103f06630f914262cbc4bce752f",
-			someId: "z5a79ec8f696debd47ffff36ec4ae1eb8",
-			subClass: "zaf1bf69321affd3c299f08aee1373fba"
+		r.locals = {
+			className: "_23_aKvs-b8bW2Vg3fwHozO",
+			someId: "_1j3LM6lKkKzRIt19ImYVnD",
+			subClass: "_13LGdX8RMStbBE9w-t0gZ1"
 		};
 		return r;
 	}());
+	test("locals-format", ".local[test] { background: red; }",
+		function() { var r = [
+			[1, ".test-3tNsp { background: red; }", ""]
+		];
+		r.locals = {
+			test: "test-3tNsp"
+		};
+		return r;
+	}(), "?localIdentName=[local]-[hash:base64:5]");
 	testMinimize("minimized simple", ".class { a: b c d; }", [
 		[1, ".class{a:b c d}", ""]
 	]);