wdsize - purposelessness
------------------------


INTRODUCTION
------------
Rewrite in C of an example found in the BashPrompt-Howto, meant for
anyone who could want a fancy, coloured number in their terminal prompt,
representing the size of the files in the current directory.


INSTALLING
----------
There are no dependencies besides the standard C library, some POSIX
poison like pthreads and, of course, a C compiler. You can just 'make'
and 'make install'.


USING
-----

* bash:

PS1="\[${WDCOLOR}\]${WDOUT}\[\033[0m\] \W \$"
PROMPT_COMMAND='eval $(wdsize)'

* zsh

precmd()
{
	eval $(wdsize)
	PS1="%{${WDCOLOR}%}${WDOUT}%{$(echo '\e[0m')%} %2c %# "
}

* tcsh

alias precmd 'eval `wdsize -t`; set prompt="%{$WDCOLOR%}$WDOUT%{\e[0m%} %c %# "'

wdsize can be configured at runtime through the environment variables listed
below (default values within parentheses) [dirconf property within brackets]:

- WDCONF_COUNT [count] (true): file counting;

- WDCONF_COLOR [color] (auto): Pre-defined strings are: black, red,
  magenta, yellow, cyan, blue, white and green for colors; bright, dim,
  italic, underscore, blink, reverse and hidden for attributes. The
  syntax is "attribute1, attribute2... attributen; fg, bg"; attributes
  are optional, but either the foreground or the background color
  must be set.

  Color schemes are special combinations of colors and attributes that can be
  defined by "schemename=attributes;fg,bg", and saved with 'wdsize -m'
  afterwards. Examples of schemes can be found in wdsize.colors; schemes
  (with previews) can be listed with 'wdsize -l', and deleted with 'wdsize -d'.
  Use -i to have a prompt before removal.

- WDCONF_ACTIVE [active] (true): turn wdsize off;

- WDSIZE_BLOCK_SIZE [blocksize] (human-readable): block size for wdsize,
  a la GNU. If unset, BLOCK_SIZE or BLOCKSIZE are read, if defined.

- WDCONF_OFFWHENINT [offwhenint] (recursive-only): long operations can get you
  stuck with a 'wdsize is working' message; hitting ENTER or pressing
  Control+D, as advised, will stop wdsize, but will not disable it
  afterwards. This setting controls when (always, never, recursive-only,
  local-only) wdsize will shut itself down after being interrupted.

- WDCONF_EXCLUDE_PATHS [exclude_paths] 
  (^(/dev|/sys|/proc) on Linux; ^(/dev|/proc) on other platforms):
  regex pattern to exclude directories from being processed. If empty,
  no directories are excluded; if unset, the default pattern is used.

- WDCONF_STRING_IGNORED [string_ignored] ((void *)0);
  WDCONF_STRING_INACTIVE [string_inactive] ((void *)0): strings to
  display when a path is ignored or inactive.
  
- WDCONF_RECURSIVE [recursive] (false): recursive mode;

- WDCONF_XDEV [xdev] (false): cross-filesystem option.


DIRCONF
-------
A dirconf rule is comprised of settings for a specific directory.
Directories without an entry in ~/.wdsize/wdsize.conf will keep using
the global settings from the dot rule ([.]) and from the environment.
wdsize.conf is an INI-style file in which the section is the dirpath,
and the property/value pairs below it are the actual configuration.
A section with a semicolon right after the opening bracket will be
parsed as regex; otherwise it is parsed as a glob(7) pattern
(multiple patterns, separated by commas, can be specified).

  
DIRCONF: AN EXHAUSTIVE LIST OF PROPERTIES AND THEIR SCOPE
---------------------------------------------------------
(As found in wdsize.c)

PROPERTY           SCOPE
count              any
color              any
tcsh               global (dot rule only)
block_size         any
active             any
offwhenint         any
exclude_paths      global
string_ignored     local (dirconf rule only)
string_inactive    local
recursive          any
xdev               any


SAVING YOUR SETTINGS
--------------------
* globally, from the environment:
    wdsize -e

* for one or more dirs, from the command line:
    wdsize -D<option1> [-D<option2>] ... <dirpath1> [dirpath2] ...
    (will create a new rule for the specified dirs in wdsize.conf)
  
  Unless you use the -a (append) option, existing rules and their
  settings are replaced with whatever is given in the command line.
  Thus, if you intend to add 'du' to a rule called /usr/bin, you'd use
     
     wdsize -Ddu=1 -a /usr/bin
     
  If you want to create a rule for various paths, you must include
  the comma and everything between quotes:
   
     wdsize -Dcolor=gay "/lib/systemd, /usr/share/emacs"
     
  A "merge rules" option may appear in the future, but don't count
  on that.


APOTHEOSIS
----------
The setup above should give you something similar to this:

514.45MiB, 2,873 /usr/bin $

Full stats:

<2,601f 272l 31h> 514.45MiB, 2,873 /usr/bin $

If a file error prevents wdsize from doing the calculation, an [ERR]
message is displayed:

ERR ~/ceilingcatiswatchingyoumasturbate #


OTHER UNIXEN
------------
- Works like a charm on FreeBSD. Other BSDs may work; try make -f
  BSDmakefile and see if you can build wdsize unmodified.

- Solaris (and forks like Illumos), Mac OS X, <some obscure UNIX>: not
  tested, but it might work.


KNOWN ISSUES
------------
A non-login shell started interactively (either with su or manually)
will inherit the current environment variables; wdsize won't re-read its
settings from the configuration files. To work around this, add an
'unset WDSIZE_EXPORTCFG' line to your .bashrc or .zshrc, or the
equivalent unsetenv to .tcshrc.


LICENSE
-------
wdsize is released under the MIT/X11 license. Refer to the LICENSE file for
the full text.

