{"id":17931294,"url":"https://github.com/seven-phases-max/less-plugin-functions","last_synced_at":"2025-03-24T04:31:38.357Z","repository":{"id":31080843,"uuid":"34639851","full_name":"seven-phases-max/less-plugin-functions","owner":"seven-phases-max","description":"Write custom Less functions in Less itself","archived":false,"fork":false,"pushed_at":"2017-04-24T10:43:55.000Z","size":28,"stargazers_count":111,"open_issues_count":2,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-01T15:17:39.656Z","etag":null,"topics":["less","less-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seven-phases-max.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-27T01:37:52.000Z","updated_at":"2023-09-21T14:13:36.000Z","dependencies_parsed_at":"2022-08-27T04:10:57.207Z","dependency_job_id":null,"html_url":"https://github.com/seven-phases-max/less-plugin-functions","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-phases-max%2Fless-plugin-functions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-phases-max%2Fless-plugin-functions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-phases-max%2Fless-plugin-functions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-phases-max%2Fless-plugin-functions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seven-phases-max","download_url":"https://codeload.github.com/seven-phases-max/less-plugin-functions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244339044,"owners_count":20437169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["less","less-plugin"],"created_at":"2024-10-28T21:21:01.592Z","updated_at":"2025-03-24T04:31:38.114Z","avatar_url":"https://github.com/seven-phases-max.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# less-plugin-functions\n\nWrite genuine [Less](http://lesscss.org) functions in Less itself.\n\n[![npm version](https://badge.fury.io/js/less-plugin-functions.svg)](http://badge.fury.io/js/less-plugin-functions)\n[![dependencies](https://david-dm.org/seven-phases-max/less-plugin-functions.svg)](https://david-dm.org/seven-phases-max/less-plugin-functions)\n[![dev dependencies](https://david-dm.org/seven-phases-max/less-plugin-functions/dev-status.svg)](https://david-dm.org/seven-phases-max/less-plugin-functions#info=devDependencies)\n\nThis experimental \"proof-of-concept\" plugin extends [Less](http://lesscss.org) with a possibility to define custom functions directly in Less itself and use them just like regular [built-in functions](http://lesscss.org/features/#features-overview-feature-functions).\n\nDefine `foo` function:\n```less\n.function {\n    .foo(@x) {\n        return: @x * 2;\n    }\n}\n```\nUse it:\n```less\ndiv {\n    width: foo(21em); // -\u003e 42em\n}\n```\n\n## Installation\n\n    npm install -g less-plugin-functions\n\n## Usage\n\n    lessc --functions file.less\n\nFor more details about using plugins with the command line Less compiler see\n[the corresponding section](http://lesscss.org/usage/#plugins-how-do-i-use-a-plugin-command-line)\nin the [Less documentation](http://lesscss.org).\n\nUsing with common Less tools:\n\n- [`grunt-contrib-less`](https://github.com/gruntjs/grunt-contrib-less#usage-examples)\n- [`gulp-less`](https://github.com/plus3network/gulp-less#using-plugins)\n\nFor more details on a programmatic Less plugin usage see [Using a plugin in code](http://lesscss.org/usage/#plugins-using-a-plugin-in-code).\n\n## Feature Details\n\nCustom functions recognizable by this plugin are defined as plain Less [mixins](http://lesscss.org/features/#mixins-parametric-feature) having either `.function-` prefix or being immediate descendant of a `.function` [namespace](http://lesscss.org/features/#features-overview-feature-namespaces-and-accessors). For example the following two snippets create the same function named `bar`.\n\nUsing namespace:\n```less\n.function {\n    .bar() {\n        return: red;\n    }\n}\n```\nUsing prefix:\n```less\n.function-bar() {\n    return: red;\n}\n```\nThe defined function can be used same way and anywhere a CSS/Less function can:\n```less\ndiv {\n    background-color: bar();    // red\n    color: lighten(bar(), 13%); // #ff4242\n    // etc.\n}\n```\nDon't miss that the defined function name is `bar`, without any prefix or a dot.\n\nAdditionally note that the function definitions should use only lowercase names (e.g. `.function-bar` not `.function-Bar`). Less function names are case-insensitive so for both `bar()` and `Bar()` call statements the compiler will look only for the lowercase `bar` definition  (for more details see [#1](https://github.com/seven-phases-max/less-plugin-functions/issues/1)).\n\n#### Supported functionality\n\nSince custom functions are defined as regular Less mixins, they inherit most of standard mixin behaviour and functionality. In particular:\n\n* [Overloading](http://lesscss.org/features/#mixins-parametric-feature-pattern-matching) (aka \"Arguments Pattern Matching\")\n* [Default Parameters](http://lesscss.org/features/#mixins-parametric-feature)\n* [Variadic Arguments](http://lesscss.org/features/#mixins-parametric-feature-advanced-arguments-and-the-rest-variable)\n* [Guards](http://lesscss.org/features/#mixin-guards-feature)\n\n#### Return Value\n\nFunction return value is specified via `return` property.\n```less\n.function-foo() {\n    return: \"Hello, I'm the foo return value.\";\n}\n```\nNotice that since the return statement is just a regular CSS property it does not \"return immediately\", and any code after `return` is still in effect. Same way all default Less behavior of CSS properties applies to the `return` property as well.\n\nE.g. it can be overridden:\n```less\n.function-bar() {\n    return: 1;\n    return: 2;\n    // function returns 2\n}\n```\n[merged](http://lesscss.org/features/#merge-feature):\n```less\n.function-baz() {\n    return+: 1;\n    return+: 2;\n    // function returns 1, 2\n}\n```\netc.\n\n#### Overriding CSS and built-in Less functions\n\nCustom function definitions override CSS or [built-in](http://lesscss.org/functions/#functions-overview) Less functions of the same\nname (certain performance critical functions are not overridable by default though, see [`-a` option](#--always-override--alwaysoverride) below for more details). That is, you can \"replace\"/\"extend\" any Less or even CSS function by your own implementation.\n\nFor example:\n```less\n// override `calc` globally:\n.function-calc(@expr) {\n    return: tired, won΄t calculate;\n}\n\ndiv {\n    width: calc(50% - 20px);\n    color: hsl(0, 50%, 25%);\n}\n\nspan {\n    color: hsl(0, 50%, 25%);\n\n    // override `hsl` locally:\n    .function-hsl(@h, @s, @l) {\n        return: hsla(@h, @l, @s, 1); // happy debugging!\n    }\n}\n```\nCSS result:\n```css\ndiv {\n    width: tired, won΄t calculate;\n    color: #602020;\n}\nspan {\n    color: #9f6060;\n}\n```\n\n#### More examples\n\nSee [included tests](test/less) for more advanced examples. Additionally see a few examples on using this plugin in conjunction with [`list-plugin-lists`](https://github.com/seven-phases-max/less-plugin-lists/blob/master/docs/for-adv.md#using-with-the-functions-plugin).\n\n## Options\n\n#### `--always-override` / `alwaysOverride`\n\u003eAlways override native CSS or Less functions\n\nShorthand: `-a`. For performance reasons (mixin lookup is a costly process) certain CSS and built-in Less functions are marked as not overridable by the custom functions. Setting this option allows you to override *any*. Note however, this can significantly increase compilation time even if you don't override anything (for a typical Less framework/codebase this option may result in about 20% performance hit).\n\nThe list of functions not overridable w/o `-a` can be found [here](lib/no-overrides.js).\n\n#### `--globals-only` / `globalsOnly`\n\u003eUse only global scope definitions\n\nShorthand: `-g`. By default the plugin searches for a possible function definition(s) starting from the current scope upwards (i.e. standard Less scoping). If your Less code is heavy on using too deep nesting and/or too many local mixins, such scope-aware lookup may negatively affect compilation time. This option allows you to restrict the search to a functions explicitly defined in the global scope.\n\nFor an average Less source code the performance difference is insignificant (unless `-a` option is also set), so normally you don't need this option (consider it as \"experimental\") unless you're hunting for every single bit of compilation time improvement.\n\n## Implementation and Compatibility\n\nTo deliver its functionality this plugin has to use certain hackish tricks and methods a standard Less plugin is not supposed to use (simply because a standard Less plugin is not supposed to provide such functionality at all). This makes the plugin to be quite vulnerable to possible compiler internals changes, thus it's more tied to a particular Less version than a typical plugin would be.\n\n_Currently supported Less versions are `2.4.0` or higher._\n\n## Future\n\nBecause of the [implementation details](#implementation-and-compatibility) and sightly confusing function definition syntax, this functionality/feature ideally should be moved into the Less core (not necessarily using the same syntax).\n\nSee corresponding feature request and related discussion at [#538](https://github.com/less/less.js/issues/538). Please, do not hesitate to put your `+1` there if you find this functionality valuable.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseven-phases-max%2Fless-plugin-functions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseven-phases-max%2Fless-plugin-functions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseven-phases-max%2Fless-plugin-functions/lists"}