diff options
Diffstat (limited to 'vendor/leafo/lessphp/docs/docs.md')
| -rw-r--r-- | vendor/leafo/lessphp/docs/docs.md | 1400 |
1 files changed, 0 insertions, 1400 deletions
diff --git a/vendor/leafo/lessphp/docs/docs.md b/vendor/leafo/lessphp/docs/docs.md deleted file mode 100644 index 112dc2ee..00000000 --- a/vendor/leafo/lessphp/docs/docs.md +++ /dev/null @@ -1,1400 +0,0 @@ - title: v0.5.0 documentation - link_to_home: true --- - -<h2 skip="true">Documentation v0.5.0</h2> - -<div style="margin-bottom: 1em;">$index</div> - -**lessphp** is a compiler that generates CSS from a superset language which -adds a collection of convenient features often seen in other languages. All CSS -is compatible with LESS, so you can start using new features with your existing CSS. - -It is designed to be compatible with [less.js](http://lesscss.org), and suitable -as a drop in replacement for PHP projects. - -## Getting Started - -The homepage for **lessphp** can be found at [http://leafo.net/lessphp/][1]. - -You can follow development at the project's [GitHub][2]. - -Including **lessphp** in your project is as simple as dropping the single -include file into your code base and running the appropriate compile method as -described in the [PHP Interface](#php_interface). - - [1]: http://leafo.net/lessphp "lessphp homepage" - [2]: https://github.com/leafo/lessphp "lessphp GitHub page" - -## Installation - -**lessphp** is distributed entirely in a single stand-alone file. Download the -latest version from either [the homepage][1] or [GitHub][2]. - -Development versions can also be downloading from GitHub. - -Place `lessphp.inc.php` in a location available to your PHP scripts, and -include it. That's it! you're ready to begin. - -## The Language - -**lessphp** is very easy to learn because it generally functions how you would -expect it to. If you feel something is challenging or missing, feel free to -open an issue on the [bug tracker](https://github.com/leafo/lessphp/issues). - -It is also easy to learn because any standards-compliant CSS code is valid LESS -code. You are free to gradually enhance your existing CSS code base with LESS -features without having to worry about rewriting anything. - -The following is a description of the new languages features provided by LESS. - -### Line Comments - -Simple but very useful; line comments are started with `//`: - - ```less - // this is a comment - body { - color: red; // as is this - /* block comments still work also */ - } - ``` - -### Variables - -Variables are identified with a name that starts with `@`. To declare a -variable, you create an appropriately named CSS property and assign it a value: - - ```less - @family: "verdana"; - @color: red; - body { - @mycolor: red; - font-family: @family; - color: @color; - border-bottom: 1px solid @color; - } - ``` - -Variable declarations will not appear in the output. Variables can be declared -in the outer most scope of the file, or anywhere else a CSS property may -appear. They can hold any CSS property value. - -Variables are only visible for use from their current scope, or any enclosed -scopes. - -If you have a string or keyword in a variable, you can reference another -variable by that name by repeating the `@`: - - ```less - @value: 20px; - @value_name: "value"; - - width: @@value_name; - ``` - -### Expressions - -Expressions let you combine values and variables in meaningful ways. For -example you can add to a color to make it a different shade. Or divide up the -width of your layout logically. You can even concatenate strings. - -Use the mathematical operators to evaluate an expression: - - ```less - @width: 960px; - .nav { - width: @width / 3; - color: #001 + #abc; - } - .body { - width: 2 * @width / 3; - font-family: "hel" + "vetica"; - } - ``` - -Parentheses can be used to control the order of evaluation. They can also be -used to force an evaluation for cases where CSS's syntax makes the expression -ambiguous. - -The following property will produce two numbers, instead of doing the -subtraction: - - ```less - margin: 10px -5px; - ``` - -To force the subtraction: - - ```less - margin: (10px -5px); - ``` - -It is also safe to surround mathematical operators by spaces to ensure that -they are evaluated: - - ```less - margin: 10px - 5px; - ``` - -Division has a special quirk. There are certain CSS properties that use the `/` -operator as part of their value's syntax. Namely, the [font][4] shorthand and -[border-radius][3]. - - [3]: https://developer.mozilla.org/en/CSS/border-radius - [4]: https://developer.mozilla.org/en/CSS/font - - -Thus, **lessphp** will ignore any division in these properties unless it is -wrapped in parentheses. For example, no division will take place here: - - ```less - .font { - font: 20px/80px "Times New Roman"; - } - ``` - -In order to force division we must wrap the expression in parentheses: - - ```less - .font { - font: (20px/80px) "Times New Roman"; - } - ``` - -If you want to write a literal `/` expression without dividing in another -property (or a variable), you can use [string unquoting](#string_unquoting): - - ```less - .var { - @size: ~"20px/80px"; - font: @size sans-serif; - } - ``` - -### Nested Blocks - -By nesting blocks we can build up a chain of CSS selectors through scope -instead of repeating them. In addition to reducing repetition, this also helps -logically organize the structure of our CSS. - - ```less - ol.list { - li.special { - border: 1px solid red; - } - - li.plain { - font-weight: bold; - } - } - ``` - - -This will produce two blocks, a `ol.list li.special` and `ol.list li.plain`. - -Blocks can be nested as deep as required in order to build a hierarchy of -relationships. - -The `&` operator can be used in a selector to represent its parent's selector. -If the `&` operator is used, then the default action of appending the parent to -the front of the child selector separated by space is not performed. - - ```less - b { - a & { - color: red; - } - - // the following have the same effect - - & i { - color: blue; - } - - i { - color: blue; - } - } - ``` - - -Because the `&` operator respects the whitespace around it, we can use it to -control how the child blocks are joined. Consider the differences between the -following: - - ```less - div { - .child-class { color: purple; } - - &.isa-class { color: green; } - - #child-id { height: 200px; } - - &#div-id { height: 400px; } - - &:hover { color: red; } - - :link { color: blue; } - } - ``` - -The `&` operator also works with [mixins](#mixins), which produces interesting results: - - ```less - .within_box_style() { - .box & { - color: blue; - } - } - - #menu { - .within_box_style; - } - ``` - -### Mixins - -Any block can be mixed in just by naming it: - - ```less - .mymixin { - color: blue; - border: 1px solid red; - - .special { - font-weight: bold; - } - } - - - h1 { - font-size: 200px; - .mymixin; - } - ``` - -All properties and child blocks are mixed in. - -Mixins can be made parametric, meaning they can take arguments, in order to -enhance their utility. A parametric mixin all by itself is not outputted when -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; - -webkit-border-radius: @radius; - -moz-border-radius: @radius; - } - - .header { - .rounded-corners(); - } - - .info { - background: red; - .rounded-corners(14px); - } - ``` - -If you have a mixin that doesn't have any arguments, but you don't want it to -show up in the output, give it a blank argument list: - - ```less - .secret() { - font-size: 6000px; - } - - .div { - .secret; - } - ``` - -If the mixin doesn't need any arguments, you can leave off the parentheses when -mixing it in, as seen above. - -You can also mixin a block that is nested inside other blocks. You can think of -the outer block as a way of making a scope for your mixins. You just list the -names of the mixins separated by spaces, which describes the path to the mixin -you want to include. Optionally you can separate them by `>`. - - ```less - .my_scope { - .some_color { - color: red; - .inner_block { - text-decoration: underline; - } - } - .bold { - font-weight: bold; - color: blue; - } - } - - .a_block { - .my_scope .some_color; - .my_scope .some_color .inner_block; - } - - .another_block { - // the alternative syntax - .my_scope > .bold; - } - ``` - - -#### Mixin Arguments - -When declaring a mixin you can specify default values for each argument. Any -argument left out will be given the default value specified. Here's the -syntax: - -```less -.mix(@color: red, @height: 20px, @pad: 12px) { - border: 1px solid @color; - height: @height - @pad; - padding: @pad; -} - -.default1 { - .mix(); -} - -.default2 { - .mix(blue); -} - -.default3 { - .mix(blue, 40px, 5px); -} -``` - -Additionally, you can also call a mixin using the argument names, this is -useful if you want to replace a specific argument while having all the others -take the default regardless of what position the argument appears in. The -syntax looks something like this: - - -```lessbasic -div { - .my_mixin(@paddding: 4px); // @color and @height get default values - .my_mixin(@paddding: 4px, @height: 50px); // you can specify them in any order -} -``` - -You can also combine the ordered arguments with the named ones: - -```lessbasic -div { - // @color is blue, @padding is 4px, @height is default - .my_mixin(blue, @padding: 4px); -} -``` - -Mixin arguments can be delimited with either a `,` or `;`, but only one can be -active at once. This means that each argument is separated by either `,` or -`;`. By default `,` is the delimiter, in all the above examples we used a `,`. - -A problem arises though, sometimes CSS value lists are made up with commas. In -order to be able to pass a comma separated list literal we need to use `;` as -the delimiter. (You don't need to worry about this if your list is stored in a -variable) - -If a `;` appears anywhere in the argument list, then it will be used as the -argument delimiter, and all commas we be used as part of the argument values. - -Here's a basic example: - -```less -.fancy_mixin(@box_shadow, @color: blue) { - border: 1px solid @color; - box-shadow: @box_shadow; -} - - -div { - // two arguments passed separated by ; - .fancy_mixin(2px 2px, -2px -2px; red); -} - -pre { - // one argument passed, ends in ; - .fancy_mixin(inset 4px 4px, -2px 2px;); -} - -``` - -If we only want to pass a single comma separated value we still need to use -`;`, to do this we stick it on the end as demonstrated above. - - -#### `@arguments` Variable - -Within an mixin there is a special variable named `@arguments` that contains -all the arguments passed to the mixin along with any remaining arguments that -have default values. The value of the variable has all the values separated by -spaces. - -This useful for quickly assigning all the arguments: - - ```less - .box-shadow(@x, @y, @blur, @color) { - box-shadow: @arguments; - -webkit-box-shadow: @arguments; - -moz-box-shadow: @arguments; - } - .menu { - .box-shadow(1px, 1px, 5px, #aaa); - } - ``` - -In addition to the arguments passed to the mixin, `@arguments` will also include -remaining default values assigned by the mixin: - - - ```less - .border-mixin(@width, @style: solid, @color: black) { - border: @arguments; - } - - pre { - .border-mixin(4px, dotted); - } - - ``` - - -#### 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. - - ```less - .simple() { // matches no arguments - height: 10px; - } - - .simple(@a, @b) { // matches two arguments - color: red; - } - - .simple(@a) { // matches one argument - color: blue; - } - - div { - .simple(10); - } - - span { - .simple(10, 20); - } - ``` - -Whether an argument has default values is also taken into account when matching -based on number of arguments: - - ```less - // matches one or two arguments - .hello(@a, @b: blue) { - height: @a; - color: @b; - } - - .hello(@a, @b) { // matches only two - width: @a; - border-color: @b; - } - - .hello(@a) { // matches only one - padding: 1em; - } - - div { - .hello(10px); - } - - pre { - .hello(10px, yellow); - } - ``` - -Additionally, a *vararg* value can be used to further control how things are -matched. A mixin's argument list can optionally end in the special argument -named `...`. The `...` may match any number of arguments, including 0. - - ```less - // this will match any number of arguments - .first(...) { - color: blue; - } - - // matches at least 1 argument - .second(@arg, ...) { - height: 200px + @arg; - } - - div { .first("some", "args"); } - pre { .second(10px); } - ``` - -If you want to capture the values that get captured by the *vararg* you can -give it a variable name by putting it directly before the `...`. This variable -must be the last argument defined. It's value is just like the special -[`@arguments` variable](#arguments_variable), a space separated list. - - - ```less - .hello(@first, @rest...) { - color: @first; - text-shadow: @rest; - } - - span { - .hello(red, 1px, 1px, 0px, white); - } - - ``` - -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); - } - ``` - -#### !important - -If you want to apply the `!important` suffix to every property when mixing in a -mixin, just append `!important` to the end of the call to the mixin: - - ```less - .make_bright { - color: red; - font-weight: bold; - } - - .color { - color: green; - } - - body { - .make_bright() !important; - .color(); - } - - ``` - -### Selector Expressions - -Sometimes we want to dynamically generate the selector of a block based on some -variable or expression. We can do this by using *selector expressions*. Selector -expressions are CSS selectors that are evaluated in the current scope before -being written out. - -A simple example is a mixin that dynamically creates a selector named after the -mixin's argument: - - ```less - .create-selector(@name) { - @{name} { - color: red; - } - } - - .create-selector(hello); - .create-selector(world); - ``` - -The string interpolation syntax works inside of selectors, letting you insert varaibles. - -Here's an interesting example adapted from Twitter Bootstrap. A couple advanced -things are going on. We are using [Guards](#guards) along with a recursive -mixin to work like a loop to generate a series of CSS blocks. - - - ```less - // create our recursive mixin: - .spanX (@index) when (@index > 0) { - .span@{index} { - width: @index * 100px; - } - .spanX(@index - 1); - } - .spanX (0) {} - - // mix it into the global scopee: - .spanX(4); - ``` - -### Import - -Multiple LESS files can be compiled into a single CSS file by using the -`@import` statement. Be careful, the LESS import statement shares syntax with -the CSS import statement. If the file being imported ends in a `.less` -extension, or no extension, then it is treated as a LESS import. Otherwise it -is left alone and outputted directly: - - ```lessbasic - // my_file.less - .some-mixin(@height) { - height: @height; - } - - // main.less - @import "main.less" // will import the file if it can be found - @import "main.css" // will be left alone - - body { - .some-mixin(400px); - } - ``` - -All of the following lines are valid ways to import the same file: - - ```lessbasic - @import "file"; - @import 'file.less'; - @import url("file"); - @import url('file'); - @import url(file); - ``` - -When importing, the `importDir` is searched for files. This can be configured, -see [PHP Interface](#php_interface). - -A file is only imported once. If you try to include the same file multiple -times all the import statements after the first produce no output. - -### String Interpolation - -String interpolation is a convenient way to insert the value of a variable -right into a string literal. Given some variable named `@var_name`, you just -need to write it as `@{var_name}` from within the string to have its value -inserted: - - ```less - @symbol: ">"; - h1:before { - content: "@{symbol}: "; - } - - h2:before { - content: "@{symbol}@{symbol}: "; - } - ``` - -There are two kinds of strings, implicit and explicit strings. Explicit strings -are wrapped by double quotes, `"hello I am a string"`, or single quotes `'I am -another string'`. Implicit strings only appear when using `url()`. The text -between the parentheses is considered a string and thus string interpolation is -possible: - - ```less - @path: "files/"; - body { - background: url(@{path}my_background.png); - } - ``` - -### String Format Function - -The `%` function can be used to insert values into strings using a *format -string*. It works similar to `printf` seen in other languages. It has the -same purpose as string interpolation above, but gives explicit control over -the output format. - - ```less - @symbol: ">"; - h1:before { - content: %("%s: ", @symbol); - } - ``` - -The `%` function takes as its first argument the format string, following any -number of addition arguments that are inserted in place of the format -directives. - -A format directive starts with a `%` and is followed by a single character that -is either `a`, `d`, or `s`: - - ```less - strings: %("%a %d %s %a", hi, 1, 'ok', 'cool'); - ``` - -`%a` and `%d` format the value the same way: they compile the argument to its -CSS value and insert it directly. When used with a string, the quotes are -included in the output. This typically isn't what we want, so we have the `%s` -format directive which strips quotes from strings before inserting them. - -The `%d` directive functions the same as `%a`, but is typically used for numbers -assuming the output format of numbers might change in the future. - -### String Unquoting - -Sometimes you will need to write proprietary CSS syntax that is unable to be -parsed. As a workaround you can place the code into a string and unquote it. -Unquoting is the process of outputting a string without its surrounding quotes. -There are two ways to unquote a string. - -The `~` operator in front of a string will unquote that string: - - ```less - .class { - // a made up, but problematic vendor specific CSS - filter: ~"Microsoft.AlphaImage(src='image.png')"; - } - ``` - -If you are working with other types, such as variables, there is a built in -function that let's you unquote any value. It is called `e`. - - ```less - @color: "red"; - .class { - color: e(@color); - } - ``` - -### Built In Functions - -**lessphp** has a collection of built in functions: - -* `e(str)` -- returns a string without the surrounding quotes. - See [String Unquoting](#string_unquoting) - -* `floor(number)` -- returns the floor of a numerical input -* `round(number, [precision])` -- returns the rounded value of numerical input with optional precision - -* `lighten(color, percent)` -- lightens `color` by `percent` and returns it -* `darken(color, percent)` -- darkens `color` by `percent` and returns it - -* `saturate(color, percent)` -- saturates `color` by `percent` and returns it -* `desaturate(color, percent)` -- desaturates `color` by `percent` and returns it - -* `fadein(color, percent)` -- makes `color` less transparent by `percent` and returns it -* `fadeout(color, percent)` -- makes `color` more transparent by `percent` and returns it - -* `spin(color, amount)` -- returns a color with `amount` degrees added to hue - -* `fade(color, amount)` -- returns a color with the alpha set to `amount` - -* `hue(color)` -- returns the hue of `color` - -* `saturation(color)` -- returns the saturation of `color` - -* `lightness(color)` -- returns the lightness of `color` - -* `alpha(color)` -- returns the alpha value of `color` or 1.0 if it doesn't have an alpha - -* `percentage(number)` -- converts a floating point number to a percentage, e.g. `0.65` -> `65%` - -* `mix(color1, color1, percent)` -- mixes two colors by percentage where 100% - keeps all of `color1`, and 0% keeps all of `color2`. Will take into account - the alpha of the colors if it exists. See - <http://sass-lang.com/docs/yardoc/Sass/Script/Functions.html#mix-instance_method>. - -* `contrast(color, dark, light)` -- if `color` has a lightness value greater - than 50% then `dark` is returned, otherwise return `light`. - -* `extract(list, index)` -- returns the `index`th item from `list`. The list is - `1` indexed, meaning the first item's index is 1, the second is 2, and etc. - -* `pow(base, exp)` -- returns `base` raised to the power of `exp` - -* `pi()` -- returns pi - -* `mod(a,b)` -- returns `a` modulus `b` - -* `tan(a)` -- returns tangent of `a` where `a` is in radians - -* `cos(a)` -- returns cosine of `a` where `a` is in radians - -* `sin(a)` -- returns sine of `a` where `a` is in radians - -* `atan(a)` -- returns arc tangent of `a` - -* `acos(a)` -- returns arc cosine of `a` - -* `asin(a)` -- returns arc sine of `a` - -* `sqrt(a)` -- returns square root of `a` - -* `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)); - @end: rgbahex(rgba(85, 74, 103, .6)); - // abridged example - -ms-filter: - e("gradient(start=@{start},end=@{end})"); - } - ``` - -## PHP Interface - -When working with **lessphp** from PHP, the typical flow is to create a new -instance of `lessc`, configure it how you like, then tell it to compile -something using one built in compile methods. - -Methods: - -* [`compile($string)`](#compiling[) -- Compile a string - -* [`compileFile($inFile, [$outFile])`](#compiling) -- Compile a file to another or return it - -* [`checkedCompile($inFile, $outFile)`](#compiling) -- Compile a file only if it's newer - -* [`cachedCompile($cacheOrFile, [$force])`](#compiling_automatically) -- Conditionally compile while tracking imports - -* [`setFormatter($formatterName)`](#output_formatting) -- Change how CSS output looks - -* [`setPreserveComments($keepComments)`](#preserving_comments) -- Change if comments are kept in output - -* [`registerFunction($name, $callable)`](#custom_functions) -- Add a custom function - -* [`unregisterFunction($name)`](#custom_functions) -- Remove a registered function - -* [`setVariables($vars)`](#setting_variables_from_php) -- Set a variable from PHP - -* [`unsetVariable($name)`](#setting_variables_from_php) -- Remove a PHP variable - -* [`setImportDir($dirs)`](#import_directory) -- Set the search path for imports - -* [`addImportDir($dir)`](#import_directory) -- Append directory to search path for imports - - -### Compiling - -The `compile` method compiles a string of LESS code to CSS. - - ```php - <?php - require "lessc.inc.php"; - - $less = new lessc; - echo $less->compile(".block { padding: 3 + 4px }"); - ``` - -The `compileFile` method reads and compiles a file. It will either return the -result or write it to the path specified by an optional second argument. - - ```php - echo $less->compileFile("input.less"); - ``` - -The `compileChecked` method is like `compileFile`, but it only compiles if the output -file doesn't exist or it's older than the input file: - - ```php - $less->checkedCompile("input.less", "output.css"); - ``` - -See [Compiling Automatically](#compiling_automatically) for a description of -the more advanced `cachedCompile` method. - -### Output Formatting - -Output formatting controls the indentation of the output CSS. Besides the -default formatter, two additional ones are included and it's also easy to make -your own. - -To use a formatter, the method `setFormatter` is used. Just -pass the name of the formatter: - - ```php - $less = new lessc; - - $less->setFormatter("compressed"); - echo $less->compile("div { color: lighten(blue, 10%) }"); - ``` - -In this example, the `compressed` formatter is used. The formatters are: - - * `lessjs` *(default)* -- Same style used in LESS for JavaScript - - * `compressed` -- Compresses all the unrequired whitespace - - * `classic` -- **lessphp**'s original formatter - -To revert to the default formatter, call `setFormatter` with a value of `null`. - -#### Custom Formatter - -The easiest way to customize the formatter is to create your own instance of an -existing formatter and alter its public properties before passing it off to -**lessphp**. The `setFormatter` method can also take an instance of a -formatter. - -Each of the formatter names corresponds to a class with `lessc_formatter_` -prepended in front of it. Here the classic formatter is customized to use tabs -instead of spaces: - - - ```php - $formatter = new lessc_formatter_classic; - $formatter->indentChar = "\t"; - - $less = new lessc; - $less->setFormatter($formatter); - echo $less->compileFile("myfile.less"); - ``` - -For more information about what can be configured with the formatter consult -the source code. - -### Preserving Comments - -By default, all comments in the source LESS file are stripped when compiling. -You might want to keep the `/* */` comments in the output though. For -example, bundling a license in the file. - -Enable or disable comment preservation by calling `setPreserveComments`: - - ```php - $less = new lessc; - $less->setPreserveComments(true); - echo $less->compile("/* hello! */"); - ``` - -Comments are disabled by default because there is additional overhead, and more -often than not they aren't needed. - - -### Compiling Automatically - -Often, you want to only compile a LESS file only if it has been modified since -last compile. This is very important because compiling is performance intensive -and you should avoid a recompile if it possible. - -The `checkedCompile` compile method will do just that. It will check if the -input file is newer than the output file, or if the output file doesn't exist -yet, and compile only then. - - ```php - $less->checkedCompile("input.less", "output.css"); - ``` - -There's a problem though. `checkedCompile` is very basic, it only checks the -input file's modification time. It is unaware of any files from `@import`. - - -For this reason we also have `cachedCompile`. It's slightly more complex, but -gives us the ability to check changes to all files including those imported. It -takes one argument, either the name of the file we want to compile, or an -existing *cache object*. Its return value is an updated cache object. - -If we don't have a cache object, then we call the function with the name of the -file to get the initial cache object. If we do have a cache object, then we -call the function with it. In both cases, an updated cache object is returned. - -The cache object keeps track of all the files that must be checked in order to -determine if a rebuild is required. - -The cache object is a plain PHP `array`. It stores the last time it compiled in -`$cache["updated"]` and output of the compile in `$cache["compiled"]`. - -Here we demonstrate creating an new cache object, then using it to see if we -have a recompiled version available to be written: - - - ```php - $inputFile = "myfile.less"; - $outputFile = "myfile.css"; - - $less = new lessc; - - // create a new cache object, and compile - $cache = $less->cachedCompile($inputFile); - - file_put_contents($outputFile, $cache["compiled"]); - - // the next time we run, write only if it has updated - $last_updated = $cache["updated"]; - $cache = $less->cachedCompile($cache); - if ($cache["updated"] > $last_updated) { - file_put_contents($outputFile, $cache["compiled"]); - } - - ``` - -In order for the system to fully work, we must save cache object between -requests. Because it's a plain PHP `array`, it's sufficient to -[`serialize`](http://php.net/serialize) it and save it the string somewhere -like a file or in persistent memory. - -An example with saving cache object to a file: - - ```php - function autoCompileLess($inputFile, $outputFile) { - // load the cache - $cacheFile = $inputFile.".cache"; - - if (file_exists($cacheFile)) { - $cache = unserialize(file_get_contents($cacheFile)); - } else { - $cache = $inputFile; - } - - $less = new lessc; - $newCache = $less->cachedCompile($cache); - - if (!is_array($cache) || $newCache["updated"] > $cache["updated"]) { - file_put_contents($cacheFile, serialize($newCache)); - file_put_contents($outputFile, $newCache['compiled']); - } - } - - autoCompileLess('myfile.less', 'myfile.css'); - ``` - -`cachedCompile` method takes an optional second argument, `$force`. Passing in -true will cause the input to always be recompiled. - -### Error Handling - -All of the compile methods will throw an `Exception` if the parsing fails or -there is a compile time error. Compile time errors include things like passing -incorrectly typed values for functions that expect specific things, like the -color manipulation functions. - - ```php - $less = new lessc; - try { - $less->compile("} invalid LESS }}}"); - } catch (Exception $ex) { - echo "lessphp fatal error: ".$ex->getMessage(); - } - ``` -### Setting Variables From PHP - -Before compiling any code you can set initial LESS variables from PHP. The -`setVariables` method lets us do this. It takes an associative array of names -to values. The values must be strings, and will be parsed into correct CSS -values. - - - ```php - $less = new lessc; - - $less->setVariables(array( - "color" => "red", - "base" => "960px" - )); - - echo $less->compile(".magic { color: @color; width: @base - 200; }"); - ``` - -If you need to unset a variable, the `unsetVariable` method is available. It -takes the name of the variable to unset. - - ```php - $less->unsetVariable("color"); - ``` - -Be aware that the value of the variable is a string containing a CSS value. So -if you want to pass a LESS string in, you're going to need two sets of quotes. -One for PHP and one for LESS. - - - ```php - $less->setVariables(array( - "url" => "'http://example.com.com/'" - )); - - echo $less->compile("body { background: url("@{url}/bg.png"); }"); - ``` - -### Import Directory - -When running the `@import` directive, an array of directories called the import -search path is searched through to find the file being asked for. - -By default, when using `compile`, the import search path just contains `""`, -which is equivalent to the current directory of the script. If `compileFile` is -used, then the directory of the file being compiled is used as the starting -import search path. - -Two methods are available for configuring the search path. - -`setImportDir` will overwrite the search path with its argument. If the value -isn't an array it will be converted to one. - - -In this example, `@import "colors";` will look for either -`assets/less/colors.less` or `assets/bootstrap/colors.less` in that order: - - ```php - $less->setImportDir(array("assets/less/", "assets/bootstrap")); - - echo $less->compile('@import "colors";'); - ``` - -`addImportDir` will append a single path to the import search path instead of -overwriting the whole thing. - - ```php - $less->addImportDir("public/stylesheets"); - ``` - -### Custom Functions - -**lessphp** has a simple extension interface where you can implement user -functions that will be exposed in LESS code during the compile. They can be a -little tricky though because you need to work with the **lessphp** type system. - -The two methods we are interested in are `registerFunction` and -`unregisterFunction`. `registerFunction` takes two arguments, a name and a -callable value. `unregisterFunction` just takes the name of an existing -function to remove. - -Here's an example that adds a function called `double` that doubles any numeric -argument: - - ```php - <?php - include "lessc.inc.php"; - - function lessphp_double($arg) { - list($type, $value) = $arg; - return array($type, $value*2); - } - - $less = new lessc; - $less->registerFunction("double", "lessphp_double"); - - // gives us a width of 800px - echo $less->compile("div { width: double(400px); }"); - ``` - -The second argument to `registerFunction` is any *callable value* that is -understood by [`call_user_func`](http://php.net/call_user_func). - -If we are using PHP 5.3 or above then we are free to pass a function literal -like so: - - ```php - $less->registerFunction("double", function($arg) { - list($type, $value, $unit) = $arg; - return array($type, $value*2, $unit); - }); - ``` - -Now let's talk about the `double` function itself. - -Although a little verbose, the implementation gives us some insight on the type -system. All values in **lessphp** are stored in an array where the 0th element -is a string representing the type, and the other elements make up the -associated data for that value. - -The best way to get an understanding of the system is to register is dummy -function which does a `var_dump` on the argument. Try passing the function -different values from LESS and see what the results are. - -The return value of the registered function must also be a **lessphp** type, -but if it is a string or numeric value, it will automatically be coerced into -an appropriate typed value. In our example, we reconstruct the value with our -modifications while making sure that we preserve the original type. - -The instance of **lessphp** itself is sent to the registered function as the -second argument in addition to the arguments array. - -## Command Line Interface - -**lessphp** comes with a command line script written in PHP that can be used to -invoke the compiler from the terminal. On Linux and OSX, all you need to do is -place `plessc` and `lessc.inc.php` somewhere in your PATH (or you can run it in -the current directory as well). On windows you'll need a copy of `php.exe` to -run the file. To compile a file, `input.less` to CSS, run: - - ```bash - $ plessc input.less - ``` - -To write to a file, redirect standard out: - - ```bash - $ plessc input.less > output.css - ``` - -To compile code directly on the command line: - - ```bash - $ plessc -r "@color: red; body { color: @color; }" - ``` - -To watch a file for changes, and compile it as needed, use the `-w` flag: - - ```bash - $ plessc -w input-file output-file - ``` - -Errors from watch mode are written to standard out. - - -## License - -Copyright (c) 2012 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 -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 -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - -*Also under GPL3 if required, see `LICENSE` file* - |