`lisscad` is a library for generating OpenSCAD code from Lissp scripts.
Don’t worry! You’re not supposed to track all the parentheses yourself. With an
automatic formatter like `parinfer`, Lissp is easier than Python.
## Features
* The terseness of Lisp.
* The usability of Lisp. For example, with the `-<>>` “thread-through” macro of
Lissp, you can code for OpenSCAD operations in the order that they will be
executed, instead of the order they have in OpenSCAD scripts.
* The `lisscad` package is executable on the command line to manage CAD
projects. This includes support for tracking a project with `inotify` to
re-render work in progress.
* Boilerplate is minimal and explicit. It takes one line in CAD scripts to
import `lisscad`, and one line to transpile to OpenSCAD. Both of these and a
Git repo are included in a template for new projects.
* Most of `lisscad` is pure, type-annotated Python 3.10+. It can be used
without the Lissp layer. Conversely, you can use any Python code from Lissp.
The data model is based on dataclasses, not object-oriented Python. Pydantic
handles type conversions for you in the back end.
See also the [goals](doc/goal.md) of the project.
## Installation
On Linux:
pip install lisscad
At minimum, you also need OpenSCAD, which you must install separately. There
are several ways to do that. For example:
sudo snap install openscad
Conveniences built into `lisscad` assume that you also have `nohup` and `git`
installed.
### Editor integration
Lissp is not a common dialect, so you may need to inform your text editor that
it is Lisp. For example, if you are using Neovim, you can add the following to
`~/.config/nvim/init.vim`:
au BufRead,BufNewFile *.lissp setfiletype lisp
For Vim, only the file path is different (`~/.vimrc`).
[`parinfer-rust`](https://github.com/eraserhd/parinfer-rust) is an
excellent Lisp autoformatter for Vim, Neovim, and other editors.
## Usage
### Command-line interface
To start a new project:
```shell
lisscad new myproject
cd myproject
```
The shape of your model(s) is defined by `main.lissp`. Edit it. To render your
project to OpenSCAD once, run the normal Lissp compiler:
```shell
lissp main.lissp
```
To render a 3D model all the way to STL, pass a CLI argument via the Lissp
compiler with `--`:
```shell
lissp main.lissp -- -r
lissp main.lissp -- --render # Equivalent long option.
```
To view the most recently transpiled model in the OpenSCAD GUI:
```shell
lisscad view
```
To automatically transpile to OpenSCAD each time you edit `main.lissp`, so that
the GUI always shows the current version:
```shell
lisscad track
```
### Scripting interface
The vocabulary of `lisscad` is very similar to that of OpenSCAD.
However, some function signatures have been adjusted to reduce the overall
complexity of the interface.
* Example: `lisscad`’s `cube` is centred by default, because `sphere` is
centred in both OpenSCAD and `lisscad`.
* Example: If you want to use a keyword argument to define an angle, it’s named
`angle`; it doesn’t vary.
For maximum fidelity to OpenSCAD, use the `lisp` prelude:
```lisp
(lisscad.prelude.._macro_.lisp)
(translate '(1 0) (square '(2 3)))
```
`lisscad` gives you the option of consistency with standard geometric and
English terms instead. For example, in its `english` prelude, `lisscad` has a
`square` function that draws squares, and a `rectangle` function that draws
rectangles.
```lisp
(lisscad.prelude.._macro_.english)
(right 1 (rectangle '(2 3)))
```
When you run `lisscad new`, you get a version of the `english` prelude called
`english-util`. Named on a single line, this prelude combines the vocabulary of
`english` with a set of higher-level utilities built into `lisscad`.
For the use of operators like `+`, see [here](doc/op.md).
## History
`lisscad` is loosely patterned after `scad-clj`, ported from Clojure to another
dialect of Lisp. The new dialect, and `lisscad` itself, are implemented in
Python. This makes `lisscad` comparable to numerous Python-based OpenSCAD
generators/transpilers, including SolidPython, SolidPy, `openpyscad`,
`pycad`, `py2scad`, `py-scad` and `pyscad`.
`lisscad` was started to combine the best of its two ancestries: The simplicity
and elegance of a Lisp similar to Clojure, and the JVM-free accessibility and
startup time of Python. One notable difference is that whereas `scad-clj` uses
hash tables as an implementation detail in its intermediate data model, and
SolidPython has its own object-oriented data model, `lisscad` uses Pydantic
dataclasses.
## Legal
Copyright (C) 2022–2023 Viktor Eikman
`lisscad` is licensed as detailed in the accompanying file COPYING.md.
Raw data
{
"_id": null,
"home_page": "",
"name": "lisscad",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "CAD,CSG,Lissp,OpenSCAD,code generation,geometry,lisp,modeling",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/97/82/5c72510d770f02a5636bb82f10010bda52908a56ac62f91e032cc8cbefb8/lisscad-0.1.0.tar.gz",
"platform": null,
"description": "`lisscad` is a library for generating OpenSCAD code from Lissp scripts.\n\nDon\u2019t worry! You\u2019re not supposed to track all the parentheses yourself. With an\nautomatic formatter like `parinfer`, Lissp is easier than Python.\n\n## Features\n\n* The terseness of Lisp.\n* The usability of Lisp. For example, with the `-<>>` \u201cthread-through\u201d macro of\n Lissp, you can code for OpenSCAD operations in the order that they will be\n executed, instead of the order they have in OpenSCAD scripts.\n* The `lisscad` package is executable on the command line to manage CAD\n projects. This includes support for tracking a project with `inotify` to\n re-render work in progress.\n* Boilerplate is minimal and explicit. It takes one line in CAD scripts to\n import `lisscad`, and one line to transpile to OpenSCAD. Both of these and a\n Git repo are included in a template for new projects.\n* Most of `lisscad` is pure, type-annotated Python 3.10+. It can be used\n without the Lissp layer. Conversely, you can use any Python code from Lissp.\n\nThe data model is based on dataclasses, not object-oriented Python. Pydantic\nhandles type conversions for you in the back end.\n\nSee also the [goals](doc/goal.md) of the project.\n\n## Installation\n\nOn Linux:\n\n pip install lisscad\n\nAt minimum, you also need OpenSCAD, which you must install separately. There\nare several ways to do that. For example:\n\n sudo snap install openscad\n\nConveniences built into `lisscad` assume that you also have `nohup` and `git`\ninstalled.\n\n### Editor integration\n\nLissp is not a common dialect, so you may need to inform your text editor that\nit is Lisp. For example, if you are using Neovim, you can add the following to\n`~/.config/nvim/init.vim`:\n\n au BufRead,BufNewFile *.lissp setfiletype lisp\n\nFor Vim, only the file path is different (`~/.vimrc`).\n[`parinfer-rust`](https://github.com/eraserhd/parinfer-rust) is an\nexcellent Lisp autoformatter for Vim, Neovim, and other editors.\n\n## Usage\n\n### Command-line interface\n\nTo start a new project:\n\n```shell\nlisscad new myproject\ncd myproject\n```\n\nThe shape of your model(s) is defined by `main.lissp`. Edit it. To render your\nproject to OpenSCAD once, run the normal Lissp compiler:\n\n```shell\nlissp main.lissp\n```\n\nTo render a 3D model all the way to STL, pass a CLI argument via the Lissp\ncompiler with `--`:\n\n```shell\nlissp main.lissp -- -r\nlissp main.lissp -- --render # Equivalent long option.\n```\n\nTo view the most recently transpiled model in the OpenSCAD GUI:\n\n```shell\nlisscad view\n```\n\nTo automatically transpile to OpenSCAD each time you edit `main.lissp`, so that\nthe GUI always shows the current version:\n\n```shell\nlisscad track\n```\n\n### Scripting interface\n\nThe vocabulary of `lisscad` is very similar to that of OpenSCAD.\nHowever, some function signatures have been adjusted to reduce the overall\ncomplexity of the interface.\n\n* Example: `lisscad`\u2019s `cube` is centred by default, because `sphere` is\n centred in both OpenSCAD and `lisscad`.\n* Example: If you want to use a keyword argument to define an angle, it\u2019s named\n `angle`; it doesn\u2019t vary.\n\nFor maximum fidelity to OpenSCAD, use the `lisp` prelude:\n\n```lisp\n(lisscad.prelude.._macro_.lisp)\n\n(translate '(1 0) (square '(2 3)))\n```\n\n`lisscad` gives you the option of consistency with standard geometric and\nEnglish terms instead. For example, in its `english` prelude, `lisscad` has a\n`square` function that draws squares, and a `rectangle` function that draws\nrectangles.\n\n```lisp\n(lisscad.prelude.._macro_.english)\n\n(right 1 (rectangle '(2 3)))\n```\n\nWhen you run `lisscad new`, you get a version of the `english` prelude called\n`english-util`. Named on a single line, this prelude combines the vocabulary of\n`english` with a set of higher-level utilities built into `lisscad`.\n\nFor the use of operators like `+`, see [here](doc/op.md).\n\n## History\n\n`lisscad` is loosely patterned after `scad-clj`, ported from Clojure to another\ndialect of Lisp. The new dialect, and `lisscad` itself, are implemented in\nPython. This makes `lisscad` comparable to numerous Python-based OpenSCAD\ngenerators/transpilers, including SolidPython, SolidPy, `openpyscad`,\n`pycad`, `py2scad`, `py-scad` and `pyscad`.\n\n`lisscad` was started to combine the best of its two ancestries: The simplicity\nand elegance of a Lisp similar to Clojure, and the JVM-free accessibility and\nstartup time of Python. One notable difference is that whereas `scad-clj` uses\nhash tables as an implementation detail in its intermediate data model, and\nSolidPython has its own object-oriented data model, `lisscad` uses Pydantic\ndataclasses.\n\n## Legal\n\nCopyright (C) 2022\u20132023 Viktor Eikman\n\n`lisscad` is licensed as detailed in the accompanying file COPYING.md.\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "CAD in Lissp",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"cad",
"csg",
"lissp",
"openscad",
"code generation",
"geometry",
"lisp",
"modeling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "57533567fa60cefa1ffb6b0f60d7d25ef435fe33282ead2205068988f2d96d86",
"md5": "787541da8b6d33d3c47d18f61c574d3a",
"sha256": "c502bc219c95dab4f9f1f6767d6afdd970f831c475379229fe4e36cae2d4fbe2"
},
"downloads": -1,
"filename": "lisscad-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "787541da8b6d33d3c47d18f61c574d3a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 44409,
"upload_time": "2023-12-10T21:21:19",
"upload_time_iso_8601": "2023-12-10T21:21:19.833746Z",
"url": "https://files.pythonhosted.org/packages/57/53/3567fa60cefa1ffb6b0f60d7d25ef435fe33282ead2205068988f2d96d86/lisscad-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "97825c72510d770f02a5636bb82f10010bda52908a56ac62f91e032cc8cbefb8",
"md5": "e67b4b6ac89f72a9bb5d00989c0a0e27",
"sha256": "31fce8c8060933548ac3f44bfae5919855a590c0dca4fcb79df27f1ec26fcdf4"
},
"downloads": -1,
"filename": "lisscad-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e67b4b6ac89f72a9bb5d00989c0a0e27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 42205,
"upload_time": "2023-12-10T21:21:22",
"upload_time_iso_8601": "2023-12-10T21:21:22.167696Z",
"url": "https://files.pythonhosted.org/packages/97/82/5c72510d770f02a5636bb82f10010bda52908a56ac62f91e032cc8cbefb8/lisscad-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-10 21:21:22",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "lisscad"
}
JSON