Less language is an extension of css and this project compiles it into regular css. It adds several dynamic features into css: variables, expressions, nested rules, and so on. Our documentation contains both overview of all these features and links to their detailed descriptions. If you are interested in the language itself, we recommend to start with the overview.
The original compiler was written in JavaScript and is called less.js. Official less is mostly defined in less.js documentation/issues and by what less.js actually do. Links to less.js:
Less4j is a port and its behavior should be as close to the original implementation as reasonable. Unless explicitly stated otherwise, any difference between less.js and less4j outputs is considered a bug. As close as reasonable means that style sheets generated by less4j must be functionally the same as the outputs of less.js. However, they do not have to be exactly the same:
All known differences are documented on wiki page. Less4j also produces warnings any time it produces functionally different CSS.
Continuous integration is set up on Travis-CI, its current status is: .
Our twitter account: Less4j
The documentation is kept on Github wiki:
For those interested about project internals, architecture and comments handling are described in a [blog post] (http://meri-stuff.blogspot.sk/2012/09/tackling-comments-in-antlr-compiler.html). The blog post captures our ideas at the time of its writing, so current implementation may be a bit different.
Less4j can run from command line. Latest versions are shared via less4j dropbox account. Shared folder always contains at least two latest versions, but we may remove older ones.
If you need an old version for some reason, checkout appropriate tag from git and use mvn package -P standalone
command. The command compiles less4j and all its dependencies into target/less4j-<version>-shaded.jar
file.
Less4j is available in Maven central repository.
Pom.xml dependency:
<dependency>
<groupId>com.github.sommeri</groupId>
<artifactId>less4j</artifactId>
<version>1.17.2</version>
</dependency>
The easiest way to integrate less4j into Java project is to use wro4j library. More about wro4j can be found either in a blog post or on wro4j google code page.
Access the compiler through the com.github.sommeri.less4j.LessCompiler
interface. The interface exposes following methods:
compile(File inputFile)
- compiles a file. Import statements are assumed to be relative to that file.compile(URL inputFile)
- compiles resource referenced through url. It supports all protocols supported by java.lang.URL e.g. http, https, jar, ftp, gopher and mail.compile(String lessContent)
- compiles a string. Compiler will be unable to load imported files, less @import statements are compiled into css @import statement instead of being processed.compile(LessSource inputFile)
- compiler uses LessSource
interface to fetch imported files. It can be used to load less sheets from arbitrary source, e.g., database or npm.Less4j provides three implementations of compiler interface:
ThreadUnsafeLessCompiler
- Core implementation of the compiler. It is thread unsafe.DefaultLessCompiler
- Thread safe wrapper of the above.TimeoutedLessCompiler
- Less compiler with timeout. If the compilation does not finish within specified time limit, compiler returns an error. You can use this to stop the compiler before it consumes too much resources on infinitely looping mixins or large less sheets.Note: a common need is to add search paths for import statements e.g., functionality similar to less.js --include-path option. This is possible using the last method.
Each of these method has an additional optional parameter Configuration options
. Additional options allow you to configure generated source map, add custom functions and add embedded scripting into to compiler.
Return object CompilationResult
has three methods:
getCss
- returns compiled css,getSourceMap
- returns source map,getWarnings
- returns list of compilation warnings or an empty list. Each warning is described by message, line, character number and filename of the place that caused it.
// create input file
File inputLessFile = createFile("sampleInput.less", "* { margin: 1 1 1 1; }");
// compile it
LessCompiler compiler = new ThreadUnsafeLessCompiler();
CompilationResult compilationResult = compiler.compile(inputLessFile);
// print results to console
System.out.println(compilationResult.getCss());
for (Problem warning : compilationResult.getWarnings()) {
System.err.println(format(warning));
}
private static String format(Problem warning) {
return "WARNING " + warning.getLine() +":" + warning.getCharacter()+ " " + warning.getMessage();
}
Compile
method may throw Less4jException
. The exception is checked and can return list of all found compilation errors. In addition, compilation of some syntactically incorrect inputs may still lead to some output or produce a list of warnings. If this is the case, produced css is most likely invalid and the list of warnings incomplete. Even if they are invalid, they still can occasionally help to find errors in the input and the exception provides access to them.
List<Problem> getErrors
- list of all found compilation errors.CompilationResult getPartialResult()
- css and list of warnings produced despite compilation errors. There is no guarantee on what exactly will be returned. Use with caution. Less4j can be customized in three different ways:
Featured plugin: less4-javascript plugin which adds embedded/escaped JavaScript support to less4j.
Less4j is distributed under following licences, pick whichever you like: