eg

Useful examples at the command line.

Overview

eg provides examples of common uses of command line tools.

Man pages are great. How does find work, again? man find will tell you, but you'll have to pore through all the flags and options just to figure out a basic usage. And what about using tar? Even with the man pages tar is famously inscrutable without the googling for examples.

No more!

eg will give you useful examples right at the command line. Think of it as a companion tool for man.

eg comes from exempli gratia, and is pronounced like the letters: "ee gee".

Installation

With pip

pip install eg

With brew

brew install eg-examples

Run from source

Clone the repo and create a symlink to eg_exec.py. Make sure the location you choose 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 of eg_exec.py changed in version 0.1.x in order to support Python 3 as well as 2. Old symlinks will print a message explaining the change, but you'll have to update your links to point at the new location. Or you can install with pip or brew.

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

Usage

eg <program>

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

eg find will provide examples for the find command.

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

The complete usage statement, as shown by eg --help, is:

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

How it Works

Files full of examples live in examples/. A naming convention is followed such that the file is the name of the tool with .md. E.g. the examples for find are in find.md.

eg find will pipe the contents of find.md through less (although it tries to respect the PAGER environment variable).

Configuration and Extension

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 can never remember the flag for bzipping--why can't that guy just use gzip like everybody else? You can create an example for untarring and unzipping bzipped tarballs, stick it in a file called tar.md, and tell eg where to find it.

The way to think about what eg does is that it takes a program name, for example find, and looks for files named find.md in the default and custom directories (including subdirectories). If it finds them, it pipes them through less, with the custom files at the top. Easy.

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

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 must begin with a section called eg-config and can contain two keys: custom-dir and examples-dir. Here is an example of a valid config file:

[eg-config]
examples-dir = ~/examples-dir
custom-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 like so:

eg --config-file=myfile find

Editing Your Custom Examples

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

To edit your find examples, for example, you could say:

eg -e find

This will dump you into an editor. The contents will be piped before the default examples the next time you run eg find.

Formatting Output

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

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

Color

eg is colorful. The default colors were chosen to be pretty-ish while boring enough to not create problems for basic terminals. If you want to override these colors, you can do so in the egrc in a color 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 escape characters to be inserted as needed. An egrc with heading text a nice burnt orange 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 up your output somehow, you can either pass the --no-color flag to eg, or you can add an option to your egrc under the eg-config section like so:

[eg-config]
color = false

Squeezing Blank Lines

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, you can use your favorite pager to remove all duplicate commands, like:

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

This will use less -sR to page, which will format color correctly (-R) and remove all duplicate blank lines (-s).

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

[eg-config]
squeeze = true

Running eg --squeeze find removes excess newlines like so:

Regex Substitutions

Additional changes to the output can be accomplished with regular expressions and the egrc. Patterns and replacements are applied using Python's re module, so look to the documentation for specifics. Substitutions should be specified in the egrc as a list with the syntax: [pattern, replacement, compile_as_multiline]. If compile_as_multiline is absent or False, the pattern will not be compiled as multiline, which affects the syntax expected by re. The re.sub method is called with the compiled pattern and replacement.

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

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

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

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

Paging

By default, eg pages using less -RMFXK. The -R switch tells less to interpret ANSI escape sequences like color rather than showing them raw. -M tells it to show line number information in the bottom of the screen. -F to automatically quit if the entire example fits on the screen. -X tells it not to clear the screen. Finally, -K makes less exit in response to Ctrl-C.

You can specify a different pager using the --pager-cmd option at the command line or the pager-cmd option in the egrc. If specified in the egrc, the value must be a string literal. For example, this egrc would use cat to page:

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

pydoc.pager() does a lot of friendly error checking, so it might still be useful in some situations. If you want to use pydoc.pager() to page, you can pass the pydoc.pager as the pager-cmd.

Format and Content of Examples

Example documents are written in markdown. 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 quickly grok the examples.

Contributors should also pay close attention to these guidelines to keep examples consistent.

Overview

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

Name of the Command

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

cp original.txt copy.txt

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

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

**This section should be a quick glance for users that k