1<img align="left" width="183" height="154" src="logo.svg" /> 2 3# up - the Ultimate Plumber 4 5**up** is the **Ultimate Plumber**, a tool for writing Linux pipes in a 6terminal-based UI interactively, with instant live preview of command results. 7 8The main **goal** of the Ultimate Plumber is to help **interactively and 9incrementally explore textual data** in Linux, by making it easier to quickly 10build complex pipelines, thanks to a **fast feedback loop**. This is achieved 11by boosting any typical **Linux text-processing utils** such as `grep`, `sort`, 12`cut`, `paste`, `awk`, `wc`, `perl`, etc., etc., by providing a quick, 13**interactive, scrollable preview** of their results. 14 15[](https://asciinema.org/a/208538) 16 17## Usage 18 19**[Download *up* for Linux](https://github.com/akavel/up/releases/download/v0.3.2/up)** 20 | [ArchLinux](https://wiki.archlinux.org/index.php/Arch_User_Repository): [`aur/up`](https://aur.archlinux.org/packages/up/) 21 | FreeBSD: [`pkg install up`](https://www.freshports.org/textproc/up) 22 | macOS: [`brew install up`](https://formulae.brew.sh/formula/up) 23 | [Other OSes](https://github.com/akavel/up/releases) 24 25To start using **up**, redirect any text-emitting command (or pipeline) into it 26— for example: 27 28 $ lshw |& ./up 29 30then: 31 32- use ***PgUp/PgDn*** and ***Ctrl-[←]/Ctrl-[→]*** for basic browsing through 33 the command output; 34- in the input box at the top of the screen, start **writing any bash 35 pipeline**; then **press Enter to execute the command you typed**, 36 and the Ultimate Plumber will immediately show you the output of 37 the pipeline in the **scrollable window** below (replacing any 38 earlier contents) 39 - For example, you can try writing: 40 `grep network -A2 | grep : | cut -d: -f2- | paste - -` 41 — on my computer, after pressing *Enter*, the screen then shows 42 the pipeline and a scrollable preview of its output like below: 43 44 | grep network -A2 | grep : | cut -d: -f2- | paste - - 45 Wireless interface Centrino Advanced-N 6235 46 Ethernet interface RTL8111/8168/8411 PCI Express Gigabit Ethernet Controller 47 48 - **WARNING: Please be careful when using it! It could be dangerous.** 49 In particular, writing "rm" or "dd" into it could be like running around 50 with a chainsaw. But you'd be careful writing "rm" anywhere in Linux 51 anyway, no? 52- when you are satisfied with the result, you can **press *Ctrl-X* to exit** 53 the Ultimate Plumber, and the command you built will be **written into 54 `up1.sh` file** in the current working directory (or, if it already existed, 55 `up2.sh`, etc., until 1000, based on [Shlemiel the Painter's 56 algorithm](https://www.joelonsoftware.com/2001/12/11/back-to-basics/)). 57 Alternatively, you can press ***Ctrl-C*** to quit without saving. 58- If the command you piped into *up* is long-running (in such case you will see 59 a tilde `~` indicator character in the top-left corner of the screen, meaning 60 that *up* is still waiting for more input), you may need to press 61 ***Ctrl-S*** to temporarily freeze *up*'s input buffer (a freeze will be 62 indicated by a `#` character in top-left corner), which will inject a fake 63 EOF into the pipeline; otherwise, some commands in the pipeline may not print 64 anything, waiting for full input (especially commands like `wc` or `sort`, 65 but `grep`, `perl`, etc. may also show incomplete results). To unfreeze back, 66 press ***Ctrl-Q***. 67 68## Additional Notes 69 70- The pipeline is passed verbatim to a `bash -c` command, so any bash-isms should work. 71- The input buffer of the Ultimate Plumber is currently fixed at **40 MB**. If 72 you reach this limit, a `+` character should get displayed in the top-left 73 corner of the screen. (This is intended to be changed to a 74 dynamically/manually growable buffer in a future version of *up*.) 75- **MacOSX support:** I don't have a Mac, thus I have no idea if it works on 76 one. You are welcome to try, and also to send PRs. If you're interested in 77 me providing some kind of official-like support for MacOSX, please consider 78 trying to find a way to send me some usable-enough Mac computer. Please note 79 I'm not trying to "take advantage" of you by this, as I'm actually not at all 80 interested in achieving a Mac otherwise. (Also, trying to commit to this kind 81 of support will be an extra burden and obligation on me. Knowing someone out 82 there cares enough to do a fancy physical gesture would really help alleviate 83 this.) If you're serious enough to consider this option, please contact me by 84 email (mailto:czapkofan@gmail.com) or keybase (https://keybase.io/akavel), so 85 that we could try to research possible ways to achieve this. 86 Thanks for understanding! 87- **Prior art:** I was surprised no one seemed to write a similar tool before, 88 that I could find. It should have been possible to write this since the dawn 89 of Unix already, or earlier! And indeed, after I announced *up*, I got enough 90 publicity that my attention was directed to one such earlier project already: 91 **[Pipecut](http://pipecut.org/index.html)**. Looks interesting! You may like 92 to check it too! (Thanks [@TronDD](https://lobste.rs/s/acpz00/up_tool_for_writing_linux_pipes_with#c_qxrgoa).) 93- **Other influences:** I don't remember the fact too well already, but I'm 94 rather sure that this must have been inspired in big part by The Bret Victor's Talk(s). 95 96## Future Ideas 97 98- I have quite a lot of ideas for further experimentation of development of 99 *up*, including but not limited to: 100 - [RIIR](https://rust-lang.org) (once I learn enough of Rust... at some 101 point in future... maybe...) — esp. to hopefully make *up* be a smaller 102 binary (and also to maybe finally learn some Rust); though I'm somewhat 103 afraid if it might ossify the codebase and make harder to develop 104 further..? ...but maybe actually converse?... 105 - Maybe it could be made into an UI-less, RPC/REST/socket/text-driven 106 service, like gocode or [Language Servers](https://langserver.org/), for 107 integration with editors/IDEs (emacs? vim? VSCode?...) I'd be especially 108 interested in eventually merging it into [Luna 109 Studio](https://luna-lang.org/); RIIR may help in this. (Before this, as 110 a simpler approach, multi-line editing may be needed, or at least 111 left&right scrolling of the command editor input box. Also, some kind of 112 jumping between words in the command line; readline's *Alt-b* & *Alt-f*?) 113 - Make it possible to [capture output of already running 114 processes](https://stackoverflow.com/a/19584979/98528)! (But maybe that 115 could be better made as a separate, composable tool! In Rust?) 116 - Adding tests... (ahem; see also 117 [#1](https://github.com/akavel/up/issues/1)) ...also write `--help`... 118 - Making it work on Windows, 119 somehow[?](https://github.com/mattn/go-shellwords) Also, obviously, would 120 be nice to have some CI infrastructure enabling porting it to MacOSX, 121 BSDs, etc., etc... 122 - Integration with [fzf](https://github.com/junegunn/fzf) and other TUI 123 tools? I only have some vague thoughts and ideas about it as of now, not 124 even sure how this could look like. 125 - Adding more previews, for each `|` in the pipeline; also forking of 126 pipelines, merging, feedback loops, and other mixing and matching (though 127 I'd strongly prefer if [Luna](https://luna-lang.org) was to do it 128 eventually). 129- If you are interested in financing my R&D work, contact me by email at: 130 czapkofan@gmail.com, or [on keybase.io as akavel](https://keybase.io/akavel). 131 I suppose I will probably be developing the Ultimate Plumber further anyway, 132 but at this time it's purely a hobby project, with all the fun and risks this 133 entails. 134 135— *Mateusz Czapliński* 136*October 2018* 137 138*PS. The UP logo was conceived and generously sponsored 139by [Thoai Nguyen](https://github.com/thoaionline) 140and [GPU Exchange](https://gpu.exchange/), 141with a helping hand from [Many Pixels](https://www.manypixels.co/).* 142
