-- This package provides all of the argument defaulting and
-- validity checking required by the Software Catalog toolset.
--
-- All strings are returned in uppercase.
--
with Subtypes;
use Subtypes;
package Arguments is

    subtype Argument is Simple_Name;

    Default_User : constant String := "<CURRENT_USER>";

    function User_From (User_Argument : in Argument) return User_Name;
    --
    -- Returns the user name corresponding to the argument.
    --
    -- Raises "Invalid_Username" if the specified user name is invalid.
    --
    -- If the argument is equal to "<CURRENT_USER>", the return value
    -- will be equal to "System_Utilities.User_Name".

    Default : constant String := "<DEFAULT>";

    function Catalog_From
                (This_Catalog_Argument : in Argument) return Full_Name;
    --
    -- Returns the specified argument expanded into the full name
    -- of a catalog. Does not attempt to resolve the resulting full
    -- name to an actual catalog, but does check it for basic
    -- syntactic validity.
    --
    -- If the argument is equal to "<DEFAULT>", consults the defaults
    -- for the current user.
    --
    -- Raises "Invalid_Catalog" if the specified argument cannot be
    -- expanded into a valid catalog name.
    --
    -- Raises "IO_Failure" if a problem is encountered obtaining the
    -- defaults.

    function Simple_Catalog_From
                (This_Catalog_Argument : in Argument) return Simple_Name;
    --
    -- Has the same behavior as "Catalog_From", except that the return
    -- value is the simple name of the catalog instead of the full name.

    function Catalog_For (This_User : in Argument) return Full_Name;
    --
    -- Returns the default catalog for the specified user (which may
    -- be defaulted to "<CURRENT_USER>").
    --
    -- Raises "Invalid_Username" if the specified username is invalid.
    --
    -- Raises "Invalid_Catalog" if the default is not a valid catalog
    -- name.
    --
    -- Raises "IO_Failure" if a problem is encountered obtaining the
    -- defaults.

    function Simple_Catalog_For (This_User : in Argument) return Simple_Name;
    --
    -- Has the same behavior as "Catalog_For", except that the return
    -- value is the simple name of the catalog instead of the full name.

    function Version_From
                (This_Catalog_Argument : in Argument;
                 This_Version_Argument : in Argument) return Full_Name;
    --
    -- Returns the specified arguments expanded into the full name
    -- of a version. Does not attempt to resolve the resulting full
    -- name to an actual version, but does check it for basic
    -- syntactic validity.
    --
    -- For each argument which is equal to "<DEFAULT>", consults the
    -- defaults for the current user.
    --
    -- Raises "Invalid_Catalog" if the specified catalog argument cannot
    -- be expanded into a valid catalog name.
    --
    -- Raises "Invalid_Version" if the specified arguments cannot be
    -- expanded into a valid version name.
    --
    -- Raises "IO_Failure" if a problem is encountered obtaining the
    -- defaults.

    function Simple_Version_From
                (This_Catalog_Argument : in Argument;
                 This_Version_Argument : in Argument) return Simple_Name;
    --
    -- Has the same behavior as "Version_From", except that the return
    -- value is the simple name of the version instead of the full name.

    function Version_For (This_User : in Argument) return Full_Name;
    --
    -- Returns the default version for the specified user (which may
    -- be defaulted to "<CURRENT_USER>").
    --
    -- Raises "Invalid_Username" if the specified username is invalid.
    --
    -- Raises "Invalid_Version" if the default is not a valid version
    -- name.
    --
    -- Raises "IO_Failure" if a problem is encountered obtaining the
    -- defaults.

    function Simple_Version_For (This_User : in Argument) return Simple_Name;
    --
    -- Has the same behavior as "Version_For", except that the return
    -- value is the simple name of the version instead of the full name.

    Default_Catalog_Library : constant String := "<DEFAULT_LIBRARY>";

    function Browser_Version_From
                (This_Library : in String; This_Default_Version : in Full_Name)
                return Full_Name;
    --
    -- Returns "This_Default_Version" if "This_Library" is equal to
    -- "Default_Catalog_Library". Otherwise, returns "This_Library".

    Invalid_Username : exception;

    Invalid_Catalog : exception;
    Invalid_Version : exception;

    Invalid_View_Name : exception;
    Invalid_View_Kind : exception;

    Io_Failure : exception;

end Arguments;