path: root/support/dktools/dk4uc2l.h

/*
Copyright (C) 2015-2020, Dirk Krause
SPDX-License-Identifier: BSD-3-Clause
*/

/*
	WARNING: This file was generated by the dkct program (see
	http://dktools.sourceforge.net/ for details).
	Changes you make here will be lost if dkct is run again!
	You should modify the original source and run dkct on it.
	Original source: dk4uc2l.ctr
*/

#ifndef DK4UC2L_H_INCLUDED
/** Avoid multiple inclusions. */
#define DK4UC2L_H_INCLUDED 1


#line 10 "dk4uc2l.ctr"

/**	@file	dk4uc2l.h	Text to LaTeX conversion.

LaTeX sequences to represent a 32 bit character are found in lookup tables
in the ${datarootdir}/dktools/charmap directory. The functions in this
module read those lookup tables needed, cache the contents and provide
LaTeX sequences.

After finishing output you can write recommendations (i.e. LaTeX packages
to include, font encoding to use) as comments to the file.

The functions in this module use a dk4_er_t structure to report errors
to the calling function as good as possible.
The functions from the dk4uc2la module use a dk4_app_t structure to
report errors immediately.

Functions from the dk4uc2la and dk4uc2l module can be used combined.
A typical scenario is to use the dk4uc2l_open_app_ex1() function with la
set to 1 to open a conversion structure. This will read all the data files
and store all contained LaTeX encodings in memory when opening the structure.
Errors - i.e. failed memory allocations or syntax error in data files - are
reported immediately.
Later the dk4uc2l_find() function can be used. As problematic errors like
failed memory allocations are already reported, a NULL return value can
only indicate a missing encoding.
*/

#ifndef	DK4CONF_H_INCLUDED
#if DK4_BUILDING_DKTOOLS4
#include "dk4conf.h"
#else
#include <dktools-4/dk4conf.h>
#endif
#endif

#ifndef	DK4ERROR_H_INCLUDED
#if DK4_BUILDING_DKTOOLS4
#include "dk4error.h"
#else
#include <dktools-4/dk4error.h>
#endif
#endif

#ifndef DK4STO_H_INCLUDED
#if DK4_BUILDING_DKTOOLS4
#include "dk4sto.h"
#else
#include <dktools-4/dk4sto.h>
#endif
#endif

#ifndef	DK4STRM_H_INCLUDED
#if DK4_BUILDING_DKTOOLS4
#include "dk4strm.h"
#else
#include <dktools-4/dk4strm.h>
#endif
#endif

/**	Information about a package.
*/
typedef struct {
	char			*pn;		/**< Package name. */
	unsigned char	 used;		/**< Flag: Package used. */
} dk4_uc2l_pkg_t;

/**	Pointer to a package or an array of packages.
*/
typedef dk4_uc2l_pkg_t	*dk4_uc2l_pkg_p;

/**	Pointer to an array of package pointers.
*/
typedef	dk4_uc2l_pkg_p	*dk4_uc2l_pkg_pp;

/**	Data for contents of one file.
	The structure contains information about the character
	ranges covered by the file.
*/
typedef struct {
	dkChar		 	*fn;		/**< Short file name. */
	unsigned char	 loaded;	/**< Flag: File loaded. */
} dk4_uc2l_file_t;


/**	Range of characters.
*/
typedef struct {
	dk4_uc2l_file_t	  *file;	/**< File containing data. */
	char			 **both;	/**< LaTeX text both modes. */
	char			 **text;	/**< LaTeX text text mode. */
	char			 **math;	/**< LaTeX text math mode. */
	dk4_uc2l_pkg_t	***pkgs;	/**< Packages for characters. */
	unsigned char	  *fenc;	/**< Required font encodings. */
	dk4_um_t		  *lno;		/**< Line numbers. */
	dk4_c32_t		   start;	/**< First character of range. */
	dk4_c32_t		   end;		/**< Final character of range. */
	unsigned char	   ia;		/**< Flag: Initialisation att. */
} dk4_uc2l_range_t;


/**	Text to LaTeX conversion structure.
*/
typedef struct {
	char			 buf[16];		/**< Buffer for direct output. */
	dkChar		 	*dname;			/**< Directory name. */
	dk4_sto_t		*s_ranges;		/**< Ranges container. */
	dk4_sto_it_t	*i_ranges;		/**< Ranges container iterator. */
	dk4_sto_t		*s_files;		/**< Files container. */
	dk4_sto_it_t	*i_files;		/**< Files container iterator. */
	dk4_sto_t		*s_pkgs;		/**< Package information container. */
	dk4_sto_it_t	*i_pkgs;		/**< Package information iterator. */
	int			 	 had_error;		/**< Flag: Errors occured. */
	unsigned char	 utf8allowed;	/**< Flag: UTF-8 output allowed. */
	unsigned char	 fallowed;		/**< Allowed font encodings. */
} dk4_uc2l_t;


/**	Font encodings
*/
enum {
								/**	OT1 font encoding.
								*/
	DK4_UC2L_FONT_ENCODING_OT1	= 1 ,

								/**	T1 font encoding.
								*/
	DK4_UC2L_FONT_ENCODING_T1	= 2 ,

								/**	T4 font encoding.
								*/
	DK4_UC2L_FONT_ENCODING_T4	= 4 ,

								/**	T5 font encoding.
								*/
	DK4_UC2L_FONT_ENCODING_T5	= 8 ,

								/**	All encodings mentioned above.
								*/
	DK4_UC2L_FONT_ENCODING_ALL	= (
	  0
	  | DK4_UC2L_FONT_ENCODING_OT1
	  | DK4_UC2L_FONT_ENCODING_T1
	  | DK4_UC2L_FONT_ENCODING_T4
	  | DK4_UC2L_FONT_ENCODING_T5
	)
};



/**	Errors from this module
*/
enum {

							/**	Memory allocation failed.
							*/
	DK4_UC2L_ERROR_MEMORY	=	1 ,

							/**	Syntax error in configuration file.
							*/
	DK4_UC2L_ERROR_SYNTAX	=	2 ,

							/**	Decoding error in configuration file.
							*/
	DK4_UC2L_ERROR_DECODING =	4 ,

							/**	Other processing errors while reading data.
							*/
	DK4_UC2L_ERROR_PROCESSING =	8 ,

							/**	Failed to open one of the data files.
							*/
	DK4_UC2L_ERROR_FOPEN	=	16 ,
};



#ifdef __cplusplus
extern "C" {
#endif

/**	Open conversion structure.
	@param	dn	Directory containing the data files.
	@param	erp	Error report, may be NULL.
	@return	Valid pointer on success, NULL on error.
*/
dk4_uc2l_t *
dk4uc2l_open(const dkChar *dn, dk4_er_t *erp);

/**	Close conversion structure, release memory.
	@param	ulptr	Conversion structure to close.
*/
void
dk4uc2l_close(dk4_uc2l_t *ulptr);

/**	Find LaTeX encoding for one 32 bit character.
	@param	ulptr	Conversion structure.
	@param	c	Character to search encoding for.
	@param	mm	Flag: Math mode (1) or text mode (0).
	@param	erp	Error report, may be NULL.
	@return	Pointer to encoding string on success, NULL on error.
*/
const char *
dk4uc2l_find(dk4_uc2l_t *ulptr, dk4_c32_t c, int mm, dk4_er_t *erp);

/**	Enable or disable direct UTF-8 output.
	If you use usepackage[utf-8]{inputenc} you might want to
	enable UTF-8 output.
	@param	ulptr	Conversion structure to set up.
	@param	enabled	Flag: Enable UTF-8 output.
*/
void
dk4uc2l_allow_utf8(dk4_uc2l_t *ulptr, int enabled);

/**	Reset information about used packages and allowed and denied
	font encodings.
	Typically you want to use this function only after finishing
	one output file and starting a new one.
	@param	ulptr	Conversion structure to reset.
*/
void
dk4uc2l_clean_packages_and_fonts(dk4_uc2l_t *ulptr);

/**	Retrieve or-combination of all allowed font encodings.
	You should use this function after processing all characters.
*/
unsigned char
dk4uc2l_retrieve_allowed_fe(dk4_uc2l_t *ulptr);

/**	Check whether a character can be written to a LaTeX file directly.
	@param	c32	Character to check.
	@return	1 for yes, 0 for no.
*/
int
dk4uc2lat_direct(dk4_c32_t c32);

/**	Issue recommendations about font encodings and packages.
	Use this function after processing all characters.
	@param	ulptr	Conversion structure.
	@param	wstrm	Destination stream to write to.
	@param	erp		Error report, may be NULL.
*/
void
dk4uc2l_recommendations(dk4_uc2l_t *ulptr, dk4_stream_t *wstrm, dk4_er_t *erp);

/**	Retrieve internal error status from conversion structure.
	@param	ulptr	Conversion structure.
	@return	Error status, 0 or combination of DK4_UC2L_ERROR_MEMORY,
	DK4_UC2L_ERROR_SYNTAX, DK4_UC2L_ERROR_DECODING,
	DK4_UC2L_ERROR_PROCESSING, and DK4_UC2L_ERROR_FOPEN.
*/
int
dk4uc2l_retrieve_errors(dk4_uc2l_t *ulptr);

/**	Retrieve internal error status from conversion structure.
	@param	ulptr	Conversion structure.
	@return	Error status, 0 or combination of DK4_UC2L_ERROR_MEMORY,
	DK4_UC2L_ERROR_SYNTAX, DK4_UC2L_ERROR_DECODING,
	DK4_UC2L_ERROR_PROCESSING, and DK4_UC2L_ERROR_FOPEN.
*/
void
dk4uc2l_reset_errors(dk4_uc2l_t *ulptr);

/**	Write dkChar string LaTeX encoded to stream.
	The method is primarily selected by DK4_CHAR_SIZE.
	Use this function if you want to output a dkChar string.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String.
	@param	ie		Input encoding, only used if dkChar is char.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_dk(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const dkChar	*str,
	int				 ie,
	dk4_er_t		*erp
);

/**	Write encoded string LaTeX encoded to stream.
	The method is selected by the ie parameter.
	Use this function if your string is not necessarily a dkChar string
	but you know the encoding.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String.
	@param	ie		Input encoding, only used if dkChar is char.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_encoded(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const void		*str,
	int				 ie,
	dk4_er_t		*erp
);

/**	Write dk4_c32_t string LaTeX encoded to stream.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String to write.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_c32(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const dk4_c32_t	*str,
	dk4_er_t		*erp
);

/**	Write UTF-16 encoded dk_c32_t string LaTeX encoded to stream.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String to write.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_c16(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const dk4_c16_t	*str,
	dk4_er_t		*erp
);

/**	Write UTF-8 encoded char string LaTeX encoded to stream.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String to write.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_utf8(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const char		*str,
	dk4_er_t		*erp
);

/**	Write ANSI encoded char string LaTeX encoded to stream.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String to write.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_ansi(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const char		*str,
	dk4_er_t		*erp
);

/**	Write ASCII encoded char string LaTeX encoded to stream.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String to write.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_ascii(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const char		*str,
	dk4_er_t		*erp
);

/**	Write char string LaTeX encoded to stream.
	@param	wstrm	Stream to write to.
	@param	ulptr	Conversion structure.
	@param	str		String to write.
	@param	ie		Input encoding.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk4uc2l_string_c8(
	dk4_stream_t	*wstrm,
	dk4_uc2l_t		*ulptr,
	const char		*str,
	int				 ie,
	dk4_er_t		*erp
);

#ifdef __cplusplus
}
#endif




#endif