lass
0.6.0Lisp Augmented Style Sheets. Compiles LASS to CSS.
Table of Contents
About LASS
Writing CSS files comes with a lot of repetition and is generally much too verbose. With lispy syntax, shortcuts, and improvements, LASS aims to help you out in writing CSS quick and easy. LASS was largely inspired by SASS.
How To & Examples
LASS supports two modes, one being directly in your lisp code, the other in pure LASS files. Adding LASS into your code is easy:
(lass:compile-and-write
'(div
:background black))
"div{
background: black;
}"
LASS works on the following simple principles: A list is a block. The first argument in the list is a selector. The body of the list makes up the properties and sub-blocks. A property is started with a keyword that is used as the property name. Following is a bunch of property arguments until a new keyword, list, or the end is reached. A list inside a block is, again, a block with the twist that the parent block's selector is prepended to the sub-block's selector.
(lass:compile-and-write
'(nav
(ul
:list-style none
(li
:margin 0 :padding 0
:display inline-block)))))
"nav ul{
list-style: none;
}
nav ul li{
margin: 0;
padding: 0;
display: inline-block;
}"
Since LASS' COMPILE-SHEET
simply takes a bunch of lists as its argument, you can use the backquote and comma to integrate variables from your lisp environment:
(let ((color "#0088EE"))
(lass:compile-and-write
`(div
:background ,color))))
"div{
background: #0088EE;
}"
Alternatively however, and this is especially useful in pure LASS files, you can use the LET
block to create LASS-specific bindings:
(lass:compile-and-write
'(:let ((color "#0088EE"))
(div
:background #(color))))
"div{
background: #0088EE;
}"
You can also let bind entire property blocks:
(lass:compile-and-write '(:let ((colors :background "#0088EE")) (div #(colors)) (:media "(prefers-color-scheme: light)" (div #(colors)))))
"div{
background: #0088EE;
}
@media (prefers-color-scheme: light){
div{
background: #0088EE;
}
}"
LASS' selector mechanism is very flexible and allows for some complex logic to reduce duplication:
(lass:compile-and-write
'(article
((:or p blockquote)
:margin 0 :padding 0
(a
:color black)
((:and a :hover)
:color darkred))))
"article p, article blockquote{
margin: 0;
padding: 0;
}
article p a, article blockquote a{
color: black;
}
article p a:hover, article blockquote a:hover{
color: darkred;
}"
But it can go even further:
(lass:compile-and-write
'((:and
(:or article section)
(:= data-author (:or yukari ran chen))
(:nth-child (:or 1 2 3)))
:display none))
"article[data-author=\"yukari\"]:nth-child(1),
article[data-author=\"yukari\"]:nth-child(2),
article[data-author=\"yukari\"]:nth-child(3),
article[data-author=\"ran\"]:nth-child(1),
article[data-author=\"ran\"]:nth-child(2),
article[data-author=\"ran\"]:nth-child(3),
article[data-author=\"chen\"]:nth-child(1),
article[data-author=\"chen\"]:nth-child(2),
article[data-author=\"chen\"]:nth-child(3),
section[data-author=\"yukari\"]:nth-child(1),
section[data-author=\"yukari\"]:nth-child(2),
section[data-author=\"yukari\"]:nth-child(3),
section[data-author=\"ran\"]:nth-child(1),
section[data-author=\"ran\"]:nth-child(2),
section[data-author=\"ran\"]:nth-child(3),
section[data-author=\"chen\"]:nth-child(1),
section[data-author=\"chen\"]:nth-child(2),
section[data-author=\"chen\"]:nth-child(3){
display: none;
}"
Whoa nelly!
If you ever need to expand a selector into a parent block, for instance to specialise on different classes of the block, you can use the parent pseudo-selector:
(lass:compile-and-write
'((:or article section)
:background black
((:parent .bright)
:background white)))
"article,
section{
background: black;
}
article.bright,
section.bright{
background: white;
}"
Some CSS properties are not fully specified yet and require browser-specific prefixes. LASS can help you with that, too:
(lass:compile-and-write
'(.fun
:linear-gradient "deg(45)" black 0% darkgray 100%
:transform rotate -45deg))
".fun{
background: -moz-linear-gradient(deg(45), black 0%, darkgray 100%);
background: -o-linear-gradient(deg(45), black 0%, darkgray 100%);
background: -webkit-linear-gradient(deg(45), black 0%, darkgray 100%);
background: -ms-linear-gradient(deg(45), black 0%, darkgray 100%);
background: linear-gradient(deg(45), black 0%, darkgray 100%);
-moz-transform: rotate(-45deg);
-o-transform: rotate(-45deg);
-webkit-transform: rotate(-45deg);
-ms-transform: rotate(-45deg);
transform: rotate(-45deg);
}"
LASS also supports the various @QUERY
operator blocks:
(lass:compile-and-write
'(:media "(max-width: 800px)"
(div
:margin 0)))
"@media (max-width: 800px){
div{
margin: 0;
}
}"
By default LASS activates pretty-printing and inserts newlines and spaces where appropriate in order to make the result readable and easy to debug. However, you can also deactivate that and directly produce minified CSS:
(let ((lass:*pretty* NIL))
(lass:compile-and-write
'(:media "(max-width: 800px)"
(div
:margin 0))))
"@media (max-width: 800px){div{margin:0;}}"
As mentioned above you can write pure LASS files to compile down to a CSS file. To do that, simply use GENERATE
:
Blocks
Each block in a LASS sheet consists of a list containing a selector followed by one or more properties or sub-blocks.
(selector [property | block]*)
Selectors
The following list contains examples for the various uses of selectors.
- Any element
*
- An element with tag-name
e
e
- An element with tag-name
e
orf
(:or e f)
- An
e
element with the:link
pseudo-selector
(:and e :link)
- The first formatted line of an
e
element
(:and e |::first-line|)
or(:and e "::first-line")
- An
e
element with a "warning" class
e.warning
- An
e
element with ID equal towarning
|e#warning|
or"e#warning"
- An
e
element with afoo
attribute
e[foo]
- An
e
element whosefoo
attribute value is exactly equal tobar
(:and :a (:= foo "bar"))
- An
e
element whosefoo
attribute value is a list of whitespace-separated values, one of which is exactly equal tobar
(:and :a (:~= foo "bar"))
- An
e
element whosefoo
attribute has a hyphen-separated list of values beginning (from the left) withbar
(:and :a (:/= foo "bar"))
- An
e
element whosefoo
attribute value begins exactly with the stringbar
(:and :a (:^= foo "bar"))
- An
e
element whosefoo
attribute value ends exactly with the stringbar
(:and :a (:$= foo "bar"))
- An
e
element whosefoo
attribute value contains the substringbar
(:and :a (:*= foo "bar"))
- An
e
element that matches the pseudo-selectornth-child(2)
(e (:nth-child 2))
- An
f
element preceded by ane
element
(e ~ f)
- An
f
element immediately precede by ane
element
(e + f)
- An
f
element which is a descendant ofe
(e f)
- An
f
element which is a direct descendant ofe
(e > f)
Selector Combinations
As illustrated briefly above, LASS includes two combinators for selectors, :and
and :or
. These combinators are combinatoric, meaning that all possible combinations are explored. Consider the following selector:
((foo (:and a .title (:or :active :hover)) (:or span div)))
Enumerating all possible answers to this combination would result in the following list
foo a.title:active span
foo a.title:active div
foo a.title:hover span
foo a.title:hover div
The number of possible combinations can quickly explode in size the more options are available. This means that for complex relations and expressions, LASS can be extremely concise. Note that combinators are available at any position in a selector, this includes the arguments of a pseudo-selector like :nth-child
.
Properties
A property consists of a keyword symbol and a sequence of values. The values to a property are gathered up until either a non-value list or a new keyword is encountered. Originally it stopped as soon as a list was encountered, but this behaviour was changed and specially recognised lists are integrated to allow a more native look for certain values like colours, urls, and so on. Certain properties are specifically declared and will error if they are passed the wrong number or invalid kind of values. For most however, LASS will just blindly put things into the CSS file as you give them. It is up to you to make sure that the values are valid.
:text-style underline
:color (rgb 212 112 30)
:background (url "/foo")
:border 1px solid black
Certain properties currently still require vendor-specific declarations. LASS tries to do that automatically for you, but it also needs to know about these declarations and as such, they need to be manually added. Some of the more common ones are included in LASS by default, but if you encounter one that isn't, you are welcome to send a pull request (see Extending LASS on how to do it).
Sub-Blocks
A block can contain other blocks. These sub-blocks are recursively flattened into the structure by simply prepending the selector of the parent block. Thus
(foo (bar (baz) (bam)))
Is equivalent to
(foo) ((foo bar)) ((foo bar baz)) ((foo bar bam))
Allowing this kind of nesting allows you to more closely mirror the structure present in your HTML file that you want to style. Combining this with the selector combinations, this system allows reducing code duplication a lot.
Special Blocks
In CSS3 there are special properties and blocks that are preceded by an @
symbol. The most well-known examples therefore are probably @include
and @media
. LASS implements all of these special blocks by a keyword symbol equivalent selector. Therefore the above two would translate to the following in LASS.
(:include (url "foo"))
(:media "(max-width: 800px)"
(foo))
Variables
Often times it is useful to define variables that you can use within your style so that colours and fonts can quickly be exchanged. LASS allows you to do that too using the :let
directive and by abusing the vector type. It is probably best illustrated using an example:
(:let ((foo "#0088EE"))
((a:active) :color #(foo)))
Extending LASS
Pretty much every part of LASS is extensible through methods. Most useful will however probably be the DEFINE-SPECIAL-PROPERTY
, DEFINE-BROWSER-PROPERTY
and DEFINE-SPECIAL-SELECTOR
helper-macros. Here's some examples from the SPECIAL.LISP
file that defines some standard special handlers:
(define-special-property font-family (&rest faces)
(list (make-property "font-family" (format NIL "~{~a~^, ~}" (mapcar #'resolve faces)))))
(define-browser-property linear-gradient (direction &rest colors)
(:default (property)
(make-property "background" (format NIL "~a(~a~{, ~a ~a~})"
property (resolve direction) (mapcar #'resolve colors)))))
For more control, have a look at the various COMPILE-*
generic functions.
Emacs Support
LASS includes a tiny elisp file, lass.el
. Add LASS' directory to your emacs LOAD-PATH
and REQUIRE
lass.
(add-to-list 'load-path "[path-to-lass-source-dir]/")
(require 'lass)
Once you visit a .lass
file, it will automatically start in the LASS
major-mode, which is a derived-mode from COMMON-LISP-MODE
. Whenever you save, it will automatically try to compile the lass file to its CSS equivalent. If slime is connected, it will try to quickload LASS and evaluate GENERATE
. If slime is not connected, it instead executes a shell command. In order for that to work, the lass
binary must be in your path.
If your operating system is not directly supported with a binary, you can build it yourself using a build tool like Buildapp, the ASDF system BINARY-LASS
and the entry-point BINARY-LASS:CMD-WRAPPER
.
To generate pretty .lass
files, set lass-generate-pretty-p
to t
.
ASDF Integration
If you want to compile LASS files to CSS in your systems, you can now (v0.4+) do this via a lass-file
component type, and :defsystem-depends-on
-ing LASS.
(asdf:defsystem my-system
:defsystem-depends-on (:lass)
:components ((:lass-file "test-file")))
You can also specify an :output
argument to a lass-file
to specify what the target css file should be.
Support
If you'd like to support the continued development of LASS, please consider becoming a backer on Patreon:
System Information
Definition Index
-
LASS
- ORG.TYMOONNEXT.LASS
No documentation provided.-
EXTERNAL SPECIAL-VARIABLE *INDENT-LEVEL*
Directs the current amount of spaces used to indent.
-
EXTERNAL SPECIAL-VARIABLE *INDENT-SPACES*
Specifies the number of spaces to use for indentation.
-
EXTERNAL SPECIAL-VARIABLE *PRETTY*
Directs whether to pretty-print using whitespace or not.
-
EXTERNAL SPECIAL-VARIABLE *VARS*
Special variable containing LASS-environment variables. See the definition of the LET block.
-
EXTERNAL CLASS LASS-FILE
An ASDF source-file component to allow compilation of LASS to CSS in ASDF systems.
-
EXTERNAL FUNCTION COMPILE-AND-WRITE
- &REST
- FORMS
- &REST
Shortcut for (WRITE-SHEET (COMPILE-SHEET FORMS*))
-
EXTERNAL FUNCTION COMPILE-SHEET
- &REST
- BLOCKS
- &REST
Compiles a LASS sheet composed of BLOCKS. Each BLOCK is passed to COMPILE-BLOCK. The results thereof are appended together into one list of blocks and properties.
-
EXTERNAL FUNCTION GENERATE
- IN
- &KEY
- OUT
- PRETTY
- IF-EXISTS
- &REST
Generate a CSS file from a LASS file. IN --- The LASS input file. Has to be READable. OUT --- The target file, by default a file of same location and name, but with CSS type. PRETTY --- Whether to minify or not. See WRITE-SHEET. IF-EXISTS --- See WITH-OPEN-FILE Returns OUT
-
EXTERNAL FUNCTION INDENT
Returns a string of the appropriate number of spaces depending on *PRETTY* and *INDENT-LEVEL*
-
EXTERNAL FUNCTION MAKE-BLOCK
- SELECTOR
- VALUES
- &REST
Creates a block object with SELECTOR and VALUES.
-
EXTERNAL FUNCTION MAKE-PROPERTY
- PROPERTY
- &OPTIONAL
- VALUE
- &REST
Creates a property object with PROPERTY as its key and VALUE as its value.
-
EXTERNAL FUNCTION PROPERTY-FUNCTION
- NAME
- &REST
Returns a function to process a property function of NAME, if any.
-
EXTERNAL FUNCTION (SETF PROPERTY-FUNCTION)
- FUNCTION
- NAME
- &REST
Sets FUNCTION as the new processor for the property function NAME.
-
EXTERNAL FUNCTION REMOVE-PROPERTY-FUNCTION
- NAME
- &REST
Removes the property function NAME.
-
EXTERNAL FUNCTION RESOLVE-FUNCTION
- FUNCTION
- &REST
- ARGS
- &REST
Turns the FUNCTION with its ARGS into a properly usable property value.
-
EXTERNAL FUNCTION WRITE-SHEET
- SHEET
- &KEY
- STREAM
- PRETTY
- &REST
Writes the compiled SHEET object to STREAM. If PRETTY is non-NIL, spaces and newlines are inserted as appropriate in order to create a human-readable stylesheet. Otherwise whitespace is only used where necessary, producing a minified version. STREAM can be a STREAM, T for *STANDARD-OUTPUT*, or NIL for a STRING.
-
EXTERNAL FUNCTION WRITE-SHEET-PART
- STREAM
- BLOCK
- CP
- AP
- &REST
Wrapper around WRITE-SHEET-OBJECT so that we can call it from FORMAT. Calls WRITE-SHEET-OBJECT with (CAR BLOCK) (CDR BLOCK) STREAM.
-
EXTERNAL GENERIC-FUNCTION COMPILE-BLOCK
- HEADER
- FIELDS
- &REST
Compiles the block with given HEADER and FIELDS list. By default, the following case is handled: (T T) Blocks are handled in the following way: The HEADER is used as a selector and compiled through COMPILE-SELECTOR. Fields are semantically segregated through KEYWORDS and LISTS. Every time a KEYWORD is encountered, it is taken as the current property and all following objects until either a LIST or a KEYWORD is encountered are gathered as the property's values. Every time a LIST is encountered, it is taken as a SUB-BLOCK and is passed to COMPILE-BLOCK with the HEADER being the current block's selector prepended to the selector of the sub-block. Special handling of blocks may occur. See DEFINE-SPECIAL-BLOCK.
-
EXTERNAL GENERIC-FUNCTION COMPILE-CONSTRAINT
- FUNC
- ARGS
- &REST
Compiles a constraint of type FUNC with arguments ARGS to a list of alternative selectors. By default, the following cases are handled: (T T) Concatenates its ARGS together with spaces. Preserves OR combinations. (NULL NULL) Returns NIL (T NULL) Returns FUNC (:OR T) Passes all ARGS to COMPILE-SELECTOR individually and then APPENDS all the results together. (:AND T) Concatenates its ARGS together without spaces. Preserves OR combinations. Special handling of constraints may occur. See DEFINE-SPECIAL-SELECTOR.
-
EXTERNAL GENERIC-FUNCTION COMPILE-PROPERTY
- KEY
- VALUE
- &REST
Compile a property of KEY and VALUE to a list of property objects. By default, the following cases are handled: (T LIST) A list is created with one property object, wherein the property-value is the Space-concatenated list of RESOLVEd VALUEs. The KEY is DOWNCASEd. (T T) A list is created with one property object, wherein the property-value is the RESOLVEd VALUE. The KEY is DOWNCASEd. Special handling of properties may occur. See DEFINE-SPECIAL-PROPERTY
-
EXTERNAL GENERIC-FUNCTION COMPILE-SELECTOR
- SELECTOR
- &REST
Compiles the SELECTOR form into a list of alternative selectors. By default, the following cases are handled: (NULL) Returns NIL. (LIST) Calls COMPILE-CONSTRAINT with the SELECTOR's CAR and CDR. (T) Returns a list with the RESOLVEd SELECTOR.
-
EXTERNAL GENERIC-FUNCTION CONSUME-ITEM
- ITEM
- READABLE-LIST
- &REST
Consumes items from READABLE-LIST as required by the ITEM. Returned should be two values, the first being a property to compile (or NIL) and the second a block to compile (or NIL). By default, the following cases are handled: (LIST) Simply returns the ITEM as a block. (SYMBOL) If it's a keyword, reads until the next keyword or list and returns that as a property to compile. With property-functions, some sublists may also be read in automatically. See DEFINE-PROPERTY-FUNCTION. If it is a regular symbol, CALL-NEXT-METHOD is invoked. (T) Signals an error.
-
EXTERNAL GENERIC-FUNCTION RESOLVE
- THING
- &REST
Resolves THING to a value that makes sense for LASS. By default the following types are handled: NULL: NIL STRING: the THING itself ARRAY: the variable stored in *VARS* under THING KEYWORD: Colon-prefixed, downcased symbol-name of THING SYMBOL: Downcased symbol-name of THING PATHNAME: If designating an image, base64 encoded inline image data. T: PRINC-TO-STRING of THING
-
EXTERNAL GENERIC-FUNCTION WRITE-SHEET-OBJECT
- TYPE
- OBJECT
- STREAM
- &REST
Writes the OBJECT of type TYPE to STREAM. By default the following TYPEs are handled: :BLOCK (SELECTOR-LIST OBJECTS*) Prints the SELECTOR-LIST separated by commas, followed by an opening brace and the printed list of OBJECTS using WRITE-SHEET-PART. Finally the body is closed off with a closing brace. Newlines and spaces may be inserted where necessary if *PRETTY* is non-NIL. :PROPERTY (KEY VALUE) Prints the KEY. If VALUE is non-NIL, a colon is printed followed by the VALUE. Finally a semicolon is printed. Spaces may be inserted where necessary if *PRETTY* is non-NIL.
-
EXTERNAL MACRO DEFINE-BROWSER-PROPERTY
- NAME
- ARGS
- &BODY
- BROWSER-OPTIONS
- &REST
Helper macro to define properties that have browser-dependant versions. NAME --- The base name of the property name or value. ARGS --- Property arguments, see DEFINE-SPECIAL-PROPERTY. BROWSER-OPTIONS ::= (OPTION (symbol) FORM*) OPTION ::= :MOZ | :O | :WEBKIT | :MS | :W3C | :DEFAULT Each browser-option body should return a single property. The SYMBOL in the option definition is bound to the computed property name (eg -moz-NAME for the :MOZ option). You can define special handling of the browsers by defining options specifically for them. If no handling is defined, the DEFAULT option is used as a fallback.
-
EXTERNAL MACRO DEFINE-PRIMITIVE-PROPERTY-CONSUMER
- SPECIALIZER
- PROPVALS
- READABLE
- NEXT
- &REST
- &BODY
- LOOP-BODY
- &REST
Defines a CONSUME-ITEM method for the given item SPECIALIZER. SPECIALIZER --- The method specializer for the item. PROPVALS --- The list that should contain the property values. READABLE --- The readable-list being operated on currently. NEXT --- Bound to the next (unconsumed) item in the readable-list. LOOP-BODY --- The body of the reading loop to execute until the readable is empty. The return value of the loop-body is discarded. You can use (RETURN) to exit the loop, for example for when you encounter an item you don't want to read.
-
EXTERNAL MACRO DEFINE-PROPERTY-FUNCTION
- NAME
- ARGS
- &BODY
- BODY
- &REST
Define a new property function NAME, accepting ARGS. The body should return a value to use directly, if possible a string. The results of a property-function should not be RESOVLEd. Property functions are function calls that occur as (part of) the value of a property. Due to ambiguity issues with a general sub-block, property functions need to be explicitly defined and may completely differ depending on the property. Property functions defined with this are only the defaults available for all properties. If you want to minimise collision probability or avoid an illegal function for a certain property, you should define a direct method on CONSUME-ITEM to handle the reading of the property values manually.
-
EXTERNAL MACRO DEFINE-PROPERTY-FUNCTION-CASE
- PROPERTY
- ARGS
- &REST
- &BODY
- FUNCTION-CLAUSES
- &REST
Defines a CONSUME-ITEM method for PROPERTY that has special handling for property-functions. FUNCTION-CLAUSES ::= function-clause* FUNCTION-CLAUSE ::= (function-name form*) Each function-name is compared by STRING-EQUAL and each clause should return the property-value to use in its place, or NIL if it should be skipped. You can use (RETURN) in a clause body to stop reading values altogether.
-
EXTERNAL MACRO DEFINE-SIMPLE-PROPERTY-FUNCTION
- NAME
- ARGS
- &REST
Defines a property function that returns name(arg1,arg2...). Only required arguments are allowed.
-
EXTERNAL MACRO DEFINE-SIMPLE-PROPERTY-FUNCTIONS
- PROPERTY
- &REST
- FUNCSPECS
- &REST
Defines a CONSUME-ITEM method for PROPERTY that has special handling for property-functions. FUNCSPECS ::= funcspec* FUNCSPEC ::= (funcname arg* [&optional arg*] [&key arg*]) See DEFINE-PROPERTY-FUNCTION-CASE.
-
EXTERNAL MACRO DEFINE-SINGLE-ARG-SELECTOR
- NAME
- &REST
Helper macro to define a single-argument pseudo-selector like NOT or NTH-CHILD.
-
EXTERNAL MACRO DEFINE-SPECIAL-BLOCK
- NAME
- ARGS
- &BODY
- BODY
- &REST
Define handling of a special block type. In order for the block to be recognised, it has to begin with the NAME as a keyword. The ARGS is a lambda-list that parses the block contents. Expected as a return value is a /list/ of either attributes or blocks. See COMPILE-BLOCK
-
EXTERNAL MACRO DEFINE-SPECIAL-PROPERTY
- NAME
- ARGS
- &BODY
- BODY
- &REST
Define handling of a special property. The ARGS is a lambda-list that parses the arguments passed to the property. Expected as a return value is a /list/ of either attributes or blocks. See COMPILE-PROPERTY
-
EXTERNAL MACRO DEFINE-SPECIAL-SELECTOR
- NAME
- ARGS
- &BODY
- BODY
- &REST
Define handling of a special selector type. In order for the selector to be recognised, it has to begin with the NAME as a keyword. The ARGS is a lambda-list that parses the selector contents. Expected as a return value is a /list/ of alternate versions of selectors. See COMPILE-CONSTRAINT.