The following is a list of known differences between the Squarespace LESS compiler and less.js 1.7.0.
The compiler accepts a per-compile compatibility level that selects how many legacy behaviors ("patches") are fixed: level 0 keeps every legacy behavior active, preserving the previous release's behavior surface, and at level N every patch whose threshold is at most N is fixed. The highest level is the fully-fixed compiler.
LessOptions opts = new LessOptions();
opts.compatLevel(0); // released behavior: no fixes, every legacy behavior active
opts.compatLevel(1); // level-1 fixes applied (BUG1..BUG4)
opts.compatLevel(2); // fully fixed: every fix applied
LessContext ctx = new LessContext(opts);
new LessCompiler().compile(raw, ctx);
Current patches, by threshold:
Threshold 1 - legacy generation 1 (the former safe-mode tolerances, see docs/legacy-bugs.md; active below level 1):
BUG1- extraneous'+'at block scope is tolerated.BUG2- a@mediadirective without a following block is dropped and the statements that follow attach to the enclosing block.BUG3- a variable reference followed by empty parentheses (@var();) is accepted.BUG4- invalid addition expressions such asrandom(90) + pxare tolerated.
Threshold 2 - legacy generation 2 (gated bug fixes; active below level 2):
SELECTOR_COMPLEXITY_OVERFLOW- selector-combine overflow is swallowed and the current selector is dropped instead of failing the compile.IMPORT_URL_INLINE-@import url("x.less")is emitted literally instead of being resolved and inlined.NONFINITE_AS_ZERO- NaN and Infinity values render as0instead of visible text.MOD_ZERO_STRICT-mod(x, 0)silently returns NaN instead of obeying the division contract (strict fails, lenient warns).CONVERT_INCOMPATIBLE_UNITS-convert()to an incompatible unit silently emits 0 instead of failing the compile.REPLACE_REGEX_GROUPS-replace()treats$and\in the replacement as regex group references instead of inserting them literally.VARIADIC_NAMED_ARG- a named arg targeting the variadic parameter fails with ARG_NAMED_NOTFOUND instead of binding to it.ARGUMENTS_ORDER-@argumentsfollows binding insertion order instead of parameter declaration order.GUARD_COMPARE_UNCOMPARABLE- uncomparable guard operands compare as -1, so<,<=and!=evaluate true (the released truth table, pinned by the compat matrix; at the fixed level only<stays true).IMPORT_EXT_CASE-@importextensions match case-sensitively.IMPORT_ONCE_SUPPRESS- a plain import caching the file first defeats a later@import-once, which re-inlines the file.COLOR_BLEND_ALPHA- color-blend results are opaque instead of keeping the larger input alpha.COLOR_CHANNEL_PRECISION- color channel math truncates fractional intermediates before the final rounding.ATTR_SELECTOR_UNTERMINATED- an unterminated attribute selector or parenthesized element is silently dropped instead of failing the compile.NUMBER_EXPO- numeric values have no exponent:1e3tokenizes as the number1and the identifiere3(emitted literally, invalid CSS), and7E705Eas7andE705E. At level 2,1e2,2E2and1.5e-3parse as single numbers;em/exunits are unaffected (eis an exponent only when a digit follows).FUNCTION_CALL_IN_VALUE- a wired context (a compiler attached viactx.setCompiler) renders function calls literally with their arguments evaluated below level 2, at every position a call can evaluate: value positions, font shorthand (either side of the/), and directive values, matching the bare context (no function table), which is unaffected at every level; calls are never math operands. At level 2 the same calls evaluate against the function table. Guards need level 2:operand()suppresses the call below it, the condition fails to parse, and a parenthesized call that survives stays an incomparable literal the comparison rejects with UNCOMPARABLE_TYPE. Selectors never evaluate the node, so a call in a parenthesized selector value renders as written in both contexts at every level. Wired consumers that want evaluated calls compile at level 2.
At level 0 every legacy behavior is active. At level 1 the threshold-1 patches are fixed. At level 2 every patch is fixed. The fix ladder is pinned by CompatPatchTest and CompatLevelTest.
Per-site patches can be forced on for stylesheets that need an irregular combination the ladder cannot express:
opts.compatPatch(Patch.BUG2);
New fixes ship with a legacy path gated by a new patch at a new higher threshold, so higher levels apply more fixes without changing the released surface at level 0. Patches are retired when the last site that needs them migrates to their threshold level or above.
For backwards compatibility, the parser's boolean safeMode() flag is the
recovery-mode flag (see below): true = best effort, false (default) =
strict. It is independent of the compat level, which is set exclusively via
LessOptions.compatLevel(int). Legacy note: on the released 1.7.2 compiler
the 2-arg compile(raw, ctx) / parse(raw, ctx) entry points defaulted to
safeMode=true. Here they apply no mode override (the options default:
strict, level 0) — parser-equivalent to released behavior at level 0, but
with no recovery; callers that want recovery must pass the flag explicitly
or set opts.safeMode(true).
A second, orthogonal axis to the compat level: what happens when the compiler must reject something. The compat level decides what is fixed; the mode decides how violations behave.
-
strict (default,
safeMode(false)): any hard error aborts the compile with aLessException— released behavior. -
safe (
safeMode(true)): best effort. The offending construct is dropped at a well-defined boundary, aWARNING[n] ... raised during recovery: ...comment is emitted, and compilation continues:- parser: the stream is resynchronized at well-defined boundaries —
a well-formed statement that follows the error (including a complete
top-level block) is re-parsed and kept; only the broken region is
dropped; an unterminated tail is truncated; input that recovers to
nothing is a hard error even in safe mode (
stylesheet produced no output) — a blank stylesheet never ships on a green build, and genuinely empty input still compiles to empty output (released behavior); comments do not count as output for this check, so a sheet that is comments + fully-broken input errors too; - evaluation: a failed block member (rule, mixin call, ...) is dropped and the next sibling is evaluated;
- render: a node that fails to render is skipped;
- complexity overflow: the combined selector is truncated at the limit and the rule body is kept.
The released surface is level 0 + strict; level 0 + safe behaves identically until something must be rejected, then it degrades with warnings instead of failing — production keeps rendering while the warning stream is the migration ledger. The matrix of (patch x level x mode) outcomes is pinned by RecoveryMatrixTest.
- parser: the stream is resynchronized at well-defined boundaries —
a well-formed statement that follows the error (including a complete
top-level block) is re-parsed and kept; only the broken region is
dropped; an unterminated tail is truncated; input that recovers to
nothing is a hard error even in safe mode (
The NONFINITE_AS_ZERO patch is fixed at level 2: non-finite math values
(NaN, Infinity) render as visible text there, same as less.js. At the
released levels (below 2) they render as 0:
y: sqrt(-1); /* level 0 (released) -> 0; level 2 (fixed) -> NaN */
y: pow(0, -1); /* level 0 (released) -> 0; level 2 (fixed) -> Infinity */
Modulo by zero follows the same contract as division: strict mode fails the
compile, lenient mode warns, and the NaN result renders according to the
level (see MOD_ZERO_STRICT).
foo: blue + 1;
foo: blue + red;
foo: alpha(opacity=.7)
foo: alpha(opacity=0.35)
Squarespace LESS renders non-integer numbers with at most 8 decimals
(Buffer.DEFAULT_PRECISION), rounding to the nearest value with ties going
to the even neighbor (RoundingMode.HALF_EVEN), then strips trailing zeros:
x: 123.456456456456; /* -> 123.45645646 (rounded to 8 decimals) */
x: 0.500000001; /* -> 0.5 (trailing zeros stripped) */
A leading zero is also dropped for values with magnitude less than 1:
x: 0.4; /* -> .4 */
rgba(0, 0, 0, 0.4); /* -> rgba(0, 0, 0, .4) */
less.js 1.7.0 instead emits the number in its full JavaScript double representation, with no default rounding or zero stripping:
x: 123.456456456456; /* -> 123.456456456456 */
x: 0.4; /* -> 0.4 */
This behavior is tested by the files in the test suite
(dimension.css, css-3.css).
Squarespace LESS allows the use of both >= and => forms for
greater-or-equal-to, <= and =< for less-or-equal-to conditions, as well as
!= for not-equal condition:
.mixin-1 (@foo, @bar) when (@foo >= 20px), (@bar => 20px) { }
.mixin-2 (@foo, @bar) when (@foo <= 20px), (@bar =< 20px) { }
.mixin-3 (@foo) when (@foo != 2) { }
For example, comments between selectors:
h1 /* a */ span:hover /* b */ {
color: /* c */ red;
}
Squarespace LESS:
h1 span:hover {
color: /* c */ red;
}
less.js:
% lessc-1.7.0 comment.less
ParseError: Unrecognised input in comment.less on line 24, column 12:
23
24 h1 /* a */ span:hover /* b */ {
25 color: /* c */ red;
A @media directive that is not followed by a block is silently dropped in
safe mode, and the statements that follow it attach to the enclosing block:
@media only screen and (max-width: 640px)
#content {
padding-top: 50px;
}
Squarespace LESS (safe mode):
#content {
padding-top: 50px;
}
less.js:
% lessc-1.7.0 bug2.less
ParseError: Unrecognised input in bug2.less on line 1, column 1:
1 @media only screen and (max-width: 640px)
2 #content {
This leniency is intentional legacy compatibility: production stylesheets
containing unclosed or block-less @media directives must keep compiling
(see docs/legacy-bugs.md, BUG2, for the affected sites). It applies only in
safe mode, which is the default for both LessCompiler.parse() and
LessCompiler.compile(). With safe mode disabled the same input fails the
compile.