diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..b02fa6c --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,19 @@ +Copyright © 2018 Marcus 'ReFreezed' Thunström + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..9d7d35e --- /dev/null +++ b/README.md @@ -0,0 +1,109 @@ +# LuaCss + +CSS tokenizing and minimizing library for Lua 5.1. No external dependencies - only pure Lua. + +- [Usage](#usage) +- [API](#api) +- [Token Format](#tokenformat) + - [Token Types](#tokentypes) + + + +## Usage +`css.lua` is the library. `utf8.lua` is used by the library. Those are the only files you need. + +```lua +local css = [[ +div { + color: blue; + /* Blah. */ + background-color: #36B !important; +} + +@media (min-width: 800px) { + .box a:hover { text-decoration: underline; } +} +]] + +local cssLib = require("css") +local minimizedCss = cssLib.minimize(css) + +-- minimizedCss is: +-- div{color:blue;background-color:#36B!important}@media(min-width:800px){.box a:hover{text-decoration:underline}} +``` + + + +## API + +### minimize +`cssString = minimize( cssString [, strictErrors=false ] )` + +### serializeAndMinimize +`cssString = serializeAndMinimize( cssTokens [, strictErrors=false ] )` + +### tokenize +`cssTokens = tokenize( cssString )` + +```lua +local tokens = cssLib.tokenize(css) + +for i, token in ipairs(tokens) do + print(i, token.type, token.value, token.unit) +end +``` + + + +## Token Format +```lua +token = { + -- Always present: + type = tokenType, + + -- Present in some token types: + value = tokenValue, + from = unicodeRangeStart, + idType = hashTokenIdentifierType, + numberType = numberType, + quoteCharacter = stringQuoteCharacter, + representation = originalNumberRepresentation, + to = unicodeRangeEnd, + unit = dimensionUnit, +} +``` + +### Token Types + +| Type | Value | Description | +| ------------------ | ----- |------------ | +| `"atKeyword"` | The name, e.g. `"media"`. | `@whatever` | +| `"badString"` | nothing | Malformed string. | +| `"badUrl"` | nothing | Malformed `url()`. | +| `"cdo"`
`"cdc"` | nothing | Long ago people used to wrap embedded CSS code inside HTML comments, thus these tokens (`""`, respectively). | +| `"colon"` | nothing | `:` | +| `"columnMatch"` | nothing | Token that exists to help with parsing: ||. | +| `"comma"` | nothing | `,` | +| `"comment"` | The contents of the comment. | `/* Blah. */`
Note that comments starting with `!` are preserved during minification, e.g. `/*! Copyright info. */`. | +| `"dashMatch"` | nothing | |= | +| `"dimension"` | The number. | Numeric value with a unit.
This token has a `unit` field, e.g. with the value `"px"`.
This token also has the extra fields that the `number` type has. | +| `"function"` | The name of the function, e.g. `"calc"`. | An identifier followed by a `(`. | +| `"hash"` | The name, e.g. `"commentBox"` or `"A0FF5C"`. | Matches include ID selectors and color values.
This token also has an `idType` field with the value `"id"` or `"unrestricted"` (the latter *generally* meaning the value is a color starting with a number, e.g. `#2FBBAA`). | +| `"ident"` | The name, e.g. `"div"` or `"font-size"`. | Any isolated identifier. | +| `"includeMatch"` | nothing | `~=` | +| `"number"` | The number. | Plain numeric value.
This token also has a `numberType` and `representation` field. `numberType` can be either `"integer"` or `"number"`. | +| `"percentage"` | The number. | Numeric percentage value.
This token also has the extra fields that the `number` type has. | +| `"prefixMatch"` | nothing | `^=` | +| `"semicolon"` | nothing | `;` | +| `"string"` | The contents of the string. | This token also has a `quoteCharacter` field whose value is either `"` (quote) or `'` (apostrophe).
Also see `badString`. | +| `"substringMatch"` | nothing | `*=` | +| `"suffixMatch"` | nothing | `$=` | +| `"unicodeRange"` | nothing | Unicode ranges has a `from` and a `to` field with Unicode code points. | +| `"url"` | The URL. | This token also has a `quoteCharacter` field whose value is either `"` (quote), `'` (apostrophe) or an empty string.
Also see `badUrl`. | +| `"whitespace"` | The contents of the whitespace sequence. | Whitespace characters are **space**, **horizontal tab** and **newline**. Note that all line endings are normalized into **newlines**. | +| `"("`, `")"` | nothing | `(` and `)`, respectively. | +| `"["`, `"]"` | nothing | `[` and `]`, respectively. | +| `"{"`, `"}"` | nothing | `{` and `}`, respectively. | +| `"delim"` | The delimiter. | Any other isolated punctuation character, e.g. `"."` or `"+"`. | + +