// file      : clean/clean.cli
// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <vector>;
include <string>;
include <cstdint>; // uint16_t

"\section=1"
"\name=brep-clean"
"\summary=clean brep databases"

{
  "<options> <buildtab> <timeout> <name> <hours>",

  "\h|SYNOPSIS|

   \c{\b{brep-clean --help}\n
      \b{brep-clean --version}\n
      \b{brep-clean} [<options>] builds <buildtab> [<timeout>...]\n
      \b{brep-clean} [<options>] tenants <timeout>}

   \h|DESCRIPTION|

   \cb{brep-clean} deletes expired package builds from the brep \cb{build}
   database or deletes/archives tenants from the brep \cb{package} database.

   The first form considers a build as expired if the corresponding package
   version is not in the \cb{package} database, or the configuration is not
   listed in the <buildtab> file, or its age is older than the specified
   timeout for this build toolchain.

   Build <timeout>, if specified, should have the \c{[<name>=]<hours>} form.
   Specify zero for <hours> to make builds for a toolchain to never expire.
   Omit <name> (including \cb{=}) to specify the default timeout. It will
   apply to all the toolchains that don't have a toolchain-specific timeout.

   The second form considers a tenant as expired if its age is older than the
   specified <timeout>.

   If the \cb{--archive} option is specified, then the tenant is archived
   rather than deleted. In this state the tenant packages (and their builds)
   are still visible in \cb{brep} but are not (re-)built by build bots.

   Note that \cb{brep-clean} expects the \cb{build} and \cb{package} database
   schemas to have already been created using \l{brep-migrate(1)}."
}

class options
{
  "\h|OPTIONS|"

  bool --archive
  {
    "Archive old tenants."
  }

  std::string --db-user
  {
    "<user>",
    "Database user name. If not specified, then operating system (login) name
     is used."
  }

  std::string --db-password
  {
    "<pass>",
    "Database password. If not specified, then login without password is
     expected to work."
  }

  std::string --db-name
  {
    "<name>",
    "Database name. If not specified, then \cb{brep_build} is used for the
     first form and \cb{brep_package} for the second."
  }

  std::string --db-host
  {
    "<host>",
    "Database host name, address, or socket. If not specified, then connect to
     \cb{localhost} using the operating system-default mechanism (Unix-domain
     socket, etc)."
  }

  std::uint16_t --db-port = 0
  {
    "<port>",
    "Database port number. If not specified, the default port is used."
  }

  std::string --pager // String to allow empty value.
  {
    "<path>",
    "The pager program to be used to show long text. Commonly used pager
     programs are \cb{less} and \cb{more}. You can also specify additional
     options that should be passed to the pager program with
     \cb{--pager-option}. If an empty string is specified as the pager
     program, then no pager will be used. If the pager program is not
     explicitly specified, then \cb{brep-clean} will try to use \cb{less}.
     If it is not available, then no pager will be used."
  }

  std::vector<std::string> --pager-option
  {
    "<opt>",
    "Additional option to be passed to the pager program. See \cb{--pager}
     for more information on the pager program. Repeat this option to
     specify multiple pager options."
  }

  bool --help {"Print usage information and exit."}
  bool --version {"Print version and exit."}
};

"\h|EXIT STATUS|

\dl|

\li|\cb{0}

Success.|

\li|\cb{1}

Fatal error.|

\li|\cb{2}

An instance of \cb{brep-clean} or \l{brep-migrate(1)} is already running. Try
again.|

\li|\cb{3}

Recoverable database error. Try again.||
"