(Kevux) Remove Documentation

The (Kevux) Remove program, called remove, is a tool for deleting (removing) various file types.

The remove program supports simulate mode to pretend to delete, without actuallying removing files.

This also provides the following standard programs designed to implement most, but not all, of the standard functionality:

rm
rmdir
unlink

Standard Parameters

Short	Long	Description
`-h`	`--help`	Print the help message.
`+C`	`++copyright`	Print the copyright.
`+d`	`++dark`	Output using colors that show up better on dark backgrounds.
`+l`	`++light`	Output using colors that show up better on light backgrounds.
`+n`	`++no_color`	Do not print using color.
`+Q`	`++quiet`	Decrease verbosity, silencing most output.
`+E`	`++error`	Decrease verbosity, using only error output.
`+N`	`++normal`	Set verbosity to normal.
`+V`	`++verbose`	Increase verbosity beyond normal output.
`+D`	`++debug`	Enable debugging, significantly increasing verbosity beyond normal output.
`+v`	`++version`	Print only the version number.

The +Q/++quiet parameter silences all output that is not the intent and purpose of the program.
For example, the purpose of the utf8 program is to print the Unicode code point or the UTF-8 byte code.
The +Q/++quiet will not suppress this output.
The new line printed at the end of the program, is however, not printed.
The +Q/++quiet is ideal for using in scripting to help guarantee more consistent and controlled output.

The +N/++no_color simplifies the output to avoid the special color character codes.
The special color character codes tend to take up a lot of extra space and may slow down printing performance.

Program Parameters

Short	Long	Description
`-A`	`--accessed`	Remove by file last accessed date and time.
`-b`	`--block`	Remove by file type of block.
`-C`	`--changed`	Remove by file changed on date and time.
`-c`	`--character`	Remove by file type of character.
`-O`	`--different`	Remove by file owner by a user different from the current calling user.
`-d`	`--directory`	Remove by file type of directory.
`-e`	`--empty`	Remove directory by a specific empty or not empty state.
`-o`	`--fifo`	Remove by file type of FIFO.
`-F`	`--follow`	Remove the file being pointed to rather than the symbolic link itself.
`-f`	`--force`	Ignore non-existent files and never prompt.
`-g`	`--group`	Remove by file group ID or name.
`-l`	`--link`	Remove by file type of link.
`-m`	`--mode`	Remove by file mode.
`-p`	`--prompt`	Prompt before removing.
`-r`	`--recurse`	Traverse into directories when removing.
`-R`	`--regular`	Remove by file type of regular.
`-s`	`--same`	Remove by file owner by the current calling user.
`-S`	`--simulate`	Simulate removal rather than actually removing.
`-k`	`--socket`	Remove by file type of socket.
`-Y`	`--stay`	Remove the symbolic link itself rather than the file being pointed to.
`-t`	`--tree`	Remove entire specified directory tree.
`-U`	`--updated`	Remove by file last updated date and time.
`-u`	`--user`	Remove by file user ID or name.
	`--allow_root`	Allow removal of the root directory '/'.
	`--local`	Designate dates are in local time, unless the time zone is specified.
	`--remember`	Remember paths of files already deleted so as to not potentially error out on already removed path.
	`--unknown`	Remove by file type of unknown.
	`--utc`	Designate dates are in UTC, unless the time zone is specified.

The parameters '--accessed', '--changed', '--group', '--mode', '--updated', and '--user' may be specified multiple times.

The value passed to the parameter '--group' may either be a GID or a group name.

The value passed to the parameter '--user' may either be a UID or a user name.

The parameter '--empty' supports the following values:

'not': Remove directories that are not empty.
'not_fail': Fail when attempting to remove directories that are not empty.
'only': Remove directories that are empty.
'only_fail': Fail when removing directoies that are empty.

The parameter '--prompt' supports the following values:

'each': Operate in interactive mode, prompting for every file.
'follow': Operate in interactive mode, prompting for every link that is being followed.
'never': Do not operate in interactive mode.
'once': Operate in interactive mode: prompting if removing 3 or more files.

The first value to the parameter '--mode' must be any of:

'~~' or 'different': Mode matches different parts.
'==' or 'same': Mode matches exactly.
'~=' or 'similar': Mode matches the same parts.
'<>' or 'not': Mode does not match exactly.

The second value to the parameter '--mode' may be either a mode octal or a mode string, such as: '0751' or 'u+rwX,g+r'.

The date related parameters are: '--accessed', '--changed', and '--updated'.

Where 'updated' refers to when the contents of a file have been changed and 'changed' refers to when the file system data for that file have been changed.

The first value to the date related parameters must be any of the following comparison operators:

'==' or 'equal': Date match using an equal to operation.
'<' or 'less': Date match using a less than operation.
'<=' or 'less_equal': Date match using a less than or equal to operation.
'>' or 'more': Date match using a more than operation.
'>=' or 'more_equal': Date match using a more than or equal to operation.
'<>' or 'not': Date match using a not equal to operation.

Parameters with the '<' and '>l' characters will need to be quoted to prevent unintended redirecting.

When the second value to the date related parameters must be a date.

Valid dates for the date related parameters must be any of the following:

'now': Use the current day and time.
'Time': Use the Time format, such as '1234:5678'.
'EpochTime': Use the EpochTime format, such as '1234::5678'.
'today': Use the current day.
'tomorrow': Use the next day.
'Unix Epoch': Use the EpochTime format, such as '1672639985'.
'yesterday': Use the previous day.

Valid formats for the date related parameters must be any of the following:

'%Y/%m/%d %I:%M:%S %p %z': A date like '2022/12/30 1:45:02 pm +0600'.
'%Y/%m/%d %H:%M:%S %z': A date like '2022/12/30 13:45:02 +0600'.
'%Y/%m/%d %I:%M %p %z': A date like '2022/12/30 1:45 pm +0600'.
'%Y/%m/%d %H:%M %z': A date like '2022/12/30 13:45 +0600'.
'%Y/%m/%d %I %p %z': A date like '2022/12/30 1 pm +0600'.
'%Y/%m/%d %H %z': A date like '2022/12/30 13 +0600'.
'%Y/%m/%d %I:%M:%S %p': A date like '2022/12/30 1:45:02 pm'.
'%Y/%m/%d %H:%M:%S': A date like '2022/12/30 13:45:02'.
'%Y/%m/%d %I:%M %p': A date like '2022/12/30 1:45 pm'.
'%Y/%m/%d %H:%M': A date like '2022/12/30 13:45'.
'%Y/%m/%d %I %p': A date like '2022/12/30 1 pm'.
'%Y/%m/%d %H': A date like '2022/12/30 13'.
'%Y/%m/%d': A date like '2022/12/30'.
'%Y/%m': A date like '2022/12'.
'%Y/': A date like '2022/'.

Valid formats for the 'Time' and 'EpochTime' formats might look like the following:

'0::167242950220': An EpochTime with an explicit year.
'1970:1672429502000000000': A Time with an explicit year.
'::1672429502': An EpochTime with an implicit year (relative to the UNIX Epoch).
':1672429502000000000': A Time with an implicit year (relative to the current year).

The '--remember' parameter accepts either yes or no to designate whether or not to remember already pocessed paths.