{"id":27962318,"url":"https://github.com/jcubic/lips","last_synced_at":"2025-05-15T05:08:22.536Z","repository":{"id":29744543,"uuid":"122653051","full_name":"jcubic/lips","owner":"jcubic","description":"Scheme based powerful lisp interpreter in JavaScript","archived":false,"fork":false,"pushed_at":"2025-05-01T15:08:59.000Z","size":39064,"stargazers_count":443,"open_issues_count":95,"forks_count":39,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-05-07T19:26:24.605Z","etag":null,"topics":["bookmarklet","hacktoberfest","language","lisp","lisp-interpreter","lisp-language","macros","parser","r5rs","r5rs-scheme","r7rs","r7rs-scheme","repl","s-expression","scheme","scheme-interpreter","support-bigint"],"latest_commit_sha":null,"homepage":"https://lips.js.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcubic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"jcubic","ko_fi":"jcubic","custom":"https://www.paypal.me/jcubic"}},"created_at":"2018-02-23T17:39:04.000Z","updated_at":"2025-05-04T16:58:47.000Z","dependencies_parsed_at":"2024-02-03T21:24:25.196Z","dependency_job_id":"4540f147-a795-4743-bc95-5751b1cae563","html_url":"https://github.com/jcubic/lips","commit_stats":{"total_commits":1567,"total_committers":4,"mean_commits":391.75,"dds":0.00829610721123164,"last_synced_commit":"ac51faeed3a41952f5853cb7b2a1bc0d45d0ccc9"},"previous_names":["lips-scheme/lips","jcubic/lips"],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Flips","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Flips/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Flips/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Flips/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcubic","download_url":"https://codeload.github.com/jcubic/lips/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"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":["bookmarklet","hacktoberfest","language","lisp","lisp-interpreter","lisp-language","macros","parser","r5rs","r5rs-scheme","r7rs","r7rs-scheme","repl","s-expression","scheme","scheme-interpreter","support-bigint"],"created_at":"2025-05-07T19:20:15.985Z","updated_at":"2025-05-15T05:08:17.519Z","avatar_url":"https://github.com/jcubic.png","language":"JavaScript","readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/jcubic/lips/blob/master/assets/lips.svg?raw=true\"\n       alt=\"LIPS - Scheme Based Powerful Lisp Language\" /\u003e\n\u003c/h1\u003e\n\n[![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/LIPS_scheme)](https://twitter.com/LIPS_scheme)\n[![npm](https://img.shields.io/badge/npm-1.0.0%E2%80%93beta.20-blue.svg)](https://www.npmjs.com/package/lips)\n![1.0.0 Complete](https://img.shields.io/github/milestones/progress-percent/jcubic/lips/1?label=1.0.0%20Complete)\n[![Build and test](https://github.com/jcubic/lips/actions/workflows/build.yaml/badge.svg?branch=master\u0026event=push)](https://github.com/jcubic/lips/actions/workflows/build.yaml)\n[![Coverage Status](https://coveralls.io/repos/github/jcubic/lips/badge.svg?branch=master\u0026dd93e2ed5fe4147ff629f2673e56de90)](https://coveralls.io/github/jcubic/lips?branch=master)\n[![Join Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jcubic/lips)\n![NPM Download Count](https://img.shields.io/npm/dm/lips)\n![JSDelivr Download count](https://img.shields.io/jsdelivr/npm/hm/lips)\n\u003ca href=\"https://codeclimate.com/github/jcubic/lips/maintainability\"\u003e\u003cimg src=\"https://api.codeclimate.com/v1/badges/876398746c020dd1bb97/maintainability\" /\u003e\u003c/a\u003e\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjcubic%2Flips.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjcubic%2Flips?ref=badge_shield)\n\n[![GitHub stars](https://img.shields.io/github/stars/jcubic/lips.svg?style=social\u0026label=Star\u0026maxAge=2592000)](https://GitHub.com/jcubic/lips/stargazers/)\n\u003ca href=\"https://twitter.com/intent/tweet?text=Powerful%20Scheme%20based%20lisp%20language%20written%20in%20JavaScript.%20It%20makes%20life%20easier%20by%20better%20interaction%20with%20JS.%20Use%20full%20power%20of%20JS%2C%20lisp,%20and%20npm%20to%20create%20your%20applications%20via%20@lips_lang\u0026url=https://github.com/jcubic/lips\u0026hashtags=javascript,opensource,lisp,scheme,language,programming\"\u003e\n   \u003cimg src=\"https://github.com/jcubic/lips/blob/devel/assets/tweet-shield.svg?raw=true\" alt=\"Tweet\" height=\"20\"/\u003e\n\u003c/a\u003e\n\n[LIPS is a powerful Scheme-based, Lisp language written in JavaScript](https://lips.js.org).\nIt is based on the Scheme dialect of lisp and the R5RS/R7RS specifications. It has extensions to make it easier\nto interact with JavaScript and extend the language. It works both in the browser and with Node.js.\n\nThe aim of the project is to support full R7RS specification and be compatible with [Scheme programming language](https://www.scheme.org/).\n\nThe name is a recursive acronym which stands for LIPS Is Pretty Simple.\n\n## Demo\n\n[Web REPL Demo](https://lips.js.org/#demo)\n\n## Features\n\n* Literal regular expression.\n* Asynchronous execution (auto resolving of promises).\n* Possibility to add new syntax (similar to vectors and object).\n* Numerical tower and Big Integer support.\n* Powerful introspection.\n* Great integration with JavaScript.\n* Auto formatting lisp of code (pretty print)\n* Lisp and hygienic Scheme macros and macroexpand.\n* Builtin help system.\n\n## Installation\n\nTo install you can use npm (or yarn)\u003cbr/\u003e\n**NOTE:** The version that is on NPM is heavily outdated, use beta version:\n\n\n```\nnpm install lips@beta\n```\n\nor yarn:\n\n```\nyarn add lips@beta\n```\n\nthen include the file in the script tag. You can grab the version from unpkg.com\n\n```\nhttps://unpkg.com/lips@beta\n```\n\nor from jsDelivr (that's seems a bit faster)\n\n```\nhttps://cdn.jsdelivr.net/npm/lips@beta/dist/lips.min.js\n```\n\n## Bookmarklet REPL\n\n\nYou can also run the REPL on any page while you learn Scheme using the bookmarklet:\n\n```\nhttps://github.com/jcubic/lips/blob/master/lib/js/bookmark.js\n```\n\nCreate any link in your bookmarks, edit it and copy-paste the content of that file.\nAfter you click on the link it will create the REPL at the bottom of the page.\n(NOTE: It may not work on every page because of content security policy;\ne.g. google.com or gihub.com)\n\nIf you have trouble with creating the bookmarklet, you can open\n[LISP Scheme home page](https://lips.js.org/#bookmark) where you can\nfind a link that you can drag to your bookmarks.\n\n## Usage\n\nThe simplest way is to include the lips code in the script tag:\n\n```html\n\u003cscript type=\"text/x-scheme\" bootstrap\u003e\n(let ((what \"world\")\n      (greet \"hello\"))\n   (display (string-append greet \" \" what)))\n\u003c/script\u003e\n```\n\nor use the `src` attribute:\n\n```html\n\u003cscript type=\"text/x-scheme\" bootstrap src=\"example.scm\"\u003e\u003c/script\u003e\n```\n\n## Bootstrapping Scheme system\n\nBig part of LIPS is written in LIPS itself, but to use full power of LIPS you need\nto load those additional Scheme files. The easiest way is to add `bootstrap` attribute\non first script tag with `text/x-scheme` type. By default, it will use CDN from\n[jsdelivr](https://www.jsdelivr.com/). To load each file using builtin load function\n(that will fetch the file using AJAX and evaluate it).\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/lips@beta/dist/lips.min.js\" bootstrap\u003e\u003c/script\u003e\n```\n\nYou can also specify the path where LIPS should search for standard library.\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/lips@beta/dist/lips.min.js\"\n        bootstrap=\"https://cdn.jsdelivr.net/npm/lips@beta/dist/std.xcb\"\u003e\n\u003c/script\u003e\n```\n\nYou can use `bootstrap=\"./std.xcb\"` if there is `std.xcb` file in local directory.\nYou can also bootstrap with `std.scm` or `std.min.scm` but xcb file is the fastest,\nbecause it's already parsed and compiled into binary format.\n\n## Running LIPS programmatically\n\n```javascript\nvar {exec} = require('lips'); // node\n// or\nvar {exec} = lips; // browser\n\nexec(string).then(function(results) {\n     results.forEach(function(result) {\n        console.log(result.toString());\n     });\n});\n```\n\nWhen running exec you will also need to bootstrap the language and loaded files from `/lib/` directory.\n\nDocumentation about beta version can be found in\n[Wiki](https://github.com/jcubic/lips/wiki/v1.0.0).\n\n## Standalone executable\n\n**NOTE:** Executable don't require bootstrapping lib files.\n\nIf you install lips globally with:\n\n```\nnpm install -g lips@beta\n```\n\nyou can run the interpreter from the terminal:\n\n![LIPS: Scheme interactive terminal](https://github.com/jcubic/lips/blob/master/assets/screencast.gif?raw=true)\n\n\nYou can also run code in a string with:\n\n```\nlips -c '(let ((what \"World\")) (display (string-append \"Hello \" what)))'\n```\n\nand you can run a file using:\n\n```\ncat \u003e foo.scm \u003c\u003cEOF\n(let ((what \"World\"))\n  (display (string-append \"Hello \" what))\n  (newline))\nEOF\n\nlips foo.scm\n```\n\nYou can also write executable files that use lips using shebang (SRFI-22)\n\n```\ncat foo.scm\n#!/usr/bin/env lips\n\n(let ((what \"World\"))\n  (display (string-append \"Hello \" what))\n  (newline))\n\nchmod a+x foo.scm\n./foo.scm\n```\n\nExecutables also return a S-Expression according to SRFI-176 use `lips --version` or `lips -V`.\n\n## FOSDEM'23 Presentation [Video]\n\n[![FOSDEM 2023 - LIPS Scheme: Powerful introspection and extensibility](https://github.com/jcubic/lips/blob/master/assets/fosdem-intro.png?raw=true)](https://fosdem.org/2023/schedule/event/lipsscheme/)\n\n## Limitations\n\n### Performance\nBecause LIPS is tree walking interpreter, sometimes it may be slow. Especially if you want to\nprocess long arrays and use callback function. If the array is quite large each piece of code\ninside the callback may slow down the processing. For example see:\n\nscript [reference.scm](https://github.com/jcubic/lips/blob/master/scripts/reference.scm)\n\nThat generates reference documentation for all builtin functions and macros.\nThe slow part is `(names.sort name-compare)` (`Array::sort`) that take quite time to calculate,\nbecause the array with functions and macros is quite large. If you came into performance issue,\nyou can write the part of the code in JavaScript. If you want to do this in LIPS Scheme you can use\nsomething like this:\n\n```scheme\n(let ((fn (self.eval \"(function(a, b) {\n                         /* any complex code in JS */\n                         return a.localeCompare(b);\n                      })\")))\n   (arr.sort fn))\n```\n\nAnother example of slow performance is using LIPS with React, the more code you put into components\nthe slower the app will become.\n\nExamples:\n* [Preact app that update SVG](https://codepen.io/jcubic/pen/PojYxBP) - it requires using debounce.\n* [React with Hooks](https://codepen.io/jcubic/pen/PoKQmpq?editors=1000) - on click the UI freezes for ~300ms, you can see warnings in dev tools.\n\nThe issue with performance is tracked in [#197](https://github.com/jcubic/lips/issues/197).\n\n### JavaScript callbacks\n\nAnother limitation is when using JavaScript libraries that require normal values but get a Promise instead.\nThis can happen with React/Preact and when the component returns a Promise. Some macros can be async\n(return a Promise), which will break the React app when used in components. An example of a macro that is async is\n`do` macro. So when using React/Preact and when you need to use a promise, use promise quotation and `useEffect`.\n\n## Supported SRFI\n\n### built-in\n\n| description | spec |\n| :--- | ---: |\n| Feature-based conditional expansion construct | [SRFI-0](https://srfi.schemers.org/srfi-0/) |\n| Homogeneous numeric vector datatypes | [SRFI-4](https://srfi.schemers.org/srfi-4/) |\n| Basic String Ports | [SRFI-6](https://srfi.schemers.org/srfi-6/) |\n| Running Scheme Scripts on Unix | [SRFI-22](https://srfi.schemers.org/srfi-22/) |\n| Error reporting mechanism | [SRFI-23](https://srfi.schemers.org/srfi-23/) |\n| Basic Format Strings | [SRFI-28](https://srfi.schemers.org/srfi-28/) |\n| Basic Syntax-rules Extensions | [SRFI-46](https://srfi.schemers.org/srfi-46/) |\n| An interface to access environment variables | [SRFI-98](https://srfi.schemers.org/srfi-98/) |\n| Syntax parameters | [SRFI-139](https://srfi.schemers.org/srfi-139/) |\n| Custom macro transformers | [SRFI-147](https://srfi.schemers.org/srfi-147/) |\n| Version flag | [SRFI-176](https://srfi.schemers.org/srfi-176/) |\n| Command line | [SRFI-193](https://srfi.schemers.org/srfi-193/) |\n| Mixing groups of definitions with expressions within bodies | [SRFI-251](https://srfi.schemers.org/srfi-251/) |\n\n### require manual loading\n\nYou can load the SRFI with special syntax that start with `@lips`\nwhich points to root LIPS directory:\n\n```scheme\n(load \"@lips/lib/srfi/\u003cnumber\u003e.scm\")\n```\n\nThey should be loaded as R7RS libraries in final 1.0.0 version\n\n| description | spec |\n| :--- | ---: |\n| List Library | [SRFI-1](https://srfi.schemers.org/srfi-1/) |\n| `AND-LET*`: an AND with local bindings, a guarded `LET*` special form | [SRFI-2](https://srfi.schemers.org/srfi-2/) |\n| receive: Binding to multiple values | [SRFI-8](https://srfi.schemers.org/srfi-8/) |\n| `#,` external form | [SRFI-10](https://srfi.schemers.org/srfi-10/) |\n| Notation for Specializing Parameters without Currying | [SRFI-26](https://srfi.schemers.org/srfi-26/) |\n| Basic hash tables | [SRFI-69](https://srfi.schemers.org/srfi-69/) |\n| Boxes | [SRFI-111](https://srfi.schemers.org/srfi-111/) |\n| Syntactic combiners for binary predicates | [SRFI-156](https://srfi.schemers.org/srfi-156/) |\n| Multiple-value boxes | [SRFI-195](https://srfi.schemers.org/srfi-195) |\n| Procedures and Syntax for Multiple Values | [SRFI-210](https://srfi.schemers.org/srfi-210/) |\n| Evaluating expressions in an unspecified order | [SRFI-236](https://srfi.schemers.org/srfi-236) |\n| Destructuring Lists | [SRFI 239](https://srfi.schemers.org/srfi-239/) |\n\nin Web (e.g. in Web REPL) you can also use full URL:\n\n```scheme\n(load \"https://cdn.jsdelivr.net/npm/lips@beta/lib/srfi/\u003cNUMBER\u003e.scm\")\n```\n\n## Links\n* [Gitter Chat for discussions](https://gitter.im/jcubic/lips)\n* [LIPS: Scheme in JavaScript Git Repository](https://github.com/jcubic/lips)\n* [Official Website](https://lips.js.org/)\n* [Twitter/X](https://twitter.com/LIPS_scheme)\n\n### Articles\n* [How to start learning Lisp](https://jcubic.pl/2019/05/jak-zaczac-nauke-lispa.html) (PL with translator widget)\n\n### Press\n* [JavaScript Weekly](https://javascriptweekly.com/issues/669)\n* [Hacker News](https://news.ycombinator.com/item?id=38819212)\n* [Brian Lovin](https://brianlovin.com/hn/38819212) (HN clone)\n\n## Roadmap\n### 1.0\n- [x] Full support for R5RS\n- [ ] Full support for R7RS\n  - [ ] R7RS libraries (`import`/`export`/`define-library`).\n  - [ ] Continuations.\n  - [ ] Tail Call Optimization (TCO).\n  - [ ] Fully tested Numerical Tower.\n- [x] Fully working binary compiler (for faster parsing and loading std lib).\n- [ ] Finish `syntax-rules` (ignore limitations of current approach).\n  - [ ] Objects.\n  - [ ] Vectors.\n\n### Future Plans\n- [ ] Picture language (possibly inspired by P5.js, see [SRFI-203](https://srfi.schemers.org/srfi-203/srfi-203.html)).\n- [ ] Stepper/Debugger.\n- [ ] Allow to use read/port in syntax extensions (similar to CL reader macros).\n- [ ] Proper expansion time for both macro systems.\n- [ ] Fully working and tested R7RS hygienic Macros (`syntax-rules`).\n- [ ] All recursive function in JS don't consume stack.\n\n### WIP Side projects\n- [ ] [KISS](https://github.com/jcubic/kiss) (Chrome extension REPL).\n- [ ] [SMILE](https://github.com/jcubic/smile) (Web IDE), need to start over.\n\n## How you can help\n\nI'm working on version 1.0. If you find any bugs, you can help by reporting them.\nIf you have some Scheme code that doesn't work (note about the limitations)\ndon't hesitate to [report an issue](https://github.com/jcubic/lips/issues/new).\n\nYou can also propose a feature or improvement to the library, it doesn't always have to be defects.\n\nIf you enjoy the library, you can write about it on a blog post and share information about it or write on Social Media.\nDon't forget to link to the project website (it's\n[good for SEO](https://itnext.io/seo-for-open-source-projects-1a6b17ffeb8b)).\n\nOf course, if you want you can also contribute with code, but there are way easier ways to help.\n\nI would also love to see if you use the library, I may even share the links of projects that use it.\n\n## Acknowledgments\n* Font used in logo is [Telegrafico](https://www.dafont.com/telegrafico.font) by [ficod](https://www.deviantart.com/ficod).\n* The cover image for GitHub and Blog Posts use clipart by [Baptiste Gaultier](https://openclipart.org/artist/b.gaultier).\n* Part of the current Parser is inspired by implementation in [BiwaScheme](https://www.biwascheme.org/) by Yutaka HARA (yhara).\n* `fetch` polyfill use [unfetch](https://github.com/developit/unfetch) by Jason Miller.\n* Browser `init` function use [ContentLoaded](http://javascript.nwbox.com/ContentLoaded/).\n* The rationalize algorithm is based on [Kawa Scheme](https://www.gnu.org/software/kawa/index.html) by Per M.A. Bothner, Alan Bawden and Marc Feeley.\n* `ucs2decode` function taken from [punycode.js](https://github.com/bestiejs/punycode.js) by [Mathias Bynens](https://mathiasbynens.be/).\n* [Rosetta Code](https://rosettacode.org/) was used for:\n  * [gdc](https://rosettacode.org/wiki/Greatest_common_divisor#JavaScript),\n  * [lcm](https://rosettacode.org/wiki/Least_common_multiple#JavaScript),\n  * [LFloat::toRational](https://rosettacode.org/wiki/Convert_decimal_number_to_rational).\n* [StackOverlow](https://stackoverflow.com) code was used for functions:\n  * [fworker](https://stackoverflow.com/a/10372280/387194),\n  * [flatten](https://stackoverflow.com/a/27282907/387194),\n  * [allPossibleCases](https://stackoverflow.com/a/4331218/387194),\n  * [async replace](https://stackoverflow.com/a/48032528/387194).\n* Code formatter is roughly based on [scheme-style](http://community.schemewiki.org/?scheme-style) and GNU Emacs scheme mode.\n* Some helpers in standard library are inspired by same functions from [RamdaJS library](https://ramdajs.com/).\n\nSpecial thanks:\n* [Lassi Kortela](https://github.com/lassik) for helping with Scheme code.\n* [Niels Wijers](https://github.com/nielswijers) for handing over the [lips npm name](https://www.npmjs.com/package/lips).\n\nThanks for [Algolia DocSearch](https://docsearch.algolia.com/) for providing free search on LIPS website.\n\n## License\n\nReleased under [MIT](http://opensource.org/licenses/MIT) license\u003cbr/\u003e\nCopyright (c) 2018-2024 [Jakub T. Jankiewicz](https://jcubic.pl/me)\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjcubic%2Flips.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjcubic%2Flips?ref=badge_large)\n","funding_links":["https://github.com/sponsors/jcubic","https://ko-fi.com/jcubic","https://www.paypal.me/jcubic"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcubic%2Flips","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcubic%2Flips","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcubic%2Flips/lists"}