Feature request: the `@options` directive

[jonschlinkert]

This is something I've wanted since first using LESS, and I think I've come up with a solution that could be pretty awesome if we get some feedback and tweak it to get the kinks out.

Proposal, Part 1: The @options directive

I propose that we use the @options directive to allow setting processing options directly inside less files themselves, like this:

@options {
  // options
}

As with media queries, the @options directive wraps a declaration block which contains the options/flags for how you want your less to compile. When this directive is found, less.js reads in the options and processes all less files accordingly. If multiple @options directives are identified, less.js either throws an error or it uses the options from the last directive (I'll leave that decision to others). If the latter is chosen and multiple @options directives can exist simultaneously, my suggestion would be to process it like this:

If multiple @options directives could co-exist:

First directive identified...

@options {
  paths: "";
  rootpath: "";
  relativeUrls: "false";
  strictImports: "false";
  compress: "false";
  yuicompress: "true";
  optimization: "1";
  silent: "false";
  lint: "false";
  color: "true";
}

Second directive identified

@options {
  compress: "true"; // less.js uses `compress: "true"`, but leaves the other options in tact
}

Another suggestion would be to use !important to designate which options should not be overridden.

Why would multiple @options directives exist? A good use case is that when importing external libraries, such as Twitter Bootstrap, you may wish to override the options from that library.

Regardless of how it's actually implemented, what I find so compelling about this concept is that it paves the way for keeping the syntax and language cleaner, it keeps options closer to the less files, and forces a stronger separation of concerns between processing/compiling features and language features. To that end, I often see feature requests or Issues where the OP is asking for something to be added to the language, when really all that is needed is a new processing/compiling option. LESS is a language, but less.js is a compiler! This makes that distinction much clearer, and it allows for the user to store different options across different projects, either directly inside a single less file, in several less files, or even organized in options.less files that can be reused across projects. Whichever you prefer, it's a better approach than putting those options in a json file or javascript.

see: #850

Proposal, Part 2: Setting "Contexts" with the @options directive

With this proposal, "context" is created in a kind of similar way to setting context in "logic-less" templating languages, such as mustache. So, for instance, rather than hard-coding processing options in @import or @include directives, we would instead use "contexts" so that the choice is made by the developer, and they have the choice of setting the options in the less files themselves or on-the-fly at compiling time.

@options("default") {
  paths: "";
  rootpath: "";
  relativeUrls: "false";
  strictImports: "false";
  compress: "false";
  yuicompress: "true";
  optimization: "1";
  silent: "false";
  lint: "false";
  color: "true";
}

(and how awesome would it be to be able to use variables in paths and rootpaths now that we are storing those properties in our less files!)

A common use case is to create contexts for environments, like development and production, so that less.js (env) processes the options according to how they are defined in the less files themselves:

@options("dev") {
  compress: "false";
}

and...

@options("prod") {
  compress: "true";
}

Applying contextual options in your less files

Media queries are a great starting point for inspiration, for example:

@media (min-width: 768px) and (max-width: 979px) {
  .row {
    margin-left: -20px;
    zoom: 1;
  }
}

And CSS syntax already allows us flexibility with media queries with @import and @media, like:

@import url(example.css) screen and (color), projection and (color) { // declarations };

// and

@import url("phone.css") only screen and (max-width:400px) { // declarations };

// and

@media screen and (color), projection and (color) { // declarations }

And written in HTML, XHTML, XML, @import and @media:

<link rel="stylesheet" media="screen and (color), projection and (color)" rel="stylesheet" href="example.css">

So following convention established by @imports and media queries, here are some ideas for how we can take the contexts we created using the @options("context") directive and apply them throughout our less stylesheets:

@context("prod") {
  .some-experimental-class {
    display: none;
  }
  .sidebar {
    width: 250px;
  }
  ...
}

and...

@context("dev") {
  .some-experimental-class {
    display: block;
  }
  .sidebar {
    width: 210px;
  }
  ...
}

This gives us the choice to extend the directive in the future:

@context ("experimental") and (some-rule: true) { // declarations }

// and

@context all and (some-rule: true) { // declarations }

As with media queries, these would be equivalent:

@context all { // declarations }
@context { // declarations }

Or, for example, we could set the "contexts" from our @options on other directives like this:

@import:dev "forms.less"

// or

@import("dev") "forms.less"

// or

@import:context("dev") "forms.less"

// or

@import:options("dev") "forms.less"

Example of other Issues that could be resolved with this:

• support for default variables: Added support for default variables #1104
• Added support for default variables #1104
• Importing - Both CSS and Less SomMeri/less4j#19
• @include: @include .css file contents #560

I would solve the @include issue like this:

@options("dev") {
  css: "passthrough"; // or some more elegant way of describing it
}

and...

@options("prod") {
  css: "append";
}

or maybe just...

@options("prod") {
  concatenate: "true"; // which would apply to both css and less.
}

Last, it's understood that @options could collide with custom variables, so either 1) bake it in as a reserved word and force people to not use that as a variable name, 2) allow @options: variable and @options {} to co-exist peacefully, or 3) we just use a different namespacey term than @options. I like #2 the most, alternatively #1.

[dpashkevich]

Why would multiple @options directives exist? A good use case is that when importing external libraries, such as Twitter Bootstrap, you may wish to override the options from that library.

So this means if I import an external library, it can mess up compiler settings for my files unless I override them. I believe that's undesired behavior. If multiple @options declarations can exist, I think they need to be scoped somehow (file scope? like it's the case with js linters). If only one @options declaration can exist, then we're only trying to agree here on the format for storing compiler options in an external file (that can be used by multiple tools, e.g. grunt-based build system).

As for Part 2 of the proposal, to me this looks more like a compiler argument that would allow specifying the necessary options file at run time. So far the proposal a bit complicated to me, don't you think that build configuration (the use case implied from your examples) should be defined at the level of build tools, not at the level of, in this case, .less files themselves?

[jonschlinkert]

"So this means if I import an external library, it can mess up compiler settings for my files unless I override them."

Lol hey @dpashkevich, you make it sound like so much work!

1. How is adding a single @options directive to a project any more complicated than adding any other custom style to your project? It's a lot like adding a .jshintrc to a project.
2. This only needs to be done if you want to override external options.
3. You already have to do this when you use a build tool, like Grunt (which you mention later). And since I specified that the last options win, it makes sense that the build tool could specify options and they would win.
4. If none of those answers work, we could add the ignoreOptionsDirective: true flag to less so that @options are ignored by default

"I think they need to be scoped somehow" agreed. it seems to me that this is addressed with "contexts" as I suggested, or am I missing something. If I am, maybe you can help me come up with a better way of scoping? In any case, scoping can't be done at all today, so this is a step in the right direction

"If only one @options declaration can exist, then we're only trying to agree here on the format for storing compiler options in an external file" yeah, that's what I was thinking. that's why I prefer the ability to store multiple directives, similar to media queries. I don't think it makes sense to require only one @options directive. I mean where would you put it?

"don't you think that build configuration (the use case implied from your examples) should be defined at the level of build tools" Yes, this doesn't preclude that. As I mention above you can still specify options in your build tool. However, you and I have collaborated quite a bit on build tool stuff, Grunt in particular. And build tools couldn't possibly achieve what this directive could regarding contexts. Meaning the ability to create contexts throughout the stylesheets so that regardless of the compiler the .css files compile as expected. Think about how mustache works, and how you can do (for starters):

{{#production}}
<script type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>
{{/production}}

and that script will only show up in the compiled result when production context = true. So how would a build process actually create that context for you as well? Someone actually has to wrap the production context around the script in the .html or .mustache file before the compiler could do anything with it. It works the same with my proposal for context, you could use @options inside your .less files or in the build tool or both allowing you to compile those contexts however you want, with whatever build tool you want.

@dpashkevich thanks for the feedback, and aren't you a SASS fan? jk :)

[matthew-dean]

@jonschlinkert Thanks so much for picking this back up. This is pretty important to me, because 1) it allows a LESS tool to "save" things like output file so that the "link" to a CSS file is preserved (good for GUIs like Crunch), and 2) it facilities working in teams (all members of the team have the same options for working with that LESS library.

Originally, I, too had thought that embedding this inline in a LESS file was the best way to go, then was persuaded for different reasons that it should be an external JSON, but you make some good arguments to keep it in LESS.

I think my two favorite and most persuasive reasons to keep it in LESS are:

1. The syntax is familiar to LESS devs. It looks and feels CSS/LESS-like.
2. On the LESS time, we've established that while LESS is a JavaScript parser, the language should be script-agnostic. For this reason, we've been deprecating inline JavaScript (to address support for PHP or C#-based parsers), so it seems a step back to use JavaScript object notation for configuration.

I think the reason I was swayed was that you could use one config file to apply to multiple "root" LESS files, but I think that's an edge case. PLUS.... on the other hand... you are giving instructions to the parser.... so there's probably trade-offs either way.

I think this is great work, but can you address the additional options / configuration that I laid out in issue #850? Specifically, setting (saving) an output CSS file? What is your proposed syntax?

Also, would love to see @agatronic's thoughts.

[jonschlinkert]

I just realized I didn't even put any thoughts on how this would work in the command line, but my thinking was that you might create a context as described above, say @options("dev") { // declarations } and then in the command line lessc --dev.

by the way, @MatthewDL I'd love to run something (mostly) unrelated by you, can I get in touch?

[matthew-dean]

@jonschlinkert Yes, sent you an email just now. You can also get in touch via http://matthewdean.me/

[lukeapage]

1. I am not sure about : if you want to set options in your less you have to either have an import or indent the entire file.
2. Not sure on its relevance to Added support for default variables #1104, which was closed since the we already provide a mechanism to solve the problem
3. what is the use case for needing to apply different options to different sections? For most of the options this doesn't make sense. I can't think of any options that a library would want to set (apart from how to handle the import)
4. in terms of other compilers, other compilers (and less.js) already have a set of options specific to their implementation

dis-regarding how to handle an import statement (include or not) my thoughts would be that the configuration should live in the build process. e.g. if I move from one domain to another and need to set a different rootpath, I would think that I should modify my build/deployment parameters, not my less files.

I think where your spec falls down is on its simplicity to specify whether an import is a less file or a css file - you have to use an option instead of being able to simply tell the compiler what it is you are importing (which won't change) - I would like to specify in a clear, simple (and consistent across less files and libraries) way whether the file you want to include is css (which may or may not be valid less) and less.

It's very nice and elegant but I don't see the problem it is trying to solve (other than @include/@import which I think would be better done with simply specifying whether it is css or less and then having an option allowing you include/not include the css)

Could you go into more detail about what the problem is / why you have always wanted this?

[lukeapage]

re-reading the original issue, I've changed it back to high priority and would like to maybe just suggest the following changes

1. having an extra options.less is a nice idea, and having that able to be consumed by less, I don't have a problem with. Extracting that further and saying the options can be included in the main file or an additional file, I think is fine. can we have it so that @options { compress: true } effects everything?
2. presumably we disallow someone doing this @options { compress: @compress } - because that would mean you need to eval @compress but to do the eval you need the options and then you get into a cycle
3. also.. the options ordering would be important, for the same reason as (2)
4. We would encourage libraries to not do @import options.less - if they do this it causes major headaches for people consuming the library, they need to then override the options and then you end up having to have an option as to whether you override the options
5. because of (4) you would presumably have to be able to process both the main less file and an options file at the same time, so for instance bootstrap can have their own options without causing headaches for everyone using bootstrap
6. As I said, I would still have a way to distinguish between less and css in imports that is not an option - just because I don't see it as an option, I see it as something that should be specified about every single @import - just that at the moment it is specified by looking at the filename ending.

[jonschlinkert]

@agatronic you make some really great points. I've read through everything and I'll put some comments and questions up as soon as I have a chance in the next day or two. But in the meantime, after reading some of your points I think that in general whatever solution we end up with ought to be clean and straightforward, and hopefully not come with any warnings or gotchas. Your suggestions will help achieve that, so give me some time to think it over and I'll come back with some ideas to get your feedback.

[lukeapage]

@jonschlinkert thanks, hope I wasn't too negative, I'm just trying to give a 2nd point of view. Look forward to hearing your comments here and on any other bug.

[jonschlinkert]

@agatronic no not in the least, I think your comments are really constructive, and thank you. I just haven't had a chance before now to give a thoughtful response... I will definitely be spending more time here.

I'm still considering some of the points you made about options, and one thing that is at the top of my mind is use cases where this could either help or hinder with external libraries. I've created some project scaffolds and test scenarios with Gruntjs over the last couple of days. This will sound a little crazy, but it's working - just for proof of concept I externalized less options to a few .lessrc json files, and I'm using mustache inside the less files to create contexts, and then testing out different build configurations that conditionally "include" or "exclude" certain LESS and CSS styles and imports based on the mustache contexts.

One thing this has accomplished is that it made me realize this should have been two requests. So I think we should narrow down this request to just the @options directive, and for now let's disregard the context part, it's use cases are materially different than the uses cases of the @options directive. so rather than answering to your questions here, once I've spent some time with test scenarios for the context concept I'll create a new Issue and address the questions you asked there.

I'll be back with more answers...

[jonschlinkert]

@agatronic, one thing I am curious about though, and this will definitely influence some of my ideas on this...

You said, "presumably we disallow someone doing this @options { compress: @compress }", to be clear, you're saying that variables inside the @options block would not be allowed, correct?