/* Objective Modula-2 Compiler (objm2c)
 *
 *  @file objm2_filename.h
 *  portable filename function interface
 *
 *  Compose and decompose pathnames and test file extensions
 *
 *  Author: Benjamin Kowarsch
 *
 *  Copyright (C) 2009 The Objective Modula-2 Project. All rights reserved.
 *
 *  License:
 *
 *  Redistribution  and  use  in source  and  binary forms,  with  or  without
 *  modification, are permitted provided that the following conditions are met
 *
 *  1) This file,  or any part thereof,  may  NOT  be hosted on websites which
 *     contain advertising,  unless specific prior written permission has been
 *     obtained.  The licensor will grant such permission  upon request at its
 *     sole discretion to websites the licensor does  NOT  consider abusive in
 *     their  use  of advertising.  Small notices  in the footer  of a website
 *     naming corporate rights holders,  infrastructure providers  or sponsors
 *     are not considered advertising in the context of this license.
 *
 *  2) Redistributions  of source code must retain the above copyright notice,
 *     this list of conditions and the following disclaimer.
 *
 *  3) Redistributions  in binary form  must  reproduce  the  above  copyright
 *     notice,  this list of conditions  and  the following disclaimer  in the
 *     documentation and other materials provided with the distribution.
 *
 *  4) Neither the author's name nor the names of any contributors may be used
 *     to endorse  or  promote  products  derived  from this software  without
 *     specific prior written permission.
 *
 *  5) Where this list of conditions  or  the following disclaimer, in part or
 *     as a whole is overruled  or  nullified by applicable law, no permission
 *     is granted to use the software.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,  BUT NOT LIMITED TO,  THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY  AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT  SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE  FOR  ANY  DIRECT,  INDIRECT,  INCIDENTAL,  SPECIAL,  EXEMPLARY,  OR
 * CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT  NOT  LIMITED  TO,  PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES;  LOSS OF USE,  DATA,  OR PROFITS; OR BUSINESS
 * INTERRUPTION)  HOWEVER  CAUSED  AND ON ANY THEORY OF LIABILITY,  WHETHER IN
 * CONTRACT,  STRICT LIABILITY,  OR TORT  (INCLUDING NEGLIGENCE  OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,  EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *  
 */

#ifndef OBJM2_FILENAME_H
#define OBJM2_FILENAME_H


#include "common_types.h"


// --------------------------------------------------------------------------
// Status codes
// --------------------------------------------------------------------------

typedef /* objm2_filename_status_t */ enum {
    OBJM2_FILENAME_STATUS_SUCCESS,
    OBJM2_FILENAME_STATUS_ALLOCATION_FAILED,
    OBJM2_FILENAME_STATUS_INVALID_REFERENCE,
    OBJM2_FILENAME_STATUS_INVALID_DIRECTORY,
    OBJM2_FILENAME_STATUS_INVALID_FILENAME,
    OBJM2_FILENAME_STATUS_INVALID_FILETYPE,
    OBJM2_FILENAME_STATUS_INVALID_PATHNAME,
    OBJM2_FILENAME_STATUS_PATHNAME_TOO_LONG,
    OBJM2_FILENAME_STATUS_FILENAME_TOO_LONG,
} objm2_filename_status_t;


// ---------------------------------------------------------------------------
// Filenaming schemes
// ---------------------------------------------------------------------------

typedef enum /* objm2_filenaming_t */ {
    DEFAULT_FILENAMING = 0,
    POSIX_FILENAMING,
    ISO9660_FILENAMING,
    MSDOS_FILENAMING,
    OPENVMS_FILENAMING,
    NUMBER_OF_FILENAMING_SCHEMES
} objm2_filenaming_t;


// ---------------------------------------------------------------------------
// File types
// ---------------------------------------------------------------------------

typedef enum /* objm2_file_type_t */ {
    FILE_TYPE_UNKNOWN = 0,
    FILE_TYPE_DEF,
    FILE_TYPE_MOD,
    FILE_TYPE_PROT,
    FILE_TYPE_AST,
    FILE_TYPE_SYM,
    FILE_TYPE_H,
    FILE_TYPE_C,
    FILE_TYPE_MM,
    FILE_TYPE_LLVM,
    INVALID_FILENAME
} objm2_file_type_t;


// ---------------------------------------------------------------------------
// Target types
// ---------------------------------------------------------------------------

typedef enum /* objm2_target_t */ {
    OBJM2_TARGET_OBJC,
    OBJM2_TARGET_LLVM
} objm2_target_t;


// --------------------------------------------------------------------------
// Opaque filename descriptor handle type
// --------------------------------------------------------------------------
//
// WARNING: Objects of this opaque type should only be accessed through this
// public interface.  DO NOT EVER attempt to bypass the public interface.
//
// The internal data structure of this opaque type is HIDDEN  and  MAY CHANGE
// at any time WITHOUT NOTICE. Accessing the internal data structure directly
// other than through the  functions  in this public interface is  UNSAFE and
// may result in an inconsistent program state or a crash.

typedef opaque_t objm2_filename_t;


// ---------------------------------------------------------------------------
// function:  objm2_working_directory()
// ---------------------------------------------------------------------------
//
// Obtains the  current working directory pathname  of the current process and
// returns an  immutable pointer  to the pathname string.  Subsequent calls to
// this function will always return the  same string  as the working directory
// is not supposed to change during the process' lifetime.

const char *objm2_working_directory();


// ---------------------------------------------------------------------------
// function:  objm2_is_valid_filename_string( filename )
// ---------------------------------------------------------------------------
//
// Returns true if <filename> is a valid Objective Modula-2 filename,  returns
// false otherwise.  Characters  allowed  in  filenames are  letters,  digits,
// underscore and dollar.  However, filenames must not start with a digit. The
// syntax for filenames is the same as for Objective Modula-2 identifiers:
//
// filename := ( letter | "_" | "$" ) ( letter | digit | "_" | "$" )*

bool objm2_is_valid_filename_string(const char *filename);


// --------------------------------------------------------------------------
// function:  objm2_outfile_type_for( target, sourcefile_type )
// --------------------------------------------------------------------------
//
// Returns  the  output  file  type  associated  with  <sourcefile_type>  for
// <target>.  Returns FILE_TYPE_UNKNOWN if no associated file type exists.

objm2_file_type_t objm2_outfile_type_for(objm2_target_t target,
                                         objm2_file_type_t sourcefile_type);


// ---------------------------------------------------------------------------
// function:  objm2_new_filename( dir, name, file_type, filenaming, status )
// ---------------------------------------------------------------------------
//
// Returns a newly allocated filename descriptor,  initialised with the passed
// in parameters.  The caller is responsible  for deallocating the descriptor.
// Returns NULL if  any  of <filename> and <file_type> is invalid.
//
// The status of the operation  is passed back in <status>,  unless  NULL  was
// passed in for <status>.

objm2_filename_t *objm2_new_filename(const char *directory,
                                     const char *filename,
                                     objm2_file_type_t file_type,
                                     objm2_filenaming_t filenaming,
                                     objm2_filename_status_t *status);


// ---------------------------------------------------------------------------
// function:  objm2_new_filename_from_path( path, filenaming )
// ---------------------------------------------------------------------------
//
// Returns a newly allocated filename descriptor,  initialised from path using
// filenaming scheme <filenaming>.  The caller is responsible for deallocating
// the descriptor.  The function tests the path for the presence of input file
// extensions and sets the filename descriptor's file_type field as follows:
//
// o  if  the  filename  consists  of nothing but the file extension  then the
//    descriptor's file_type field is set to INVALID_FILENAME.
//
// o  if the file extension is "DEF",  "Def"  or "def"  then  the descriptor's
//    file_type field is set to FILE_TYPE_DEF.
//
// o  if the file extension is "MOD",  "Mod"  or "mod"  then  the descriptor's
//    file_type field is set to FILE_TYPE_MOD.
//
// o  if the file extension is "PROT", "Prot" or "prot"  then the descriptor's
//    file_type field is set to FILE_TYPE_PROT.
//
// o  if the file extension matches none of the above file extensions then the
//    descriptor's file_type field is set to FILE_TYPE_UNKNOWN.
//
// For  any missing component  in <path>  an empty string  is  assigned to the
// string field representing  the missing component in the descriptor.  If all
// components are missing in <path>,  no descriptor will be created  and  NULL
// will be returned.
//
// The status of the operation  is passed back in <status>,  unless  NULL  was
// passed in for <status>.

objm2_filename_t objm2_new_filename_from_path(const char *path,
                                              objm2_filenaming_t filenaming,
                                              objm2_filename_status_t *status);


// ---------------------------------------------------------------------------
// function:  objm2_directory_string( filename )
// ---------------------------------------------------------------------------
//
// Returns  an  immutable pointer  to the  directory string  field of filename
// descriptor <filename>.  Returns NULL if the descriptor is NULL.

const char *objm2_directory_string(objm2_filename_t filename);


// ---------------------------------------------------------------------------
// function:  objm2_filename_string( filename )
// ---------------------------------------------------------------------------
//
// Returns  an  immutable pointer  to the  filename string  field  of filename
// descriptor <filename>.  Returns NULL if the descriptor is NULL.

const char *objm2_filename_string(objm2_filename_t filename);


// ---------------------------------------------------------------------------
// function:  objm2_file_ext_string( filename )
// ---------------------------------------------------------------------------
//
// Returns  an  immutable pointer  to the  file_ext string  field  of filename
// descriptor <filename>.  Returns NULL if the descriptor is NULL.

const char *objm2_file_ext_string(objm2_filename_t filename);


// ---------------------------------------------------------------------------
// function:  objm2_file_type( filename )
// ---------------------------------------------------------------------------
//
// Returns the value of the file_type field of filename descriptor <filename>.
// Returns FILE_TYPE_UNKNOWN if the descriptor is NULL.

objm2_file_type_t objm2_file_type(objm2_filename_t filename);


// ---------------------------------------------------------------------------
// function:  objm2_filenaming( filename )
// ---------------------------------------------------------------------------
//
// Returns the  filenaming scheme  of filename descriptor <filename>.  Returns
// DEFAULT_FILENAMING if the descriptor is NULL.

objm2_filenaming_t objm2_filenaming(objm2_filename_t filename);


// ---------------------------------------------------------------------------
// function:  objm2_path_from_filename( filename, status )
// ---------------------------------------------------------------------------
//
// Returns a newly allocated C string with a pathname composed from the fields
// in   filename   descriptor   <filename>.  The  caller  is  responsible  for
// deallocating the returned C string.
//
// The status of the operation  is passed back in <status>,  unless  NULL  was
// passed in for <status>.

const char objm2_path_from_filename(objm2_filename_t filename,
                                    objm2_filename_status_t *status);


// ---------------------------------------------------------------------------
// function:  objm2_dispose_filename( filename )
// ---------------------------------------------------------------------------
//
// Deallocates filename descriptor <filename> and all of its components.

void objm2_dispose_filename(objm2_filename_t filename);


#endif /* OBJM2_FILENAME_H */

// END OF FILE