From e634a6fa69bce8264bc7d178cda33a212c3cb3ce Mon Sep 17 00:00:00 2001 From: Igor Chubin Date: Sun, 10 Jun 2018 15:05:45 +0000 Subject: [PATCH] major update of README.md (not yet finished) --- README.md | 490 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 351 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index 50714ed..042ca8b 100644 --- a/README.md +++ b/README.md @@ -3,74 +3,321 @@ Unified access to the best community driven cheat sheets repositories of the world. +Let's imagine for a moment that we have an ideal cheat sheet. +How such a thing shold look like? +What features should it have? + +* *concise* — it should be concise; it should contain only things you need and nothing else; +* *fast* — it should be possible to use it instantly; +* *comprehensive* — it should contain answers for every question you could have; +* *universal* — it should be available everywhere without any preparations; +* *unobtrusive* — it does not distract you when you are using it, it does not want anything from you; +* *tutoring* — it helps you to learn the subject; +* *inconspicuous* — it should be possible to use it completely unnoticed. + +It's *cheat.sh*. ## Features -* simple curl/browser interface -* available everywhere, no installation needed -* selected popular well maintained community driven cheat sheets repositories -* search (on a cheat sheet and in all cheat sheets) -* tab completion -* syntax highlighting -* editors integration +cheat.sh + +* has simple curl/browser interface; +* covers 55 programming languages, and several DBMSes, and more than 1000 most important UNIX/Linux commands; +* available everywhere, no installation needed; +* ultrafast, it returns the answer, as a rule, within 100 ms; +* can be used directly from the editor, without losing the context; +* has a convenient command line client, very advantageous and helpful, though not mandatory; +* supports special mode (stealth mode), where it can be used fully invisibly, not even touching a key and not making a sound. ## Usage -To read a cheat sheet: +To read a cheat sheet for a UNIX/Linux command, use the name of the command as the query: ``` - curl cheat.sh/sudo -``` - -Here `sudo` is the name of the cheat sheet you are looking for. - -If you don't know the name of the topic you need, -you can search for it using the ~KEYWORD notation. -For example, to see how you can make snapshots, you make the following query + curl cheat.sh/tar + curl cht.sh/curl + curl https://cheat.sh/rsync + curl https://cht.sh/tr -``` - ~snapshot ``` -and get the list of snapshot creation examples commands. +You can use both HTTPS and HTTP to access the service, and both the long (cheat.sh) and the short service names (cht.sh). -Programming languages cheat sheets are located in correspondent namespaces, -named after the name of the language: +Here `tar`, `curl`, `rsync`, and `tr` are the names of the UNIX/Linux commands, you want to get cheat sheets for. + +If you don't know the name of the command you need, +you can search for it using the `~KEYWORD` notation. + +For example, to see how you can make snapshots of a filesystem/volume/something else (and let's imagine you don't know using +what command you could do it), you use `~snapshot` (note the `~`) as the query: ``` - scala/Functions + curl cht.sh/~snapshot ``` -Read more about the programming languages cheat sheets below. - -There are several special pages (their name are always starting with a colon), -that are not cheat sheets and have special meaning. For example: +Programming languages cheat sheets are located not directly in the root namespace, +but in special namespaces, dedicated for them: ``` - :help - :list list all cheat sheets - /perl/:list list all perl cheat sheets + curl cht.sh/go/Pointers + curl cht.sh/scala/Functions + curl cht.sh/python/lambda ``` -cheat.sh supports tab completion in a shell and in a browser. -All major shells are supported. Read more on it in the *Tab completion* section. - -cheat.sh uses syntax highlighting by default. -You can switch it off, or choose other color scheme for it. -Use URL options for that. More on it in the *Options* section below. - - -Usage examples: +To get the list of available programming language cheat sheets, do a special query `:list`: ``` - $ curl cheat.sh/cpio - $ curl cheat.sh/~snapshot - $ curl cheat.sh/go/range - $ curl cheat.sh/rust/hello - $ curl cheat.sh/rust/hello?T + curl cht.sh/go/:list ``` -![cheat.sh usage](http://igor.chub.in/download/cheatsh-en.gif) +(almost) each programming language has a special page, named `:learn`, +that describes the langauge basics (and that's direct mappng from a beauriful project "Learn X in Y"), +and that could be good starting point, if you are only beginning to learn the language. + +What is much more important, and what makes *cheat.sh* really useful, +is that if there is no cheat sheet for some programming language query +(and it is almost always the case, for there are by far more devirse queries than all possible cheat sheets), +it is generated on the fly, using available information in the related connected documentation repositories and +answers on StackOverflow. Of course, there is no guarantee that the returned +cheat sheet will be a 100% hit, but it almost always exactly what you are looking for. + +Just try these and your own various queries to get the impression of that, how the answers look like: +``` + curl cht.sh/go/reverse+a+list + curl cht.sh/python/random+list+elements + curl cht.sh/js/parse+json + curl cht.sh/lua/merge+tables + curl cht.sh/clojure/variadic+function +``` + +If you don't need text comments in the answer, you can eliminate them +with a special option `?Q`, and if you don't need syntax highlighting, switch it of using `?T`. +You can combine the options: + +``` + curl cht.sh/go/reverse+a+list?Q + curl cht.sh/python/random+list+elements?Q + curl cht.sh/js/parse+json?Q + curl cht.sh/lua/merge+tables?QT + curl cht.sh/clojure/variadic+function?QT +``` + +Try to ask your own queries. Try to follow these rules when making your queries: + +1. Try to be more specific (`/python/append+file` is better than `/python/file` and `/python/append`); +2. Ask practical question if possible (yet theoretical question are possible too); +3. Ask programming language questions only; specify the name of the programming language as the section name; +4. Separate words with `+` instead of spaces; +5. Do not use special characters, they are ignored anyway. + +Read more about the programming languages queries below. + +## Command line client, cht.sh + +The cheat.sh service has its own command line client (cht.sh), that has several useful features, +comparing to quering the service directly with curl: + +* Special shell mode with a persistent queries context and readline support; +* Queries history; +* Clipboard integration; +* Tab completion support for shells (bash, fish, zsh); +* Stealth mode. + +To install the client: + +``` + curl https://cht.sh/:cht.sh > ~/bin/cht.sh + chmod +x ~/bin/cht.sh +``` + +Now, you can use `cht.sh` instead of curl, and write queries in more natural way, +with spaces instead of `+`: + +``` + cht.sh go reverse a list + cht.sh python random list elements + cht.sh js parse json +``` + +It is even more convenient to start the client in a special shell mode: + +``` + $ cht.sh --shell + cht.sh> go reverse a list +``` + +If all queries are supposed to be about the same language, you can change the context of the queries +and spare repeating the programming language name: +``` + $ cht.sh --shell + cht.sh> cd go + cht.sh/go> reverse a list +``` +or even start in this context: +``` + $ cht.sh --shell go + cht.sh/go> reverse a list + ... + cht.sh/go> join a list + ... +``` + +If you want to change the context, you can do it with the `cd` command, +or you can temporary change the context only for one query + +``` + cht.sh --shell go + cht.sh/go> /python dictionary comprehension + ... +``` + +If you want to copy the last answer in the clipboard, you can +use the `c` (`copy`) command, or `C` (`ccopy`, without comments). + +Type `help` to list other internal cht.sh commands. + +### Tab completion + +To activate tab completion support for `cht.sh`, add the `:bash_completion` script to your `~/.bashrc`: + +``` + $ curl https://cheat.sh/:bash_completion > ~/.bash.d/cht.sh + $ . ~/.bash.d/cht.sh + $ # and add . ~/.bash.d/cht.sh to ~/.bashrc +``` + +### Stealth mode + +One of the important properties of any real cheat sheet, +is that it could be used fully unnoticed. + +cheat.sh can be used completely unnoticed too. The cheat.sh client, cht.sh, has +a special mode, called *stealth mode*, where you don't need even to touch your +keyboard to open some cheat sheet. + +In this mode, as soon as you select some text with the mouse (and it is added +into the selection buffer of X Window System or into the clipboard) it's used +as a query string for cheat.sh, and correspondent cheat sheets are shown. + +Let's imagine, that you are having an online interview with a shared documents +(say Google Docs), where the interviewer ask you some questions (or where you +typing them in on your own, just to show to the interviewer that you've heard +it right). + +To see the cheat sheets for the questions, you just have to select them, +and do nothing more. If you don't want to see the comments and the only thing you need is code, +use `?Q` when going into the stealth mode. + +``` +She: Hi! | $ cht.sh --shell python +You: Hi! | cht.sh/python> stealth Q +She: Are you ready for a small interview? | stealth: you are in the stealth mode; select any text in any window for a query +She: Just a couple of questions about python | stealth: selections longer than 5 words are ignored +She: We will talk about python | stealth: query arguments: ?Q +She: Let's start from something simple. | stealth: use ^C to leave this mode +She: Do you known how to reverse a list in python? | +You: Sure | +You: (selecting "reverse a list") | stealth: reverse a list + | reverse_lst = lst[::-1] +You: lst[::-1]? | +She: Good. | +She: Do you know how to chain a list of lists? | +You: (selecting "chain a list of lists") | stealth: chain a list of lists + | import itertools + | a = [["a","b"], ["c"]] + | print list(itertools.chain.from_iterable(a)) +You: May I use external modules? | +She: What module do you want to use? | +You: itertools | +She: Yes, you may use it | +You: Ok, then: | +You: itertools.chain.from_iterable(a) | +She: Good. Let's try something harder. | +She: What about quicksort implementation? | +You: (selecting "quicksort implementation") | stealth: quicksort implementation +You: Let's me think about it. | (some big and clumsy lowlevel implementation is shown) +You: Well...(starting typing it in) | def sort(array=[12,4,5,6,7,3,1,15]): + | less = [] + | equal = [] +She: (seeing your ugly pascal style) | greater = [] +She: Could you write it more concise? | if len(array) > 1: + | pivot = array[0] +You: What do you mean? | for x in array: + | if x < pivot: less.append(x) +She: I mean, | if x == pivot: equal.append(x) +She: do you really need all these ifs and fors? | if x > pivot: greater.append(x) +She: Could you just use filter instead may be? | return sort(less)+equal+sort(greater) + | else: +You: quicksort with filter? | return array + | +She: Yes | stealth: quicksort filter +You: (selecting "quicksort with filter") | return qsort(filter(lt, L[1:]))+[pivot]+qsort(filter(ge, L[1:])) +You: Ok, I will try. | +You: Something like that? | +You: qsort(filter(lt, L[1:]))+[pivot]+qsort(filter(ge, L[1:]))| + | +She: Yes! Perfect! Exactly what I wanted to see! | + +``` + +Or course, it is just fun, and you should never cheat in your coding interviews, +because you know what happens otherwise. + +![when you lie in your interview](http://cheat.sh/files/when-you-lie.png) + +## Editors integration + +### Vim + +* [cheat.sh-vim](https://github.com/dbeniamine/cheat.sh-vim) — Vim support + +[![asciicast](https://asciinema.org/a/c6QRIhus7np2OOQzmQ2RNXzRZ.png)](https://asciinema.org/a/c6QRIhus7np2OOQzmQ2RNXzRZ) + +### Emacs + +* [cheat-sh.el](https://github.com/davep/cheat-sh.el) — Emacs support (available also at cheat.sh/:emacs) +* cheat.sh/:emacs-ivy — Emacs support for ivy users + +[![asciicast](https://asciinema.org/a/3xvqwrsu9g4taj5w526sb2t35.png)](https://asciinema.org/a/3xvqwrsu9g4taj5w526sb2t35) + +## Special pages + +There are several special pages (their nameis are always starting with a colon), +that are not cheat sheets and have special meaning. + + +Getting started: + +``` + :help description of all special pages and options + :intro cheat.sh introduction, covering the most important usage questions + :list list all cheat sheets (can be used in a subsection too: /go/:list) +``` + +Command line client `cht.sh` and shells support: +``` + :cht.sh code of the cht.sh client + :bash_completion bash function for tab completion + :bash bash function and tab completion setup + :fish fish function and tab completion setup + :zsh zsh function and tab completion setup +``` + +Editors support: + +``` + :vim cheat.sh support for Vim + :emacs cheat.sh function for Emacs + :emacs-ivy cheat.sh function for Emacs (uses ivy) +``` + +Other pages: + +``` + :post how to post new cheat sheet + :styles list of color styles + :styles-demo show color styles usage examples +``` ## Search @@ -108,80 +355,6 @@ List of search options: r recursive search ``` -## Special pages - -Special pages: - -``` - :help this page - :list list all cheat sheets - :post how to post new cheat sheet - :bash_completion bash function for tab completion - :bash bash function and tab completion setup - :fish fish function and tab completion setup - :zsh zsh function and tab completion setup - :emacs cheat.sh function for Emacs - :emacs-ivy cheat.sh function for Emacs (uses ivy) - :styles list of color styles - :styles-demo show color styles usage examples -``` - -## Tab completion - -Tab completion is a very important part of cheat.sh. -Having more than a thousand cheat sheets, it's very hard to learn all their names. - -If you want to use the `cheat.sh` shell functions, it's enough to include `:bash` (`:zsh` or `:fish`) -in `~/.bashrc`: - -``` - $ curl cheat.sh/:bash > ~/.bash.d/cheat.sh - $ . ~/.bash.d/cheat.sh - $ # add . ~/.bash.d/cheat.sh to ~/.bashrc -``` - -If you want to use cheat.sh with curl -and don't create any special functions, include `:bash_completion`: - -``` - $ curl cheat.sh/:bash_completion > ~/.bash.d/cheat.sh - $ . ~/.bash.d/cheat.sh - $ # add . ~/.bash.d/cheat.sh to ~/.bashrc -``` - -## Editors integration - -### Emacs - -* [cheat-sh.el](https://github.com/davep/cheat-sh.el) — Emacs support (available also at cheat.sh/:emacs) -* cheat.sh/:emacs-ivy — Emacs support for ivy users - -[![asciicast](https://asciinema.org/a/3xvqwrsu9g4taj5w526sb2t35.png)](https://asciinema.org/a/3xvqwrsu9g4taj5w526sb2t35) - -### Vim - -* [cheat.sh-vim](https://github.com/dbeniamine/cheat.sh-vim) — Vim support - -[![asciicast](https://asciinema.org/a/c6QRIhus7np2OOQzmQ2RNXzRZ.png)](https://asciinema.org/a/c6QRIhus7np2OOQzmQ2RNXzRZ) - -## Options - - ?OPTIONS - -``` - q quiet mode, don't show github/twitter buttons - T text only, no ANSI sequences (can be pasted in an editor) - style=STYLE color style -``` - -Options can be combined together in this way: - -``` - $ curl cheat.sh/for?qT\&style=bw -``` - -(note the `\` before `&`: it is escaping `&`, which has in shell special meaning). - ## Programming languages cheat sheets Cheat sheets related to programming languages @@ -212,26 +385,65 @@ Some languages has the one-liners-cheat sheet, `1line`: ![cheat.sh usage](http://cheat.sh/files/supported-languages-c++.png) -At the moment, cheat.sh covers the 15 following programming languages (alphabetically sorted): +At the moment, cheat.sh covers the 55 following programming languages (alphabetically sorted): -|Prefix |Language |Basics|One-liners|Weirdness| -|-----------|----------|------|----------|---------| -|`c++/` |C++ |✓ | | | -|`clojure/` |Clojure |✓ | | | -|`elixir/` |Elixir |✓ | | | -|`elm/` |Elm |✓ | | | -|`erlang/` |Erlang |✓ | | | -|`go/` |Go |✓ | | | -|`haskell/` |Haskell |✓ | | | -|`js/` |JavaScript|✓ |✓ |✓ | -|`julia/` |Julia |✓ | | | -|`lua/` |Lua |✓ | | | -|`ocaml/` |OCaml |✓ | | | -|`perl/` |Perl |✓ |✓ | | -|`php/` |PHP |✓ | | | -|`python/` |Python |✓ | | | -|`rust/` |Rust |✓ | | | -|`scala/` |Scala |✓ | | | +|Prefix |Language |Basics|One-liners|Weirdness|StackOverflow| +|-----------|----------|------|----------|---------|-------------| +|`arduino/` |Arduino | | | |✓ | +|`assembly/`|Assembly | | | |✓ | +|`awk/` |AWK |✓ | | |✓ | +|`bash/` |Bash |✓ | | |✓ | +|`basic/` |BASIC | | | |✓ | +|`bf/` |Brainfuck |✓ | | |✓ | +|`c/` |C |✓ | | |✓ | +|`chapel/` |Chapel |✓ | | |✓ | +|`clean/` |Clean | | | |✓ | +|`clojure/` |Clojure |✓ | | |✓ | +|`coffee/` |CoffeeScript|✓ | | |✓ | +|`cpp/` |C++ |✓ | | |✓ | +|`csharp/` |C# |✓ | | |✓ | +|`d/` |D |✓ | | |✓ | +|`dart/` |Dart |✓ | | |✓ | +|`delphi/` |Dephi | | | |✓ | +|`dylan/` |Dylan |✓ | | |✓ | +|`eiffel/` |Eiffel | | | |✓ | +|`elixir/` |Elixir |✓ | | |✓ | +|`elisp/` |ELisp |✓ | | |✓ | +|`elm/` |Elm |✓ | | |✓ | +|`erlang/` |Erlang |✓ | | |✓ | +|`factor/` |Factor |✓ | | |✓ | +|`fortran/` |Fortran |✓ | | |✓ | +|`forth/` |Forth |✓ | | |✓ | +|`fsharp/` |F# |✓ | | |✓ | +|`go/` |Go |✓ | | |✓ | +|`groovy/` |Groovy |✓ | | |✓ | +|`haskell/` |Haskell |✓ | | |✓ | +|`java/` |Java |✓ | | |✓ | +|`js/` |JavaScript|✓ |✓ |✓ |✓ | +|`julia/` |Julia |✓ | | |✓ | +|`kotlin/` |Kotlin |✓ | | |✓ | +|`lisp/` |Lisp |✓ | | |✓ | +|`lua/` |Lua |✓ | | |✓ | +|`matlab/` |MATLAB |✓ | | |✓ | +|`ocaml/` |OCaml |✓ | | |✓ | +|`perl/` |Perl |✓ |✓ | |✓ | +|`perl6/` |Perl 6 |✓ |✓ | |✓ | +|`php/` |PHP |✓ | | |✓ | +|`pike/` |Pike | | | |✓ | +|`python/` |Python |✓ | | |✓ | +|`python3/` |Python 3 |✓ | | |✓ | +|`r/` |R |✓ | | |✓ | +|`racket/` |Racket |✓ | | |✓ | +|`ruby/` |Ruby |✓ | | |✓ | +|`rust/` |Rust |✓ | | |✓ | +|`scala/` |Scala |✓ | | |✓ | +|`scheme/` |Scheme |✓ | | |✓ | +|`swift/` |Swift |✓ | | |✓ | +|`tcsh/` |Tcsh |✓ | | |✓ | +|`tcl/` |Tcl |✓ | | |✓ | +|`objective-c/`|Objective-C|✓ | | |✓ | +|`vb/` |VisualBasic|✓ | | |✓ | +|`vbnet/` |VB.Net |✓ | | |✓ | ## Cheat sheets sources @@ -253,12 +465,13 @@ of cheat sheets |Programming languages |[adambard/learnxinyminutes-docs](https://github.com/adambard/learnxinyminutes-docs)|999/4513|Jun 23, 2013| |Go |[a8m/go-lang-cheat-sheet](https://github.com/a8m/go-lang-cheat-sheet)|23/2086|Feb 9, 2014| |Perl |[pkrumnis/perl1line.txt](https://github.com/pkrumins/perl1line.txt)|4/151|Nov 4, 2011| +|Programming languages |[StackOverflow](https://stackoverflow.com)| | | Pie diagram reflecting cheat sheets sources distribution (by number of cheat sheets on cheat.sh originating from a repository): ![cheat.sh cheat sheets repositories](http://cheat.sh/files/stat-2017-06-05.png) -## How to conribute +## How to contribute ### How to edit a cheat sheet @@ -296,4 +509,3 @@ If you want to add a cheat sheet repository to cheat.sh, please open an issue: * [Add a new repository](https://github.com/chubin/cheat.sh/issues/new) Please specify the name of the repository, and give its short description. -