{"id":13594877,"url":"https://github.com/letoram/pipeworld","last_synced_at":"2025-07-18T03:07:11.201Z","repository":{"id":48326875,"uuid":"357116616","full_name":"letoram/pipeworld","owner":"letoram","description":"Dataflow 'spreadsheet' desktop environment","archived":false,"fork":false,"pushed_at":"2023-11-03T07:46:42.000Z","size":1201,"stargazers_count":173,"open_issues_count":1,"forks_count":6,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-07-07T19:16:20.213Z","etag":null,"topics":["desktop-environment","graphics","linux","spreadsheet","tiling-window-manager","zui"],"latest_commit_sha":null,"homepage":"https://arcan-fe.com","language":"Lua","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/letoram.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"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}},"created_at":"2021-04-12T08:32:09.000Z","updated_at":"2025-07-01T19:30:15.000Z","dependencies_parsed_at":"2023-02-19T02:15:28.054Z","dependency_job_id":"3388efe6-f792-4497-a730-96bb1c371796","html_url":"https://github.com/letoram/pipeworld","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/letoram/pipeworld","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Fpipeworld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Fpipeworld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Fpipeworld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Fpipeworld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/letoram","download_url":"https://codeload.github.com/letoram/pipeworld/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Fpipeworld/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264503949,"owners_count":23618762,"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":["desktop-environment","graphics","linux","spreadsheet","tiling-window-manager","zui"],"created_at":"2024-08-01T16:01:40.356Z","updated_at":"2025-07-09T21:30:31.944Z","avatar_url":"https://github.com/letoram.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"About\n=====\n\nPipeworld is a zooming dataflow tool and desktop heavily inspired by\n[userland](https://www.userland.org). It is built using the [arcan desktop\nengine](https://arcan-fe.com) [git](https://github.com/letoram/arcan).\n\nIt combines the programmable processing of shell scripts and pipes, the\ninteractive visual addressing/programming model of spread sheets, the\nscenegraph- and interactive controls-, IPC- and client processing- of display\nservers into one model with zoomable tiling window management.\n\nIt can be used as a standalone desktop of its own, or as a normal application\nwithin another desktop as a 'substitute' for your normal terminal emulator.\n\nIt is described further in the article here:\n[introducing pipeworld](https://arcan-fe.com/2021/04/12/introducing-pipeworld)\n\nA longer video clip showcasing some features can be found here:\n[Youtube - UI Demo](https://www.youtube.com/watch?v=zZqKD-p4GpE)\n\nContact\n=======\nOnly use github issues for real bugs, not for support or wishful thinking\nabout features you dream of someone developing for you.\n\nOldschool chatter at #arcan on irc.freenode.net.\n\nDiscord invite at http://chat.divergent-desktop.org.\n\nSee the 'HACKING.md' for ways to contribute, 'TODO.md' for smaller things in\nthe near future and 'IDEAS.md' for bigger projects.\n\nUse\n===\n\n*This project is used to drive the development of Arcan further, and requires a\nvery recent build of Arcan to work properly or even at all. Relying on packages\nfrom your distribution can have weird and unexpected behaviour. Don't report\nissues unless you are running with the current master branch of Arcan first.*\n\nAssuming a working arcan installation, entering pipeworld should be no more\ndifficult than:\n\n    arcan /path/to/pipeworld/pipeworld\n\nOr just:\n\n    arcan pipeworld\n\nIf it is added into your arcan applpath (.arcan/appl or /usr/share/arcan/appl).\n\nYou might want to look at the bindings.lua and config.lua lua files to modify\ninput controls and look/feel first, particularly the meta keys as those tend to\nbe different if you are running standalone or as part of another desktop.\n\nThe model is fairly simple:\n\nYou have _rows_ and _cells_. A _row_ act as a container (visual partition and\nlogical address) of a chain of 1..n cells, and each cell represents a data\nconsumer, producer or producer-consumer.\n\nThe first cell in a row defines how the row behaves, it is 'typed', see the\n'Cell Model' section further below for more details.\n\nBy default, the first cell you will see is of the expression type, and it is\nthe cell type that will be created by default when a new row is built.\n\nThis cell acts as a namespaced command-line interface, see 'Expression Cell'\nfurther below. Worthwhile to know:\n\n    :shutdown()\n\nWill cause the system function 'shutdown' to be called.\n\nThe window management style is 'zooming-tiling' - each logical group (cell,\nrow, world) has a magnification level and a density level. The easiest way to\nget a feel for how this works is to use a mouse, and then add the patterns you\nestablish as keybindings.\n\nActions to try out:\n\n * mouse wheel on background (zoom in/out all)\n * mouse l-drag on background (pan)\n * mouse l-drag+rbutton on background (zoom in/out selected row)\n * double-click on background (toggle 1:1 or last zoom)\n * double-click on row (toggle 1:1 or last zoom for row)\n * mouse wheel on row background (zoom row in / out)\n * double-click on cell (toggle 1:1)\n * right-click on background, row-background and cell label\n\nThese actions all change the magnification or 'scale' the contents of the cell,\nthus the clients do not receive any notifications to try and resize which is a\nmuch more expensive option.\n\nConfiguration\n=============\n\nCheck 'pipeworld/keybindings.lua' for default input bindings and for adding\nyour own. These map to one or many commands from the 'pipeworld/commands.lua'\nfile.\n\nTo see most of the currently available commands:\n\n    grep cmdtree commands.lua\n\nThe commands and tools will be documented when the project is a bit more mature\nand the set has stabilized.\n\nSets of commands can also be at startup. These are defined in the\n'pipeworld/scripts/autorun.lua' file. Other scripts in this folder can also be\nrun at startup like this:\n\n    arcan pipeworld tests/listen.lua\n\nWhich would run the test script 'listen.lua' in pipeworld/scripts/tests.\n\nThe 'devmaps' folder contains configuration files for tool (optional plugins),\nadvanced input and client colorschemes.\n\nTo change visuals, window management behaviour, animation speed and so on,\nsee the 'pipeworld/config.lua' file. To avoid modifying it directly and risking\nmerge collisions when we update and extend the set of options, you can\ncreate sets of configuration overrides in the pipeworld/devmaps/themes folder.\n\nThese can be switched to at runtime by running the system expression:\n\n    :theme(\"mytheme\")\n\nSee further below for an explanation on running expressions.\n\nThe pipeworld/devmaps/themes/default.lua will be set automatically on startup,\nand will remain empty in the git for the purpose of easy modification.\n\nPopups\n======\n\nIn the menus/ folder you will find bindings that control the various popups\nthat can be triggered on mouse or command bindings. These map to commands in\ncommand.lua, so it is trivial to extend with your own.\n\nThese are:\n\n * system.lua (right-click wallpaper for system context menu)\n * label.lua (right-click on text label)\n * insert.lua (rclick on-over surface below last row)\n * row.lua (rclick on row background)\n\nAutomation / Testing\n====================\n\nAny arguments passed after 'pipeworld' on the command line will be treated as a\nreferences to entries in the scripts/ subdirectory. These are simply tables of\ncommands matching the same set of actions available to keybindings, and will be\nexecuted in the same order as provided on the command line.\n\nThis can be used to setup your default workspace as well as for testing changes.\n\nCell Model\n==========\n\nCells are typed, and the type of the cell itself defines how it and other cells\nin the row will behave, the inputs it will accept and the outputs it can\nprovide.\n\nCells has an evolving set of properties and parameters, some experimental and\nundocumented for the time being.\n\nThe short list of existing cell types and their arguments is as follows:\n\n* expression([preset], [commit], [namespace])\n* capture([identifier]) - arcan-decode (afsrv\\_decode) capture support (e.g. webcam)\n* cli([w], [h], [arg], [detach]) - arcan builtin command-line\n* compose(cell1, cell2, ...) - merge together contents from other cells\n* debug(cell, [builtin]) - inject a debug window into a client\n* image(resource) - single image loading\n* listen(name) - opens a connection point for redirecting clients to (ARCAN\\_CONNPATH=name)\n* term([cmd]) - terminal emulator\n* target([name]) - launching a specific application (see below)\n* adopt([vid]) - special case, used internally\n\n## Expression Cell\n\nThe main cell type that you will deal with is the 'Expression' cell, and it is\nthe default when you click to add a new cell, as shown in the clip here:\n\nSome things to note about the expression cell:\n\n1. `#` switches to CLI mode\n2. `!` switches to Terminal mode (bash) or terminal-exec e.g. ! /bin/ls\n3. `:` evaluates in 'system' scope\n4. `.` evaluates in 'cell' scope\n5. all other expressions are in normal ('expression') scope.\n\nA cell that has changed or derived from cell-action can be reverted to its\ninitial state through the /revert/cell command path, discarding any previous\ncontents.\n\nThe 'expression' scope is the default scope for builtin functions. It should\nbe the one most commonly use and support basic arithmetic and other kinds of\nexpressions:\n\n     1 + 2 * A1 + max(A2, B2)\n\nAn expression cell can also be used as a popup with a certain scope. The two\ncommands for that are '/cursor/cellexpr' and 'cursor/sysexpr' respectively.\n(Default binding to m1+s for system and m1+d for cell).\n\nIn those cases the scope prefix (. or :) is implied and forced.\n\nSome functions support completion and argument type helpers, use 'TAB' to\nbring up the completion, and F1 for the helper text.\n\nThe rule of thumb is that functions that have a global effect, such as\ncreating new cells, modifying inputs and so on are added to the system scope.\nFunctions that change cell properties, such as assigning an alias tag:\n\n    .tag(\"hi\")\n\nBelong to the cell scope. Each function exists as a single file in\ncells/api/[system,cell,expression] and are scanned on startup.\n\nJust like with the bindable 'commands.lua', the set of functions is evolving\nand is currently undocumented. See the following folders:\n\n    pipeworld/cells/api/expression\n    pipeworld/cells/api/system\n    pipeworld/cells/api/cell\n    pipeworld/cells/api/factory\n\nFor the current commands (one file per command). The 'factory' folder is\na bit special and will result in commands in both cell and system scope.\n\n## Terminal Cell\n\nThe terminal cell is simply a Vt100 compatible terminal emulator. It can\nbe switched to from the expression cell by entering '#' or run a single command\nwith:\n\n    ! ls /usr\n\nThat can also be bound as a menu entry, keybinding or similar :\n\n    {\"/insert/row/term\", \"find /usr\"}\n\n## Target Cell\n\nArcan has a facility for defining external programs that can be launched, and\nhow those are setup. See the 'arcan\\_db' tool manpage for more details, but the\nshort version is:\n\n    arcan_db add_target BIN mytool /usr/bin/mytool arg1 arg2\n    arcan_db add_config mytool test arg3 arg4\n\n    {\"/insert/row/target\", \"mytool\", \"test\"}\n\nWhich would spawn a new process with an inherited connection through\n'/usr/bin/mytool arg1 arg2 arg3 arg4'. This is only for applications that use\nArcans native client APIs (SHMIF and TUI). This includes other protocol\nbridging tools, such as arcan-wayland (again using arcan\\_db):\n\n    add_target BIN weston-terminal /usr/bin/arcan-wayland -exec weston-terminal\n    add_target BIN chromium-x11wl /usr/bin/arcan-wayland -exec-x11 chromium\n    add_target BIN chromium-x11 /usr/bin/arcan_xwm -Xarcan chromium\n\n## CLI mode\n\nThe external CLI is part of Arcan, and while it looks like a normal 'terminal'\nprompt, it is not. The set of built-in commands it provides is limited, and it\nis mainly useful for launching other programs.\n\nThe 'cd' command changes the current directory, while 'mode' changes execution\nmode.  This is important as different clients have different needs from its\nenvironment in order to connect properly.\n\nThe different modes are:\n\n    x11\n    wayland\n    vt100 (will wrap through a terminal emulator)\n    arcan\n\ne.g.\n\n    mode x11\n    chromium\n\nWould start chromium under X11.\n\nThe 'open' command will treat its argument as a media file, and the supported\nformats are limited by what 'afsrv_decode' in arcan is compiled to handle.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletoram%2Fpipeworld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fletoram%2Fpipeworld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletoram%2Fpipeworld/lists"}