# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
# version 2025/05/01
#
# This file (assumed to be named readme.remove.txt) can be more easily read using the following iki_read commands:
#   iki_read readme.remove.txt +Q -w -W code '"' '"'
#
# To read the "Remove Readme Documentation" section of this file, use this command sequence:
#   fss_basic_list_read readme.remove.txt +Q -cn "Remove Readme Documentation" | iki_read +Q -w -W code '"' '"'
#

Remove Readme Documentation:
  The bold:"remove" is a program for removing files and directories.

  This program is similar to the common programs code:"rm", code:"rmdir", and code:"unlink".
  Compatibility helper programs are provided to closely match functionality of their respectively named common program.
  Not every functionality of those programs may be supported by these compatibility helpers but they should closely resembly most of the common functionality.

  The default behavior is to remove all non-directory files and to fail when a directory is attempted to be removed.
  When any of the file type parameters are specified, then the default behavior is completely overwritten.
  Once a single file type parameter is specified, then the removals happen for all specified file type parameters combined.
  This default behavior is not used by the compatibility helper programs which define their own defaults and parameters.

  The bold:"remove" program has the following arguments\:

    The code:"--accessed" (code:"-A") parameter filters by accessed date and time and accepts two additional parameters, see below for details.
    The code:"--block" (code:"-b") parameter is a file type parameter that restricts removal to block device files.
    The code:"--changed" (code:"-C") parameter filters by changed date and time and accepts two additional parameters, see below for details.
    The code:"--character" (code:"-c") parameter is a file type parameter that restricts removal to character device files.
    The code:"--different" (code:"-O") parameter restricts removal of files whose owner is not the user of the caller of the program.
    The code:"--directory" (code:"-d") parameter is a file type parameter that restricts removal to directory files.
    The code:"--empty" (code:"-e") parameter to remove empty directories, see below for details.
    The code:"--fifo" (code:"-o") parameter is a file type parameter that restricts removal to FIFO files.
    The code:"--follow" (code:"-F") parameter alters removal to remove the file pointed to by a symbolic link rather than the link itself (opposite of --stay).
    The code:"--force" (code:"-f") parameter to ignore non-existent files and never prompt.
    The code:"--group" (code:"-g") parameter accepts two additional parameters that restrict removal to the given group identifier.
    The code:"--link" (code:"-l") parameter is a file type parameter that restricts removal to a symbolic link file.
    The code:"--local" parameter designates that dates are in local time, unless the time zone is specified.
    The code:"--mode" (code:"-m") parameter accepts two additional parameters that restrict removal to the given file mode, see below for details.
    The code:"--prompt" (code:"-p") parameter accepts one additional parameter that designates operating in interactive mode and prompts the user for input, see below for details.
    The code:"--recurse" (code:"-g") parameter remove directories and their contents recursively.
    The code:"--regular" (code:"-R") parameter is a file type parameter that restricts removal to regular files (commonly referred to as just bold:"file").
    The code:"--remember" parameter to remember paths of files already deleted so as to not potentially error out on already removed path and requires either code:"yes" or code:"no" as an additional argument.
    The code:"--same" (code:"-s") parameter restricts removal of files whose owner is the user of the caller of the program.
    The code:"--simulate" (code:"-S") parameter designates that the program operates in simulation mode, never removing anything and instead printing what would have been mode (unless in quiet mode).
    The code:"--socket" (code:"-k") parameter is a file type parameter that restricts removal to socket files.
    The code:"--stay" (code:"-Y") parameter designating to operate on any symbolic links directly rather than what they are pointing to (opposite of --follow).
    The code:"--tree" (code:"-t") parameter designates that the specified directory tree is also deleted (may require --force and --recurse if directory tree is not empty).
    The code:"--unknown" parameter is a file type parameter that restricts removal to files of unknown types.
    The code:"--updated" (code:"-U") parameter filters by updated date and time and accepts two additional parameters, see below for details.
    The code:"--user" (code:"-u") parameter accepts two additional parameters that restrict removal to the given group identifier.
    The code:"--utc" parameter designates that dates are in UTC, unless the time zone is specified.

  The code:"--accessed" (code:"-A"), code:"--changed" (code:"-C"), and code:"--updated" (code:"-U") parameters' two arguments are (in this order)\:

    1) One of bold:"<", bold:"<=", bold:"==", bold:">=", bold:">", bold:"<>", bold:"equal", bold:"less", bold:"less_equal", bold:"more", bold:"more_equal", and bold:"not" to represent the relationship between the data for the file as the left side and the second argument as the right side.
    2) The date in any of the following formats\:

      - One of these reserved words: bold:"now", bold:"today", bold:"tomorrow", and bold:"yesterday".
      - The bold:"EpochTime format, such as code:"1234::5678".
      - The bold:"Time" format, such as code:"1234:5678".
      - The bold:"Unix Epoch" format, such as code:"1672639985".
      - Various standard date time formats, such as bold:"2022/12/30 1:45:02 pm +0600".

  The code:"--empty" (code:"-e") parameter supports the following values\:

    - code:"not" for designating removing directories that are not empty.
    - code:"not_fail" for designating to fail when attempting to remove directories that are not empty.
    - code:"only' for designating to only remove directories that are empty.
    - code:"only_fail" for desginating to fail when removing directoies that are empty.

  The code:"--prompt" (code:"-p") parameter supports the following values\:

    - code:"each" for designating operating in interactive mode, prompting for every file.
    - code:"follow" for designating operating in interactive mode, prompting for every link that is being followed.
    - code:"never" for designating to not operate in interactive mode.
    - code:"once" for designating operating in interactive mode: prompting if removing 3 or more files while not in recursive mode.

  The code:"--mode" (code:"-m") supports the following values\:

    - code:"~~" and code:"different" designate matching different parts of each mode.
    - code:"==" and code:"same" designate matching modes exactly.
    - code:"~=" and code:"similar" designate matching the same parts of each mode.
    - code:"<>" and code:"not" designate does not match modes exactly.
