Repository files navigation

Useful examples at the command line.

eg provides examples of common uses of command line tools.

Man pages are great. How doesfind work, again?man find will tell you, butyou'll have to pore through all the flags and options just to figure out abasic usage. And what about usingtar? Even with the man pagestar isfamously inscrutable without the googling for examples.

No more!

eg will give you useful examples right at the command line. Think of it as acompanion tool forman.

eg comes fromexempli gratia, and is pronounced like the letters: "eegee".

pip install eg

brew install eg-examples

Clone the repo and create a symlink toeg_exec.py. Make sure the location youchoose for the symlink is on your path:

git clone https://github.com/srsudar/eg ./ln -s /absolute/path/to/eg-repo/eg_exec.py /usr/local/bin/eg

Note that the location ofeg_exec.py changed in version 0.1.x in order tosupport Python 3 as well as 2. Old symlinks will print a message explaining thechange, but you'll have to update your links to point at the new location. Oryou can install withpip orbrew.

eg doesn't ship with a binary. Dependencies are very modest and should notrequire you to install anything (other thanpytest ifyou want to run the tests). If you find otherwise, open an issue.

eg <program>

eg takes an argument that is the name of a program for which it containsexamples.

eg find will provide examples for thefind command.

eg --list will show all the commands for whicheg has examples.

The complete usage statement, as shown byeg --help, is:

eg [-h] [-v] [-f CONFIG_FILE] [-e EXAMPLES_DIR] [-c CUSTOM_DIR] [-p PAGER_CMD]   [-l] [--color] [-s] [--no-color] [program]

Files full of examples live inexamples/. A naming convention is followedsuch that the file is the name of the tool with.md. E.g. the examples forfind are infind.md.

eg find will pipe the contents offind.md throughless (although it triesto respect thePAGER environment variable).

eg works out of the box, no configuration required.

If you want to get fancy, however,eg can be fancy.

For example, maybe a team member always sends you bzipped tarballs and you cannever remember the flag for bzipping--why can't that guy just use gziplike everybody else? You can create an example for untarring and unzippingbzipped tarballs, stick it in a file calledtar.md, and telleg where tofind it.

The way to think about whateg does is that it takes a program name, forexamplefind, and looks for files namedfind.md in the default and customdirectories (including subdirectories). If it finds them, it pipes them throughless, with the custom files at the top. Easy.

The default and custom directories can be specified at the command line likeso:

eg --examples-dir='the/default/dir' --custom-dir='my/fancy/dir' find

Instead of doing this every time, you can define a configuration file. It mustbegin with a section calledeg-config and can contain two keys:custom-dirandexamples-dir. Here is an example of a valid config file:

[eg-config]examples-dir = ~/examples-dircustom-dir = ~/my/fancy/custom/dir

The config file is looked for first at${XDG_CONFIG_HOME}/eg/egrc and then at~/.egrc. You can also specify a different location at the command line likeso:

eg --config-file=myfile find

If you want to edit one of your custom examples, you can edit the file directlyor you can just use the-e or--edit flag.

To edit yourfind examples, for example, you could say:

eg -e find

This will dump you into an editor. The contents will be piped before the defaultexamples the next time you runeg find.

eg is highly customizable when it comes to output. You have three ways to tryand customize what is piped out the pager, applied in this order:

1. Color
2. Squeezing out excess blank lines
3. Regex-based substitutions

eg is colorful. The default colors were chosen to be pretty-ish while boringenough to not create problems for basic terminals. If you want to overridethese colors, you can do so in the egrc in acolor section.

Things that can be colored are:

• pound: pound sign before headings
• heading: the text of headings
• code: anything indented four spaces other than a leading$
• prompt: a$ that is indented four spaces
• backticks: anything between two backticks

Values passed to these options must be string literals. This allows escapecharacters to be inserted as needed. An egrc with heading text a nice burntorange might look like this:

[eg-config]custom-dir = ~/my/fancy/custom/dir[color]heading = '\x1b[38;5;172m'

To remove color altogether, for example if the color formatting is messing upyour output somehow, you can either pass the--no-color flag toeg, or youcan add an option to your egrc under theeg-config section like so:

[eg-config]color = false

The example files use a lot of blank lines to try and be readable at a glance.Not everyone likes this many blank lines. If you hate all duplicate lines, youcan use your favorite pager to remove all duplicate commands, like:

eg --pager-cmd 'less -sR' find

This will useless -sR to page, which will format color correctly (-R) andremove all duplicate blank lines (-s).

eg also provides its own custom squeezed output format, removing all blanklines within a single example and only putting duplicate blank lines betweensections. This can be configured at the command line with--squeeze or inthe egrc with thesqueeze option, like:

[eg-config]squeeze = true

Runningeg --squeeze find removes excess newlines like so:

Additional changes to the output can be accomplished with regular expressionsand the egrc. Patterns and replacements are applied using Python'sre module,so look to thedocumentation forspecifics. Substitutions should be specified in the egrc as a list with thesyntax:[pattern, replacement, compile_as_multiline]. Ifcompile_as_multiline is absent orFalse, the pattern will not be compiledas multiline, which affects the syntax expected byre. There.sub method iscalled with the compiled pattern andreplacement.

Substitutions must be named and must be in the[substitutions] section of theegrc. For example, this would remove all the four-space indents beginninglines:

[substitutions]remove-indents = ['^    ', '', True]

This powerful feature can be used to perform complex transformations, includingsupport additional coloring of output beyond what is supported natively byeg. If you wish there was an option to remove or add blank lines, colorsomething new, remove section symbols, etc, this is a good place to start.

If multiple substitutions are present, they are sorted by alphabetically byname before being applied.

By default,eg pages usingless -RMFXK. The-R switch tellsless tointerpret ANSI escape sequences like color rather than showing them raw.-Mtells it to show line number information in the bottom of the screen.-F toautomatically quit if the entire example fits on the screen.-X tells it notto clear the screen. Finally,-K makesless exit in response toCtrl-C.

You can specify a different pager using the--pager-cmd option at the commandline or thepager-cmd option in the egrc. If specified in the egrc, the valuemust be a string literal. For example, this egrc would usecat to page:

[eg-config]pager-cmd = 'cat'

pydoc.pager() does a lot of friendly error checking, so it might still beuseful in some situations. If you want to usepydoc.pager() to page, you canpass thepydoc.pager as thepager-cmd.

Example documents are written inmarkdown.Documents in markdown are easily read at the command line as well as online.They all follow the same basic format.

This section explains the format so that you better understand how to quicklygrok the examples.

Contributors should also pay close attention to these guidelines to keepexamples consistent.

Anything indented four spaces or surrounded by backticks `like this` aremeant to be input or output at the command line. A single line indented fourspaces is a user-entered command. If a block is indented four spaces, only thelines beginning with$ are user-entered--anything else is output.

The first section heading should be simply the name of the tool. It should befollowed by the most rudimentary examples. Users that are familiar with thecommand but just forget the precise syntax should be able to see what they needwithout scrolling. Example commands should be as real-world as possible, withfile names and arguments as illustrative as possible. Examples for thecpcommand, for instance, might be:

cp original.txt copy.txt

Here the.txt extensions indicate that these are file names, while the namesthemselves make clear which is the already existing file and which will be thenewly created copy.

This section shouldn't show output and should not include the$ to indicatethat we are at the command line.

This section should be a quick glance for users that know what the tool does,know a basic usage is what they are trying to do, and are just looking for areminder.

Next a Basic Usage section explains the most basic usage without using realfile names. This section gives users that might not know the usual syntax amore abstract example than the first section. It is intended to provide a moreuseful explanation than the first entry in the man page, which typically showsall possible flags and arguments in a way that is not immediately obvious tonew users of the command. The SYNOPSIS section of the man page forcp, forexample, shows:

cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file ... target_directory

The Basic Usage is intended to provide less verbose, more immediatelypractical versions of the man page's SYNOPSIS section.

Commands and flags that will affect the behavior are shown as would be enteredin the command line, while user-entered filenames and arguments that do notalter the command's behaviors are shown in< >. Examples in the Basic Usagesection for thecp command, for instance, might be:

cp -R <original_directory> <copied_directory>

In this command thecp -R indicate the command and behavior and thus are notgiven in< >. Case-dependent components of the command, in this case thedirectory to be copied and the name of the copy, are surrounded with< >.Each is wrapped in separate< > to make clear that it is in fact twodistinct arguments.

Subsequent subsections can be added for common uses of the tools, asappropriate.

Although markdown is readable, it can still be tricky without syntaxhighlighting. We use spacing to help the eye.

1. All code snippets are followed by at two blank lines, unless overruled by 2.

2. Each line beginning a section (i.e. the first character on the line is#)should be preceded by exactly three lines.

3. Files should end with two blank lines.

4. Lines should not exceed 80 characters, unless to accommodate a necessarilylong command or long output.

Additions of new tools and new or more useful examples are welcome.eg shouldbe something that people want to have on their machines. If it has a man page,it should be included ineg.

Please read the Format of Examples section and review existing example files toget a feel for howeg pages should be structured.

If you find yourself turning to the internet for the same command again andagain, consider adding it to the examples.

eg examples do not intend to replace man pages!man is useful in its ownright.eg should provide quick examples in practice. Do not list all theflags for the sake of listing them. Assume that users will havemanavailable.

eg depends only on standard libraries and Python 2.x/3.x, so building shouldbe a simple matter of cloning the repo and running the executableeg/eg.py.

eg uses pytest for testing, so you'll have to have it installed to run tests.Once you have it, runpy.test fromthe root directory of the repo.

Tests should always be expected to pass. If they fail, please open an issue,even if only so that we can better elucidateeg's dependencies.

Aliaseg towoman for something that is likeman but a little morepractical:

$alias woman=eg$ man find$ woman find