package Command_Line_Interface is
    --------------------------------------------------------------------------
    --
    -- Abstract   : This package returns the names of files as they were entered
    --               on the command line.  The SPELL command line is of the
    --               following general syntax:
    --
    --                      spell document_file word_list master_dict acronym_dict
    --                              user1_dict user2_dict ... user6_dict
    --
    --               This is the fixed-parameter form.  Named parameters are also
    --               permitted of the general form:
    --
    --                      spell name=file
    --
    --               where valid 'name' values are:
    --
    --                      F - for document file
    --                      W - for word list
    --                      M - for master dictionary
    --                      A - for acronym dictionary
    --                      Un - for user dictionary, where n is 1-6
    --
    --               The command line may include fixed parameters followed
    --               by named parameters, but no fixed parameters may follow
    --               any named parameters.  Examples:
    --
    --                      SPELL myfile.txt u1=mywords.dct m=technical
    --                              document is MYFILE.TXT, master dictionary
    --                              is TECHNICAL, user dictionary 1 is MYWORDS.DCT
    --
    --                      SPELL myfile.txt words technical tac mywords.dct
    --                              document is MYFILE.TXT, word list is WORDS,
    --                              master dictionary is TECHNICAL, acronym
    --                              dictionary is TAC, and user 1 dictionary is
    --                              MYWORDS.DCT
    --
    --                      SPELL myfile.txt u6=hiswords.txt
    --                              document is MYFILE.TXT and user 6 dictionary
    --                              is HISWORDS.TXT
    --
    --------------------------------------------------------------------------

    Mix_Error : exception;
    Name_Error : exception;
    User_Dictionary_Number : exception;
    --------------------------------------------------------------------------
    -- MIX_ERROR is raised during the command line parse when a fixed
    --  parameter is encountered after a named parameter was processed;
    --  for example,
    --      SPELL myfile.txt m=master mywords
    --  will raise a MIX_ERROR when MYWORDS is processed because the
    --  named parameter "M=MASTER" was previously encountered.  Once named
    --  parameters are encountered, fixed parameter positioning is lost.
    --
    -- NAME_ERROR is raised during the command line parse when a named
    --  parameter is invalid, like "X=MYFILE", where X is not one of the
    --  legal names F, W, M, A, or Un.
    --
    -- USER_DICTIONARY_NUMBER is raised during the command line parse when
    --  the number following the U in a named parameter association is not
    --  in the range 1..6.  For example, "SPELL myfile.txt u7=user" will
    --  raise this exception because U7 is not in the range U1..U6.
    -- USER_DICTIONARY_NUMBER is also raised when the procedure USER_DICTIONARY
    --  is called with a KEY whose value is not in the range 1..6.
    --
    -- Any exception raised during the command line parse results in the
    --  error word being set, and the procedure BAD_WORD will return the
    --  error word so the point at which the parse failed can be examined.
    --
    --------------------------------------------------------------------------


    procedure File_Name (File : out String; Last : out Natural);
    --------------------------------------------------------------------------
    -- Abstract   : Return the name of the document file, if any.  If LAST=0,
    --               no document file was specified.
    --------------------------------------------------------------------------
    -- Parameters : FILE           - string containing document file name
    --              LAST           - number of characters in file name
    --------------------------------------------------------------------------


    procedure Word_List (File : out String; Last : out Natural);
    --------------------------------------------------------------------------
    -- Abstract   : Return the name of the word list file, if any.
    --------------------------------------------------------------------------
    -- Parameters : As above.
    --------------------------------------------------------------------------


    procedure Master_Dictionary (File : out String; Last : out Natural);
    --------------------------------------------------------------------------
    -- Abstract   : Return the name of the master dictionary file, if any.
    --------------------------------------------------------------------------
    -- Parameters : As above.
    --------------------------------------------------------------------------


    procedure Acronym_Dictionary (File : out String; Last : out Natural);
    --------------------------------------------------------------------------
    -- Abstract   : Return the name of the acronym dictionary file, if any.
    --------------------------------------------------------------------------
    -- Parameters : As above.
    --------------------------------------------------------------------------


    procedure User_Dictionary
                 (Key : Natural; File : out String; Last : out Natural);
    --------------------------------------------------------------------------
    -- Abstract   : Return the name of user dictionary N, where 1 <= N <= 6.
    --               The exception USER_DICTIONARY_NUMBER will be raised if
    --               the passed parameter (KEY) is not in the range 1..6.
    --------------------------------------------------------------------------
    -- Parameters : KEY            - Number of user dictionary desired (1..6)
    --              FILE           - string containing the name of the user dict
    --              LAST           - number of characters in the name of dict
    --------------------------------------------------------------------------


    procedure Bad_Word (Word : out String; Last : out Natural);
    --------------------------------------------------------------------------
    -- Abstract   : If the parse of the command line parameters fails for some
    --               reason, such as an invalid named association being
    --               employed (like X=file, where X isn't one of F,W,M,A,Un),
    --               this routine will return the word at which the parse
    --               failed.  This error word is set by any of the exceptions
    --               (above) being raised.
    --------------------------------------------------------------------------
    -- Parameters : WORD           - string containing the word in error
    --              LAST           - number of characters in word
    --------------------------------------------------------------------------

end Command_Line_Interface;