##################################################################################################
INSTALLATION

This program is intended to be used by root
Simply copy the cleanpkgfile script to someplace in the root's PATH
and make sure it's executable:
  chmod +x cleanpkfile
  cp cleanpkgfile /usr/sbin

The _cleanpkgfile contains zsh-completion function - you can place it anywhere in your $fpath
(globally, it would be /usr/share/zsh/site-functions)

It needs perl > v5 and File::Temp, File::Find::Rule, and Term::ANSIColor.

##################################################################################################
CONFIGURATION

You can write a configuration file (there should be a sample one included with the program)
and place it in one of three locations (listed in order of precedence):
  ~/.config/cleanpkgfile/cleanpkgfile.conf
  ~/.cleanpkgfile.conf
  /etc/cleanpkgfile.conf

Inside, you can set default values for all supported command-line options in the form of:
  <long option name> = <value>
where value can be 1, true, 0 or false for boolean options or any string
(including empty string by quoting it) for other options.
Boolean options may also be set to false by simply writing:
  no-<long option name>
or
  no<long option name>

You can also write simply <long option name> to set a boolean option to true
(do not use instead of empty string).

Configuration options are overridden by command line switches.

##################################################################################################
COMMAND LINE OPTIONS

--backup   -b  Backup original files before overwriting (off by default unless --force-overwrite is set).
               Disable with --no-backup.

--batch    -B  Do not prompt the user - choose default action and force overwrite (off by default).
               Disable with --no-batch.

--check    -c  Specify the type of the package atom's arguments - 'use', 'keyword', 'env', 'guess' or
               'none' (default) . Note that this affects behaviour for ALL input files - use 'guess'
               to guess check from filename/path (useful when specifying multiple files of different
               type), use the others only if ALL input files are of the specified type.

--debug    -D  Makes a lot of noise on STDOUT. It also disables prompting the user, so you can pipe the
               output. Use only if you want to report a bug (or debug yourself).

--force-overwrite
           -f  Do not prompt to save changes - backup the original file (unless --no-backup is set) and
               write changes (off by default). Disable with --no-force-overwrite.

--help     -h  Print this help message and exit.

--ignore-use-or-keyword
           -i  A coma separated list of USE flags or keywords to ignore during check (if checking is
               to be done). These will NOT be removed even if they are not listed in any of the installed
               versions matching the package.

--keep-non-matching|keep-nonmatching
           -k  Do not remove entries with no matching versions installed (off by default). Disable with
               --no-keep-non-matching|--no-keep-nonmatching.

--keep-order
           -o  Do not sort the file alphabetically (off by default). This also disables joining of entries
               referring to the same [prefix]package[-version]. Note that even when sorting, any
               consecutive comments of the form '# required by' are grouped with the package atom
               immediately following them. Disable with --no-keep-order.

--quiet    -q  Do not produce any output - only prompts (off by default). Takes precedence over --verbose.
               Disable with --no-quiet.

--tmp-dir  -d  Directory in which the temporary file will be stored before overwrite (default is /tmp).
               If set to '' (with --tmp-dir=), the directory of the currently processed file will be used.

--verbose  -v  Print information about every entry being processed (off by default).
               Disable with --no-verbose.

If not specified, path defaults to /etc/portage/
If you want to clean package in the current directory, use cleanpkgfile <options> ./file
If file's name begins with -, use cleanpkgfile <options> -- file

##################################################################################################
EXAMPLES

__________________________________________________________________________________________________
To verbosely process package.accept_keywords, package.use and package.env
and their flags/keywords/files:
  cleanpkgfile -vcguess package.accept_keywords package.use package.env
or if your shell supports brace expansion and globbing:
  cleanpkgfile -vcguess /etc/portage/package.{*keywords,use,env}

__________________________________________________________________________________________________
To only remove atoms from package.use, which don't match any installed version:
  cleanpkgfile -vcnone package.use

__________________________________________________________________________________________________
cleanpkgfile will ignore any commented lines.
If you want to exclude certain non-commented entries from being processed,
put them inside an #IGNORE# block, like so:

#IGNORE#

# this is for multilib purposes, the following packages are not currently merged,
# but if/when they do get pulled in the USE flag should be enabled
app-admin/gamin abi_x86_32
sys-libs/e2fsprogs-libs abi_x86_32

#IGNORE#

Alternatively, you can exclude certain USE flags or keywords from being processed
(and hence removed if found to be invalid) with the --ignore-use-or-keyword option:
  cleanpkgfile -cguess -iabi_x86_32,minimal package.use

__________________________________________________________________________________________________
To force overwriting the original file(s) without prompting and do a backup
use --force-overwrite and --backup:
  cleanpkgfile -fb /etc/portage/package.*

__________________________________________________________________________________________________
To disable prompts and output, use --batch and --quiet:
  cleanpkgfile -qB /etc/portage/package.*

__________________________________________________________________________________________________
Example for a cron job:
cleanpkgfile --check=guess --batch --no-backup package.use package.accept_keywords