add README

3 files changed, 144 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4264096
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+**up** is the **Ultimate Plumber**, a tool for writing Linux pipes in a
+terminal-based UI interactively, with instant live preview of command results.
+
+The main **goal** of the Ultimate Plumber is to help **interactively and
+incrementally explore textual data** in Linux, by making it easier to quickly
+build complex pipelines, thanks to a **fast feedback loop**. This is achieved
+by boosting any typical **Linux text-processing utils** such as `grep`, `sort`,
+`cut`, `paste`, `awk`, `wc`, `perl`, etc., etc., by providing a quick,
+**interactive, scrollable preview** of their results.
+
+![](up.gif)
+
+To start using **up**, redirect any text-emitting command (or pipeline) into it
+— for example:
+
+    $ lshw |& ./up
+
+then:
+
+- use PgUp/PgDn and Ctrl-[←]/Ctrl-[→] for basic browsing through the command output;
+- in the input box at the top of the screen, start **writing any bash
+  pipeline**; the Ultimate Plumber will **execute the command as you type it**,
+  and immediately show you the output of the pipeline in the **scrollable
+  window** below (replacing any earlier contents);
+    - For example, you can try writing:
+      `grep network -A2 | grep : | cut -d: -f2- | paste - -`
+      — on my computer, the screen then shows the pipeline and a scrollable
+      preview of its output like below:
+
+             | grep network -A2 | grep : | cut -d: -f2- | paste - -
+             Wireless interface      Centrino Advanced-N 6235
+             Ethernet interface      RTL8111/8168/8411 PCI Express Gigabit Ethernet Controller
+
+- when you are satisfied with the result, you can **press *Ctrl-X* to exit**
+  the Ultimate Plumber, and the command you built will be **written into
+  `up1.sh` file** in the current working directory (or, if it already existed,
+  `up2.sh`, etc., until 1000, based on [Shlemiel the Painter's
+  algorithm](https://www.joelonsoftware.com/2001/12/11/back-to-basics/)).
+  Alternatively, you can press *Ctrl-C* to quit without saving.
+- If the command you piped into *up* is long-running (in such case you will see
+  a tilde `~` indicator character in the top-left corner of the screen, meaning
+  that *up* is still waiting for more input), you may need to press *Ctrl-S* to
+  temporarily freeze *up*'s input buffer (a freeze will be indicated by a `#`
+  character in top-left corner), which will inject a fake EOF into the
+  pipeline; otherwise, some commands in the pipeline may not print anything,
+  waiting for full input (especially commands like `wc` or `sort`, but `grep`,
+  `perl`, etc. may also show incomplete results). To unfreeze back, press
+  *Ctrl-Q*.
+
+Additional notes:
+
+- The pipeline is passed verbatim to a `bash -c` command, so any bash-isms should work.
+- The input buffer of the Ultimate Plumber is currently fixed at **40 MB**. If
+  you reach this limit, a `+` character should get displayed in the top-left
+  corner of the screen. (This is intended to be changed to a
+  dynamically/manually growable buffer in a future version of *up*.)
+
+Future Ideas:
+
+- This is version 0.1 of *the Ultimate Plumber*: a minimal viable product I was
+  comfortable to release to the public, hoping it might be of use to some of
+  you already.
+- I have quite a lot of ideas for further experimentation of development of
+  *up*, including but not limited to:
+    - [RIIR](https://rust-lang.org) (once I learn enough of Rust... at some
+      point in future... maybe...) — esp. to hopefully make *up* be a smaller
+      binary (and also to maybe finally learn some Rust); though I'm somewhat
+      afraid if it might ossify the codbase and make harder to develop
+      further..? ...but maybe actually converse?...
+    - Maybe it could be made into an UI-less, RPC/REST/socket/text-driven
+      service, like gocode or [Language Servers](https://langserver.org/), for
+      integration with editors/IDEs (emacs? vim? VSCode?...) I'd be especially
+      interested in eventually merging it into [Luna
+      Studio](https://luna-lang.org/); RIIR may help in this. (Before this, as
+      a simpler approach, multi-line editing may be needed, or at least
+      left&right scrolling of the command editor input box. Also, some kind of
+      jumping between words in the command line; readline's *Alt-b* & *Alt-f*?)
+    - Make it possible to [capture output of already running
+      processes](https://stackoverflow.com/a/19584979/98528)! (But maybe that
+      could be better made as a separate, composable tool! In Rust?)
+    - Adding tests... (ahem; see also
+      [#1](https://github.com/akavel/up/issues/1)) ...also write `--help`...
+    - Making it work on Windows,
+      somehow[?](https://github.com/mattn/go-shellwords) Also, obviously, would
+      be nice to have some CI infrastructure enabling porting it to MacOSX,
+      BSDs, etc., etc...
+    - Integration with [fzf](https://github.com/junegunn/fzf) and other TUI
+      tools? I only have some vague thoughts and ideas about it as of now, not
+      even sure how this could look like.
+    - Adding more previews, for each `|` in the pipeline; also forking of
+      pipelines, merging, feedback loops, and other mixing and matching (though
+      I'd strongly prefer if [Luna](https://luna-lang.org) was to do it
+      eventually).
+- I'm interested in a lot of possible further directions
+- If you are interested in financing my R&D work, contact me by email at:
+  czapkofan@gmail.com, or [on keybase.io as akavel](https://keybase.io/akavel).
+  I suppose I will probably be developing the Ultimate Plumber further anyway,
+  but at this time it's purely a hobby project, with all the fun and risks this
+  entails.
+
diff --git a/go.sum b/go.sum
new file mode 100644
index 0000000..b8e1a8c
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,44 @@
+github.com/fsnotify/fsnotify v1.4.7 h1:IXs+QLmnXW2CcXuY+8Mzv/fWEsPGWxqefPtCP5CnV9I=
+github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
+github.com/gdamore/encoding v0.0.0-20151215212835-b23993cbb635 h1:hheUEMzaOie/wKeIc1WPa7CDVuIO5hqQxjS+dwTQEnI=
+github.com/gdamore/encoding v0.0.0-20151215212835-b23993cbb635/go.mod h1:yrQYJKKDTrHmbYxI7CYi+/hbdiDT2m4Hj+t0ikCjsrQ=
+github.com/gdamore/tcell v0.0.0-20180924055237-493f3b46b3c2 h1:tjZy+seLHD3Rokr7cZys2Ym+G/ay2IoyFTq+gVLNiDc=
+github.com/gdamore/tcell v0.0.0-20180924055237-493f3b46b3c2/go.mod h1:tqyG50u7+Ctv1w5VX67kLzKcj9YXR/JSBZQq/+mLl1A=
+github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1 h1:EGx4pi6eqNxGaHF6qqu48+N2wcFQ5qg5FXgOdqsJ5d8=
+github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
+github.com/jtolds/gls v4.2.1+incompatible h1:fSuqC+Gmlu6l/ZYAoZzx2pyucC8Xza35fpRVWLVmUEE=
+github.com/jtolds/gls v4.2.1+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
+github.com/kisielk/gotool v1.0.0 h1:AV2c/EiW3KqPNT9ZKl07ehoAGi4C5/01Cfbblndcapg=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/lucasb-eyer/go-colorful v0.0.0-20170903184257-231272389856 h1:r+WvXmgROttp7pckv7TPN7OCUEPXmvhRklOOsL2iPPc=
+github.com/lucasb-eyer/go-colorful v0.0.0-20170903184257-231272389856/go.mod h1:NXg0ArsFk0Y01623LgUqoqcouGDB+PwCCQlrwrG6xJ4=
+github.com/mattn/go-isatty v0.0.3 h1:ns/ykhmWi7G9O+8a448SecJU3nSMBXJfqQkl0upE1jI=
+github.com/mattn/go-isatty v0.0.3/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4=
+github.com/mattn/go-runewidth v0.0.2 h1:UnlwIPBGaTZfPQ6T1IGzPI0EkYAQmT9fAEJ/poFC63o=
+github.com/mattn/go-runewidth v0.0.2/go.mod h1:LwmH8dsx7+W8Uxz3IHJYH5QSwggIsqBzpuz5H//U1FU=
+github.com/mattn/go-runewidth v0.0.3 h1:a+kO+98RDGEfo6asOGMmpodZq4FNtnGP54yps8BzLR4=
+github.com/mattn/go-runewidth v0.0.3/go.mod h1:LwmH8dsx7+W8Uxz3IHJYH5QSwggIsqBzpuz5H//U1FU=
+github.com/neelance/astrewrite v0.0.0-20160511093645-99348263ae86 h1:D6paGObi5Wud7xg83MaEFyjxQB1W5bz5d0IFppr+ymk=
+github.com/neelance/astrewrite v0.0.0-20160511093645-99348263ae86/go.mod h1:kHJEU3ofeGjhHklVoIGuVj85JJwZ6kWPaJwCIxgnFmo=
+github.com/neelance/sourcemap v0.0.0-20151028013722-8c68805598ab h1:eFXv9Nu1lGbrNbj619aWwZfVF5HBrm9Plte8aNptuTI=
+github.com/neelance/sourcemap v0.0.0-20151028013722-8c68805598ab/go.mod h1:Qr6/a/Q4r9LP1IltGz7tA7iOK1WonHEYhu1HRBA7ZiM=
+github.com/shurcooL/httpfs v0.0.0-20171119174359-809beceb2371 h1:SWV2fHctRpRrp49VXJ6UZja7gU9QLHwRpIPBN89SKEo=
+github.com/shurcooL/httpfs v0.0.0-20171119174359-809beceb2371/go.mod h1:ZY1cvUeJuFPAdZ/B6v7RHavJWZn2YPVFQ1OSXhCGOkg=
+github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d h1:zE9ykElWQ6/NYmHa3jpm/yHnI4xSofP+UP6SpjHcSeM=
+github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
+github.com/smartystreets/goconvey v0.0.0-20180222194500-ef6db91d284a h1:JSvGDIbmil4Ui/dDdFBExb7/cmkNjyX5F97oglmvCDo=
+github.com/smartystreets/goconvey v0.0.0-20180222194500-ef6db91d284a/go.mod h1:XDJAKZRPZ1CvBcN2aX5YOUTYGHki24fSF0Iv48Ibg0s=
+github.com/spf13/cobra v0.0.3 h1:ZlrZ4XsMRm04Fr5pSFxBgfND2EBVa1nLpiy1stUsX/8=
+github.com/spf13/cobra v0.0.3/go.mod h1:1l0Ry5zgKvJasoi3XT1TypsSe7PqH0Sj9dhYf7v3XqQ=
+github.com/spf13/pflag v1.0.3 h1:zPAT6CGy6wXeQ7NtTnaTerfKOsV6V6F8agHXFiazDkg=
+github.com/spf13/pflag v1.0.3/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
+golang.org/x/crypto v0.0.0-20181015023909-0c41d7ab0a0e h1:IzypfodbhbnViNUO/MEh0FzCUooG97cIGfdggUrUSyU=
+golang.org/x/crypto v0.0.0-20181015023909-0c41d7ab0a0e/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
+golang.org/x/sys v0.0.0-20181011152604-fa43e7bc11ba h1:nZJIJPGow0Kf9bU9QTc1U6OXbs/7Hu4e+cNv+hxH+Zc=
+golang.org/x/sys v0.0.0-20181011152604-fa43e7bc11ba/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/text v0.0.0-20171214130843-f21a4dfb5e38 h1:yr7ItWHARpqySNZjEh5mPMHrw3xPR9tMnomFZVcO1mQ=
+golang.org/x/text v0.0.0-20171214130843-f21a4dfb5e38/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/tools v0.0.0-20181018182439-def26773749b h1:Czw8LyU+CIirm8yES+/9/oRAKhdsXjPGfVYfjjScfEM=
+golang.org/x/tools v0.0.0-20181018182439-def26773749b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+gopkg.in/DATA-DOG/go-sqlmock.v1 v1.3.0 h1:FVCohIoYO7IJoDDVpV2pdq7SgrMH6wHnuTyrdrxJNoY=
+gopkg.in/DATA-DOG/go-sqlmock.v1 v1.3.0/go.mod h1:OdE7CF6DbADk7lN8LIKRzRJTTZXIjtWgA5THM5lhBAw=
diff --git a/up.gif b/up.gif
new file mode 100644
index 0000000..493de39
--- /dev/null
+++ b/up.gif