Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

updated docs

  • Loading branch information...
commit b7c51347c56523da970535fa9793f25a38a10743 1 parent aca4886
@leafo leafo authored
Showing with 179 additions and 11 deletions.
  1. +179 −11 docs/docs.md
View
190 docs/docs.md
@@ -1,8 +1,8 @@
- title: v0.3.1 documentation
+ title: v0.3.2 documentation
link_to_home: true
--
-<h2 skip="true">Documentation v0.3.1</h2>
+<h2 skip="true">Documentation v0.3.2</h2>
<div style="margin-bottom: 1em;">$index</div>
@@ -156,7 +156,7 @@ logically organize the structure of our CSS.
```less
ol.list {
li.special {
- border: 1px solid red;
+ border: 1px solid red;
}
li.plain {
@@ -257,7 +257,7 @@ compiled. Its properties will only appear when mixed into another block.
The canonical example is to create a rounded corners mixin that works across
browsers:
-
+
```less
.rounded-corners(@radius: 5px) {
border-radius: @radius;
@@ -282,7 +282,7 @@ show up in the output, give it a blank argument list:
.secret() {
font-size: 6000px;
}
-
+
.div {
.secret;
}
@@ -356,6 +356,174 @@ remaining default values assigned by the mixin:
```
+
+#### Pattern Matching
+
+When you *mix in* a mixin, all the available mixins of that name in the current
+scope are checked to see if they match based on what was passed to the mixin
+and how it was declared.
+
+The simplest case is matching by number of arguments. Only the mixins that
+match the number of arguments passed in are used, with the exception of 0
+argument mixins, which are always included.
+
+ ```less
+ .simple() { // no argument mixin always included
+ height: 10px;
+ }
+
+ .simple(@a, @b) {
+ color: red;
+ }
+
+ .simple(@a) {
+ color: blue;
+ }
+
+ div {
+ .simple(10);
+ }
+
+ span {
+ .simple(10, 20);
+ }
+ ```
+
+Another way of controlling whether a mixin matches is by specifying a value in
+place of an argument name when declaring the mixin:
+
+ ```less
+ .style(old, @size) {
+ font: @size serif;
+ }
+
+ .style(new, @size) {
+ font: @size sans-serif;
+ }
+
+ .style(@_, @size) {
+ letter-spacing: floor(@size / 6px);
+ }
+
+ em {
+ @switch: old;
+ .style(@switch, 15px);
+ }
+ ```
+
+Notice that two of the three mixins were matched. The mixin with a matching
+first argument, and the generic mixin that matches two arguments. It's common
+to use `@_` as the name of a variable we intend to not use. It has no special
+meaning to LESS, just to the reader of the code.
+
+#### Guards
+
+Another way of restricting when a mixin is mixed in is by using guards. A guard
+is a special expression that is associated with a mixin declaration that is
+evaluated during the mixin process. It must evaluate to true before the mixin
+can be used.
+
+We use the `when` keyword to begin describing a list of guard expressions.
+
+Here's a simple example:
+
+ ```less
+ .guarded(@arg) when (@arg = hello) {
+ color: blue;
+ }
+
+ div {
+ .guarded(hello); // match
+ }
+
+ span {
+ .guarded(world); // no match
+ }
+ ```
+Only the `div`'s mixin will match in this case, because the guard expression
+requires that `@arg` is equal to `hello`.
+
+We can include many different guard expressions by separating them by commas.
+Only one of them needs to match to trigger the mixin:
+
+ ```less
+ .x(@a, @b) when (@a = hello), (@b = world) {
+ width: 960px;
+ }
+
+ div {
+ .x(hello, bar); // match
+ }
+
+ span {
+ .x(foo, world); // match
+ }
+
+ pre {
+ .x(foo, bar); // no match
+ }
+ ```
+
+Instead of a comma, we can use `and` keyword to make it so all of the guards
+must match in order to trigger the mixin. `and` has higher precedence than the
+comma.
+
+ ```less
+ .y(@a, @b) when (@a = hello) and (@b = world) {
+ height: 600px;
+ }
+
+ div {
+ .y(hello, world); // match
+ }
+
+ span {
+ .y(hello, bar); // no match
+ }
+ ```
+
+Commas and `and`s can be mixed and matched.
+
+You can also negate a guard expression by using `not` in from of the parentheses:
+
+ ```less
+ .x(@a) when not (@a = hello) {
+ color: blue;
+ }
+
+ div {
+ .x(hello); // no match
+ }
+ ```
+
+The `=` operator is used to check equality between any two values. For numbers
+the following comparison operators are also defined:
+
+`<`, `>`, `=<`, `>=`
+
+There is also a collection of predicate functions that can be used to test the
+type of a value.
+
+These are `isnumber`, `iscolor`, `iskeyword`, `isstring`, `ispixel`,
+`ispercentage` and `isem`.
+
+ ```less
+ .mix(@a) when (ispercentage(@a)) {
+ height: 500px * @a;
+ }
+ .mix(@a) when (ispixel(@a)) {
+ height: @a;
+ }
+
+ div.a {
+ .mix(50%);
+ }
+
+ div.a {
+ .mix(350px);
+ }
+ ```
+
### Import
Multiple LESS files can be compiled into a single CSS file by using the
@@ -521,10 +689,10 @@ function that let's you unquote any value. It is called `e`.
<http://sass-lang.com/docs/yardoc/Sass/Script/Functions.html#mix-instance_method>.
* `rgbahex(color)` -- returns a string containing 4 part hex color.
-
+
This is used to convert a CSS color into the hex format that IE's filter
method expects when working with an alpha component.
-
+
```less
.class {
@start: rgbahex(rgba(25, 34, 23, .5));
@@ -662,7 +830,7 @@ associative array of names and values. The values will parsed as CSS values:
```php
$less = new lessc();
- echo $less->parse(".magic { color: @color; width: @base - 200; }",
+ echo $less->parse(".magic { color: @color; width: @base - 200; }",
array(
'color' => 'red';
'base' => '960px';
@@ -776,7 +944,7 @@ Errors from watch mode are written to standard out.
## License
Copyright (c) 2010 Leaf Corcoran, <http://leafo.net/lessphp>
-
+
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
@@ -784,10 +952,10 @@ without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
-
+
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
-
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
Please sign in to comment.
Something went wrong with that request. Please try again.