flaggie / README

Full commit
flaggie -- an another flag mangler

Quick introduction

flaggie is just another handy, CLI-based mangler for `package.*` files.
Although it is originally based on [flagedit][1] by Damien Krotkine, it
aims at being nicer to use and more powerful than flagedit.

Key features:
- use of portage API (you no longer have to specify the category even
	the first time you're adding a flag!),
- support for `package.*` directories (most actions performed by flaggie
	affect the effective declarations, in whichever of the files they
- support for `package.license` file,
- smart recognition of action arguments -- flaggie knows whether you're
	passing a USE flag or a keyword.



Symbolically, the flaggie synopsis could be written as:

	flaggie [<options>] [<global-actions>] [<packages> <actions>] [...]

In other words, the basic arguments to `flaggie` consist of package
specifications and action specifications grouped together. Each group
of actions is applied to the package group preceding it; and if a group
of actions precedes the first package group, it is considered a global
action group and these actions are supposedly performed on the variables
in the `make.conf` file.

A package specification has the same atom format as one used by emerge.
You can provide a simple package name as well as a complete,
version-restricted atom. If you don't specify the package category,
flaggie will try to grab it using Portage API.

An action specification consists of an action symbol and an optional or
obligatory argument (flag). The action symbols are:

- `+` to enable a flag,
- `-` to disable a flag,
- `%` to reset the flag(s) to the default state (remove them completely
	from the files),
- `?` to print the effective flag declaration from the files.

Each of the actions should be followed by an argument. It could be
a flag name, a keyword or a license string. Arguments can be shell
patterns (same as in filename matching). If no argument is passed,
flaggie assumes `*`.

With `+` and `-` actions, pattern matching is performed against package
`IUSE`, `KEYWORDS` or `LICENSE` variable. With `%` and `?`, it is done
against values specified in `package.*` files.

In addition to that, the argument can be preceded by a namespace
specifier in the form `ns::`, where `ns` can be one of `use`, `kw` or
`lic` (or a pattern).

When no namespace is specified, the namespace is guessed from the actual
argument if it is not a pattern; `use` is assumed otherwise.

Cleanup actions

Except for the specific actions, flaggie can be perform a set of cleanup
actions which are done on whole `package.*` files. These are enabled
using long options.

The following cleanup actions are supported:

- `--drop-ineffective` to drop all flag declarations which are
	considered ineffective. In other words, those which are overriden
	by the entries or flags following them.

	In other words, the following example file:

		app-misc/foo bar baz
		app-misc/foo -bar bar

	would be written as:

		app-misc/foo baz
		app-misc/foo bar

- `--sort-entries` to sort all entries in the file by package name.

- `--sort-flags` to sort all flags (keywords, licenses) in the entries
	by their basename.


1. Enabling `USE=doc` for `x11-libs/gtk+:2`:

		flaggie gtk+:2 +doc

2. Keyword-unmasking `sys-apps/portage-2.2` (omitting the live version):

		flaggie '<portage-9999' '+**'

3. Resetting all USEflags of `net-im/ekg2` to their default values:

		flaggie ekg2 %

4. Easy license-unmasking `www-plugins/adobe-flash`:

		flaggie adobe-flash +lic::

5. Performing a cleanup of `package.*` files:

		flaggie --cleanup

6. Enabling all devices for `app-misc/lirc` (e.g. for testing):

		flaggedit app-misc/lirc '+lirc_devices_*'

<!-- vim:se syn=markdown : -->