diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 139 |
1 files changed, 88 insertions, 51 deletions
@@ -1,21 +1,62 @@ +[](https://travis-ci.org/samtay/so) +[](https://ci.appveyor.com/project/samtay/so/branch/master) + # so +A terminal interface for StackOverflow. + +**Note**: still working out some kinks. Initial release not published just yet. +**<Insert GIF here>** + +## example usage +While I like the acronym *so*, this tool would actually be better described as +*se*: an interface to the StackExchange network. In particular one thing that +differentiates it from [similar](https://github.com/santinic/how2) +[tools](https://github.com/gleitz/howdoi) is that you can simultaneously search +any number of sites in the StackExchange network: +```shell +# use default configured sites, e.g. [stackoverflow.com] +$ so how do i reverse a list in python + +# search for a latex solution +$ so --site tex how to put tilde over character + +# use google to search stackoverflow.com, askubuntu.com, and unix.stackexchange.com +$ so -e google -s askubuntu -s stackoverflow -s unix how do i install linux +``` + +## installation +The quickest installation method is to download the appropriate +binary from the [release artifacts](TODO link). Right now I'm only building the +most common targets, but in theory it should be easy to add more, so if you +don't see what you are looking for just open an issue and I can add it. Here's a +list of the [supported +targets](https://github.com/japaric/trust#supported-targets). You can quickly +install the binary for your OS with: +```shell +$ curl -LSfs https://samtay.github.io/so/install.sh | \ + sh -s -- --git samtay/so +``` -**Note:** under development, not ready for prime time. +#### cargo +``` +cargo install so +``` -# documentation +## documentation ### api keys -According to the [StackExchange -docs](https://api.stackexchange.com/docs/throttle), most users should be fine -without generating a personal API key (10k requests per IP per day). If you do -run into throttling issues, get a key -[here](https://stackapps.com/apps/oauth/register) and tell `so` to use it: +If you want to use your own [StackExchange API +Key](https://api.stackexchange.com/docs) you can set it via ``` so --set-api-key <KEY> ``` +You can also choose to use no key by editing your configuration to `api_key: ~`. +If for some reason my API key is globally throttled, you can hit the +StackExchange API with no key up to 300 times per day per IP, which I imagine is +fine for most users. ### multi-site searching -As stated in the docs linked above, +As stated in the [docs](https://api.stackexchange.com/docs/throttle), > If a single IP is making more than 30 requests a second, new requests will be dropped. @@ -23,49 +64,45 @@ So, don't go crazy with the multi-site search, since it is all done in parallel. In particular, if you specify more than 30 sites, SE will likely ban you for a short time. ### selecting a backend -Crossterm's level of support is awesome, but it comes at a price. On my machine, -the app kind of flashes between draws quite a bit. If you are on Mac, Linux, or -Redox, your best bet is to compile with default features which uses the -termion backend. If you are on windows, use crossterm, but know it will be -slightly jumpy. - -If the crossterm folks figure out a fix for [allowing ncurses to receive resize events](), -and you have ncurses installed on your system, then you should use the -ncurses backend, or the pancurses backend if you are on Windows. Just know that -currently if you choose this option, you won't be able to resize the terminal -window while the TUI is open. - -default = ["cursive/termion-backend"] -ncurses-backend = ["cursive/ncurses-backend"] -pancurses-backend = ["cursive/pancurses-backend"] -crossterm-backend = ["cursive/crossterm-backend"] - -# notes to self - -### async considerations -Implemented async with tokio in ec92f93, but unclear if this is necessary. For -< 10 simultaneous network requests, it might be better and simpler to just use -rayon (i.e. OS threads). - -### TUI considerations -Going with cursive because it is way more flexible than tui-rs. -**Important note** Tables are not currently allowed in stackexchange... so the -benefit of incorporating termimad features will not be felt. But, this is -changing [soon](https://meta.stackexchange.com/q/348746). - -### to stress test -Produces a long answer with noticeable pause on markdown view: +If you're installing from source, you can choose from a number of available +backend rendering engines. Note that the package `default` and `windows` feature +flags do not have an ncurses dependency, for the sake of simplicity. The +default backend is [termion](https://github.com/redox-os/termion), a bindless +library in pure Rust which seems to work quite well on Linux, MacOS, BSD, and +Redox. The windows backend is by default +[crossterm](https://github.com/crossterm-rs/crossterm), and while its level of +support is awesome, it does comes at a price in performance. On my machine, the +app kind of flashes between draws quite a bit. So if you are on Mac, Linux, or +Redox, your best bet is to compile with default features which uses the termion +backend. If you are on windows, use crossterm, but know it will be slightly +jumpy. + +If the crossterm folks figure out a fix for allowing ncurses to receive [resize +events](https://github.com/crossterm-rs/crossterm/issues/447), and you have +[ncurses installed](https://github.com/gyscos/cursive/wiki/Install-ncurses) on +your system, then the ncurses and pancurses backends will also work well. +Just know that *currently* if you choose this option, and you run the `--lucky` +prompt, you won't be able to resize the terminal window while the TUI is open. + +Available backends: +- `termion-backend` +- `ncurses-backend` +- `pancurses-backend` +- `crossterm-backend` + +E.g. to use `ncurses-backend`: ``` -cargo run -- --site stackoverflow --site serverfault how do I exit Vim +cargo install so --no-default-features --features ncurses-backend ``` -### to troubleshoot -``` -export RUST_BACKTRACE=full -cargo run -- how do I exit Vim > test.txt 2>&1 -``` - - - - -**Remove this** Recall my api key is: `8o9g7WcfwnwbB*Qp4VsGsw((` +See more information on this choice +[here](https://github.com/gyscos/cursive/wiki/Backends). + +## contributions +This was my first time writing Rust, and I wrote about it +[here](https://samtay.github.io/TODO) if you're into that sort of thing. +I just want to put out a **warning** that there is very likely some non-idiomatic +and straight up ugly code throughout this project, so don't come looking here +for a good Rust example! That being said, I would love to improve the codebase +so if you have any refactoring contributions feel free to send me a PR, but +please also accompany them with a short explanation. |