From 5d7ec0cc1fad5e7ae9b6f87d0a920e4c60269e82 Mon Sep 17 00:00:00 2001 From: hyung-hwan Date: Mon, 29 Sep 2025 00:59:50 +0900 Subject: [PATCH] minor code reformat --- README.md | 24 ++++++++++++------------ lib/hawk-arr.h | 24 ++++++++++++------------ lib/hawk-cmn.h | 22 ++++++++++++++++++---- lib/hawk-cut.h | 39 +++++++++++++++++---------------------- lib/hawk-htb.h | 42 +++++++++++++++++++++--------------------- lib/hawk-prv.h | 4 ++-- lib/hawk-sed.h | 30 +++++++++++++++--------------- lib/hawk-xma.h | 30 +++++++++++++++--------------- lib/hawk.h | 18 ++++++++++-------- 9 files changed, 122 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index 761645fc..735965f8 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ int main () hawk = hawk_openstd(0, HAWK_NULL); /* create a hawk instance */ if (!hawk) { - fprintf (stderr, "ERROR: cannot open hawk\n"); + fprintf(stderr, "ERROR: cannot open hawk\n"); ret = -1; goto oops; } @@ -109,7 +109,7 @@ int main () ret = hawk_parsestd(hawk, psin, HAWK_NULL); /* parse the script */ if (ret <= -1) { - hawk_logbfmt (hawk, HAWK_LOG_STDERR, "ERROR(parse): %js\n", hawk_geterrmsg(hawk)); + hawk_logbfmt(hawk, HAWK_LOG_STDERR, "ERROR(parse): %js\n", hawk_geterrmsg(hawk)); ret = -1; goto oops; } @@ -124,7 +124,7 @@ int main () ); if (!rtx) { - hawk_logbfmt (hawk, HAWK_LOG_STDERR, "ERROR(rtx_open): %js\n", hawk_geterrmsg(hawk)); + hawk_logbfmt(hawk, HAWK_LOG_STDERR, "ERROR(rtx_open): %js\n", hawk_geterrmsg(hawk)); ret = -1; goto oops; } @@ -132,17 +132,17 @@ int main () retv = hawk_rtx_loop(rtx); /* alternatively, hawk_rtx_exec(rtx, HAWK_NULL, 0) */ if (!retv) { - hawk_logbfmt (hawk, HAWK_LOG_STDERR, "ERROR(rtx_loop): %js\n", hawk_geterrmsg(hawk)); + hawk_logbfmt(hawk, HAWK_LOG_STDERR, "ERROR(rtx_loop): %js\n", hawk_geterrmsg(hawk)); ret = -1; goto oops; } /* lowered the reference count of the returned value */ - hawk_rtx_refdownval (rtx, retv); + hawk_rtx_refdownval(rtx, retv); ret = 0; oops: - if (rtx) hawk_rtx_close (rtx); /* destroy the runtime context */ - if (hawk) hawk_close (hawk); /* destroy the hawk instance */ + if (rtx) hawk_rtx_close(rtx); /* destroy the runtime context */ + if (hawk) hawk_close(hawk); /* destroy the hawk instance */ return -1; } ``` @@ -180,22 +180,22 @@ int main () if (hawk.open() <= -1) { - fprintf (stderr, "unable to open hawk - %s\n", hawk.getErrorMessageB()); + fprintf(stderr, "unable to open hawk - %s\n", hawk.getErrorMessageB()); return -1; } HAWK::HawkStd::SourceString s("BEGIN { print \"hello, world\"; }"); if (hawk.parse(s, HAWK::HawkStd::Source::NONE) == HAWK_NULL) { - fprintf (stderr, "unable to parse - %s\n", hawk.getErrorMessageB()); - hawk.close (); + fprintf(stderr, "unable to parse - %s\n", hawk.getErrorMessageB()); + hawk.close(); return -1; } HAWK::Hawk::Value vr; - hawk.loop (&vr); // alternatively, hawk.exec (&vr, HAWK_NULL, 0); + hawk.loop(&vr); // alternatively, hawk.exec (&vr, HAWK_NULL, 0); - hawk.close (); + hawk.close(); return 0; } ``` diff --git a/lib/hawk-arr.h b/lib/hawk-arr.h index 31721333..a2e1b494 100644 --- a/lib/hawk-arr.h +++ b/lib/hawk-arr.h @@ -27,7 +27,7 @@ #include -/** @file +/** \file * This file provides a linear dynamic array. It grows dynamically as items * are added. */ @@ -253,7 +253,7 @@ HAWK_EXPORT int hawk_arr_getscale ( * of a key and a value. A scale factor determines the actual length of * a key and a value in bytes. A arr is created with a scale factor of 1. * The scale factor should be larger than 0 and less than 256. - * It is a bad idea to change the scale factor when @a arr is not empty. + * It is a bad idea to change the scale factor when \a arr is not empty. */ HAWK_EXPORT void hawk_arr_setscale ( hawk_arr_t* arr /**< array */, @@ -347,11 +347,11 @@ HAWK_EXPORT void hawk_arr_clear ( ); /** - * The hawk_arr_walk() function calls the @a walker function for each - * element in the array beginning from the first. The @a walker function + * The hawk_arr_walk() function calls the \a walker function for each + * element in the array beginning from the first. The \a walker function * should return one of #HAWK_ARR_WALK_FORWARD, #HAWK_ARR_WALK_BACKWARD, * #HAWK_ARR_WALK_STOP. - * @return number of calls to the @a walker fucntion made + * \return number of calls to the \a walker fucntion made */ HAWK_EXPORT hawk_oow_t hawk_arr_walk ( hawk_arr_t* arr, @@ -360,11 +360,11 @@ HAWK_EXPORT hawk_oow_t hawk_arr_walk ( ); /** - * The hawk_arr_rwalk() function calls the @a walker function for each - * element in the array beginning from the last. The @a walker function + * The hawk_arr_rwalk() function calls the \a walker function for each + * element in the array beginning from the last. The \a walker function * should return one of #HAWK_ARR_WALK_FORWARD, #HAWK_ARR_WALK_BACKWARD, * #HAWK_ARR_WALK_STOP. - * @return number of calls to the @a walker fucntion made + * \return number of calls to the \a walker fucntion made */ HAWK_EXPORT hawk_oow_t hawk_arr_rwalk ( hawk_arr_t* arr, @@ -387,7 +387,7 @@ HAWK_EXPORT hawk_oow_t hawk_arr_pushstack ( * The hawk_arr_popstack() function deletes the last array data. It is a utility * function to allow stack-like operations over an array. To do so, you should * not play with other non-stack related functions. - * @note You must not call this function if @a arr is empty. + * \note You must not call this function if \a arr is empty. */ HAWK_EXPORT void hawk_arr_popstack ( hawk_arr_t* arr @@ -397,8 +397,8 @@ HAWK_EXPORT void hawk_arr_popstack ( * The hawk_arr_pushheap() function inserts data to an array while keeping the * largest data at position 0. It is a utiltiy funtion to implement a binary * max-heap over an array. Inverse the comparator to implement a min-heap. - * @return number of array elements - * @note You must not mess up the array with other non-heap related functions + * \return number of array elements + * \note You must not mess up the array with other non-heap related functions * to keep the heap property. */ HAWK_EXPORT hawk_oow_t hawk_arr_pushheap ( @@ -411,7 +411,7 @@ HAWK_EXPORT hawk_oow_t hawk_arr_pushheap ( * The hawk_arr_popheap() function deletes data at position 0 while keeping * the largest data at positon 0. It is a utiltiy funtion to implement a binary * max-heap over an array. - * @note You must not mess up the array with other non-heap related functions + * \note You must not mess up the array with other non-heap related functions * to keep the heap property. */ HAWK_EXPORT void hawk_arr_popheap ( diff --git a/lib/hawk-cmn.h b/lib/hawk-cmn.h index 70fe0c21..57b7fe8f 100644 --- a/lib/hawk-cmn.h +++ b/lib/hawk-cmn.h @@ -25,6 +25,10 @@ #ifndef _HAWK_CMN_H_ #define _HAWK_CMN_H_ +/** \file + * This file defines common data types and macros. + */ + /* WARNING: NEVER CHANGE/DELETE THE FOLLOWING HAWK_HAVE_CFG_H DEFINITION. * IT IS USED FOR DEPLOYMENT BY MAKEFILE.AM */ /*#define HAWK_HAVE_CFG_H*/ @@ -556,8 +560,17 @@ typedef hawk_uint32_t hawk_ucu_t; typedef hawk_uint8_t hawk_oob_t; -/* [NOTE] sizeof(hawk_oop_t) must be equal to sizeof(hawk_oow_t) */ +/** + * The hawk_oow_t type represents an unsigned integer type that is guaranteed + * to be large enough to hold the value of a data pointer. + * + * HAWK_SIZE(hawk_oop_t) must be equal to HAWK_SIZEOF(hawk_oow_t). + */ typedef hawk_uintptr_t hawk_oow_t; + +/** + * The hawk_ooi_t type represents a signed integer type as large as #hawk_oow_t. + */ typedef hawk_intptr_t hawk_ooi_t; #define HAWK_SIZEOF_OOW_T HAWK_SIZEOF_UINTPTR_T #define HAWK_SIZEOF_OOI_T HAWK_SIZEOF_INTPTR_T @@ -746,6 +759,9 @@ struct hawk_ntime_t /*(sizeof(struct { hcl_uint8_t d1; type d2; }) - sizeof(type))*/ #endif +/** + * The HAWK_NULL macro defines a null value. + */ #if defined(__cplusplus) # if (__cplusplus >= 201103L) /* C++11 */ # define HAWK_NULL nullptr @@ -1023,7 +1039,6 @@ enum hawk_errnum_t HAWK_EVALTOCHR, /**< invalid value to convert to a character */ HAWK_EHASHVAL, /**< invalid value to hash */ - HAWK_EARRIDXRANGE, /**< disallowed array index range */ HAWK_EARRIDXMULTI, /**< single-bracketed multidimensional array indices not allowed */ HAWK_ERNEXTBEG, /**< 'next' called from BEGIN block */ @@ -1086,7 +1101,7 @@ enum hawk_errnum_t /* cut errors */ HAWK_CUT_ESELNV, /**< selector not valid */ - HAWK_CUT_EIOFIL, /**< io error with file '${0}'*/ + HAWK_CUT_EIOFIL, /**< io error with file '${0}'*/ /* the number of error numbers, internal use only */ HAWK_NUMERRNUMS @@ -1121,7 +1136,6 @@ typedef hawk_bloc_t hawk_loc_t; typedef hawk_uloc_t hawk_loc_t; #endif - /** * The hawk_errinf_t type defines a placeholder for error information. */ diff --git a/lib/hawk-cut.h b/lib/hawk-cut.h index 71c959b9..9d41a77e 100644 --- a/lib/hawk-cut.h +++ b/lib/hawk-cut.h @@ -29,18 +29,13 @@ #include #include -/** @file +/** \file * This file defines a text cutter utility. * - * @todo HAWK_CUT_ORDEREDSEL - A selector 5,3,1 is ordered to 1,3,5 + * \todo HAWK_CUT_ORDEREDSEL - A selector 5,3,1 is ordered to 1,3,5 */ -/** - * @example cut.c - * This example implements a simple cut utility. - */ - -/** @struct hawk_cut_t +/** \struct hawk_cut_t * The hawk_cut_t type defines a text cutter. The details are hidden as it is * a large complex structure vulnerable to unintended changes. */ @@ -102,7 +97,7 @@ typedef enum hawk_cut_io_cmd_t hawk_cut_io_cmd_t; struct hawk_cut_io_arg_t { void* handle; /**< I/O handle */ - const hawk_ooch_t* path; /**< file path. HAWK_NULL for a console */ + const hawk_ooch_t* path; /**< file path. #HAWK_NULL for a console */ }; typedef struct hawk_cut_io_arg_t hawk_cut_io_arg_t; @@ -151,10 +146,10 @@ struct hawk_cut_iostd_t /** file path with character encoding */ struct { - /** file path to open. #HAWK_NULL or '-' for stdin/stdout. */ + /** file path to open. HAWK_NULL or '-' for stdin/stdout. */ const hawk_ooch_t* path; /** a stream created with the file path is set with this - * cmgr if it is not #HAWK_NULL. */ + * cmgr if it is not HAWK_NULL. */ hawk_cmgr_t* cmgr; } file; @@ -203,14 +198,14 @@ extern "C" { /** * The hawk_cut_open() function creates a text cutter. - * @return A pointer to a text cutter on success, #HAWK_NULL on failure + * \return A pointer to a text cutter on success, HAWK_NULL on failure */ HAWK_EXPORT hawk_cut_t* hawk_cut_open ( hawk_mmgr_t* mmgr, /**< memory manager */ hawk_oow_t xtnsize, /**< extension size in bytes */ hawk_cmgr_t* cmgr, - hawk_errnum_t* errnum + hawk_errnum_t* errnum ); /** @@ -251,7 +246,7 @@ static HAWK_INLINE void hawk_cut_setcmgr (hawk_cut_t* cut, hawk_cmgr_t* cmgr) { /** * The hawk_cut_getoption() function retrieves the current options set in * a text cutter. - * @return 0 or a number OR'ed of #hawk_cut_option_t values + * \return 0 or a number OR'ed of #hawk_cut_option_t values */ HAWK_EXPORT int hawk_cut_getoption ( hawk_cut_t* cut /**< text cutter */ @@ -262,7 +257,7 @@ HAWK_EXPORT int hawk_cut_getoption ( */ HAWK_EXPORT void hawk_cut_setoption ( hawk_cut_t* cut, /**< text cutter */ - int opt /**< 0 or a number OR'ed of #hawk_cut_option_t values */ + int opt /**< 0 or a number OR'ed of #hawk_cut_option_t values */ ); HAWK_EXPORT hawk_errstr_t hawk_cut_geterrstr ( @@ -368,7 +363,7 @@ HAWK_EXPORT void hawk_cut_clear ( /** * The hawk_cut_comp() function compiles a selector into an internal form. - * @return 0 on success, -1 on error + * \return 0 on success, -1 on error */ HAWK_EXPORT int hawk_cut_comp ( hawk_cut_t* cut, /**< text cutter */ @@ -377,7 +372,7 @@ HAWK_EXPORT int hawk_cut_comp ( /** * The hawk_cut_exec() function executes the compiled commands. - * @return 0 on success, -1 on error + * \return 0 on success, -1 on error */ HAWK_EXPORT int hawk_cut_exec ( hawk_cut_t* cut, /**< text cutter */ @@ -425,7 +420,7 @@ HAWK_EXPORT void hawk_cut_freemem ( /** * The hawk_cut_openstd() function creates a text cutter with the default * memory manager and initialized it for other hawk_cut_xxxxstd functions. - * @return pointer to a text cutter on success, QSE_NULL on failure. + * \return pointer to a text cutter on success, #HAWK_NULL on failure. */ HAWK_EXPORT hawk_cut_t* hawk_cut_openstd ( hawk_oow_t xtnsize, /**< extension size in bytes */ @@ -436,7 +431,7 @@ HAWK_EXPORT hawk_cut_t* hawk_cut_openstd ( * The hawk_cut_openstdwithmmgr() function creates a text cutter with a * user-defined memory manager. It is equivalent to hawk_cut_openstd(), * except that you can specify your own memory manager. - * @return pointer to a text cutter on success, QSE_NULL on failure. + * \return pointer to a text cutter on success, #HAWK_NULL on failure. */ HAWK_EXPORT hawk_cut_t* hawk_cut_openstdwithmmgr ( hawk_mmgr_t* mmgr, /**< memory manager */ @@ -456,9 +451,9 @@ HAWK_EXPORT int hawk_cut_compstd ( /** * The hawk_cut_execstd() function executes the compiled script - * over an input file @a infile and an output file @a outfile. - * If @a infile is QSE_NULL, the standard console input is used. - * If @a outfile is QSE_NULL, the standard console output is used.. + * over an input file \a infile and an output file \a outfile. + * If \a infile is #HAWK_NULL, the standard console input is used. + * If \a outfile is #HAWK_NULL, the standard console output is used.. */ HAWK_EXPORT int hawk_cut_execstd ( hawk_cut_t* cut, diff --git a/lib/hawk-htb.h b/lib/hawk-htb.h index 145e5510..db086632 100644 --- a/lib/hawk-htb.h +++ b/lib/hawk-htb.h @@ -27,14 +27,14 @@ #include -/**@file +/** \file * This file provides a hash table encapsulated in the #hawk_htb_t type that * maintains buckets for key/value pairs with the same key hash chained under * the same bucket. Its interface is very close to #hawk_rbt_t. * * This sample code adds a series of keys and values and print them * in the randome order. - * @code + * \code * #include * * static hawk_htb_walk_t walk (hawk_htb_t* htb, hawk_htb_pair_t* pair, void* ctx) @@ -65,7 +65,7 @@ * hawk_close_stdsios (); * return 0; * } - * @endcode + * \endcode */ typedef struct hawk_htb_t hawk_htb_t; @@ -174,8 +174,8 @@ typedef hawk_htb_walk_t (*hawk_htb_walker_t) ( /** * The hawk_htb_cbserter_t type defines a callback function for hawk_htb_cbsert(). * The hawk_htb_cbserter() function calls it to allocate a new pair for the - * key pointed to by @a kptr of the length @a klen and the callback context - * @a ctx. The second parameter @a pair is passed the pointer to the existing + * key pointed to by \a kptr of the length \a klen and the callback context + * \a ctx. The second parameter \a pair is passed the pointer to the existing * pair for the key or #HAWK_NULL in case of no existing key. The callback * must return a pointer to a new or a reallocated pair. When reallocating the * existing pair, this callback must destroy the existing pair and return the @@ -323,12 +323,12 @@ HAWK_EXPORT const hawk_htb_style_t* hawk_get_htb_style ( * bucket and a list of values chained. The initial capacity should be larger * than 0. The load factor should be between 0 and 100 inclusive and the load * factor of 0 disables bucket resizing. If you need extra space associated - * with hash table, you may pass a non-zero value for @a xtnsize. + * with hash table, you may pass a non-zero value for \a xtnsize. * The HAWK_HTB_XTN() macro and the hawk_htb_getxtn() function return the * pointer to the beginning of the extension. - * The @a kscale and @a vscale parameters specify the unit of the key and + * The \a kscale and \a vscale parameters specify the unit of the key and * value size. - * @return #hawk_htb_t pointer on success, #HAWK_NULL on failure. + * \return #hawk_htb_t pointer on success, #HAWK_NULL on failure. */ HAWK_EXPORT hawk_htb_t* hawk_htb_open ( hawk_gem_t* gem, @@ -410,7 +410,7 @@ HAWK_EXPORT hawk_oow_t hawk_htb_getcapa ( * The hawk_htb_search() function searches a hash table to find a pair with a * matching key. It returns the pointer to the pair found. If it fails * to find one, it returns HAWK_NULL. - * @return pointer to the pair with a maching key, + * \return pointer to the pair with a maching key, * or #HAWK_NULL if no match is found. */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_search ( @@ -424,7 +424,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_search ( * matching key. If one is found, it updates the pair. Otherwise, it inserts * a new pair with the key and value given. It returns the pointer to the * pair updated or inserted. - * @return pointer to the updated or inserted pair on success, + * \return pointer to the updated or inserted pair on success, * #HAWK_NULL on failure. */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_upsert ( @@ -439,7 +439,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_upsert ( * The hawk_htb_ensert() function inserts a new pair with the key and the value * given. If there exists a pair with the key given, the function returns * the pair containing the key. - * @return pointer to a pair on success, #HAWK_NULL on failure. + * \return pointer to a pair on success, #HAWK_NULL on failure. */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_ensert ( hawk_htb_t* htb, /**< hash table */ @@ -453,7 +453,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_ensert ( * The hawk_htb_insert() function inserts a new pair with the key and the value * given. If there exists a pair with the key given, the function returns * #HAWK_NULL without channging the value. - * @return pointer to the pair created on success, #HAWK_NULL on failure. + * \return pointer to the pair created on success, #HAWK_NULL on failure. */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_insert ( hawk_htb_t* htb, /**< hash table */ @@ -466,7 +466,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_insert ( /** * The hawk_htb_update() function updates the value of an existing pair * with a matching key. - * @return pointer to the pair on success, #HAWK_NULL on no matching pair + * \return pointer to the pair on success, #HAWK_NULL on no matching pair */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_update ( hawk_htb_t* htb, /**< hash table */ @@ -484,7 +484,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_update ( * a new pair if the key is not found and appends the new value to the * existing value delimited by a comma if the key is found. * - * @code + * \code * #include * * hawk_htb_walk_t print_map_pair (hawk_htb_t* map, hawk_htb_pair_t* pair, void* ctx) @@ -565,7 +565,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_update ( * hawk_close_stdsios (); * return 0; * } - * @endcode + * \endcode */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_cbsert ( hawk_htb_t* htb, /**< hash table */ @@ -577,7 +577,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_cbsert ( /** * The hawk_htb_delete() function deletes a pair with a matching key - * @return 0 on success, -1 on failure + * \return 0 on success, -1 on failure */ HAWK_EXPORT int hawk_htb_delete ( hawk_htb_t* htb, /**< hash table */ @@ -616,7 +616,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_getfirstpair ( /** * The hawk_htb_getnextpair() function returns the pointer to the next pair - * to the current pair @a pair in a hash table. + * to the current pair \a pair in a hash table. */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_getnextpair ( hawk_htb_t* htb, /**< hash table */ @@ -625,14 +625,14 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_getnextpair ( /** * The hawk_htb_allocpair() function allocates a pair for a key and a value - * given. But it does not chain the pair allocated into the hash table @a htb. + * given. But it does not chain the pair allocated into the hash table \a htb. * Use this function at your own risk. * * Take note of he following special behavior when the copier is * #HAWK_HTB_COPIER_INLINE. - * - If @a kptr is #HAWK_NULL, the key space of the size @a klen is reserved but + * - If \a kptr is #HAWK_NULL, the key space of the size \a klen is reserved but * not propagated with any data. - * - If @a vptr is #HAWK_NULL, the value space of the size @a vlen is reserved + * - If \a vptr is #HAWK_NULL, the value space of the size \a vlen is reserved * but not propagated with any data. */ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_allocpair ( @@ -645,7 +645,7 @@ HAWK_EXPORT hawk_htb_pair_t* hawk_htb_allocpair ( /** * The hawk_htb_freepair() function destroys a pair. But it does not detach - * the pair destroyed from the hash table @a htb. Use this function at your + * the pair destroyed from the hash table \a htb. Use this function at your * own risk. */ HAWK_EXPORT void hawk_htb_freepair ( diff --git a/lib/hawk-prv.h b/lib/hawk-prv.h index db1c5c1a..16685024 100644 --- a/lib/hawk-prv.h +++ b/lib/hawk-prv.h @@ -238,7 +238,7 @@ struct hawk_t union { - hawk_oow_t a[7]; + hawk_oow_t a[7]; /**< to access the elements of the #s field as an array */ struct { hawk_oow_t incl; @@ -248,7 +248,7 @@ struct hawk_t hawk_oow_t expr_run; hawk_oow_t rex_build; hawk_oow_t rex_match; - } s; + } s; /**< defines the maximum nesting depths */ } depth; hawk_oow_t rtx_stack_limit; diff --git a/lib/hawk-sed.h b/lib/hawk-sed.h index 31c302f6..a6b1138e 100644 --- a/lib/hawk-sed.h +++ b/lib/hawk-sed.h @@ -29,7 +29,7 @@ #include #include -/** @file +/** \file * This file defines data types and functions to use for creating a custom * stream editor commonly available on many platforms. A stream editor is * a non-interactive text editing tool that reads text from an input stream, @@ -37,15 +37,15 @@ * of editing commands, and writes the pattern space to an output stream. * Typically, the input and output streams are a console or a file. * - * @code + * \code * sed = hawk_sed_open (); * hawk_sed_comp (sed); * hawk_sed_exec (sed); * hawk_sed_close (sed); - * @endcode + * \endcode */ -/** @struct hawk_sed_t +/** \struct hawk_sed_t * The hawk_sed_t type defines a stream editor. The structural details are * hidden as it is a relatively complex data type and fragile to external * changes. To use a stream editor, you typically can: @@ -456,7 +456,7 @@ extern "C" { * hawk_sed_getxtn() function and use it to store arbitrary data associated * with the object. When done, you should destroy the object with the * hawk_sed_close() function to avoid any resource leaks including memory. - * @return pointer to a stream editor on success, HAWK_NULL on failure + * \return pointer to a stream editor on success, HAWK_NULL on failure */ HAWK_EXPORT hawk_sed_t* hawk_sed_open ( hawk_mmgr_t* mmgr, /**< memory manager */ @@ -654,7 +654,7 @@ HAWK_EXPORT void hawk_sed_pushecb ( /** * The hawk_sed_comp() function compiles editing commands into an internal form. - * @return 0 on success, -1 on error + * \return 0 on success, -1 on error */ HAWK_EXPORT int hawk_sed_comp ( hawk_sed_t* sed, /**< stream editor */ @@ -663,7 +663,7 @@ HAWK_EXPORT int hawk_sed_comp ( /** * The hawk_sed_exec() function executes the compiled commands. - * @return 0 on success, -1 on error + * \return 0 on success, -1 on error */ HAWK_EXPORT int hawk_sed_exec ( hawk_sed_t* sed, /**< stream editor */ @@ -696,7 +696,7 @@ HAWK_EXPORT const hawk_ooch_t* hawk_sed_getcompid ( /** * The hawk_sed_setcompid() functions duplicates a string - * pointed to by @a id and stores it internally to identify + * pointed to by \a id and stores it internally to identify * the script currently being compiled. The lid field of the * current command being compiled in the script is set to the * lastest identifer successfully set with this function. @@ -721,7 +721,7 @@ HAWK_EXPORT const hawk_ooch_t* hawk_sed_setcompidwithucstr ( /** * The hawk_sed_getlinnum() function gets the current input line number. - * @return current input line number + * \return current input line number */ HAWK_EXPORT hawk_oow_t hawk_sed_getlinenum ( hawk_sed_t* sed /**< stream editor */ @@ -732,7 +732,7 @@ HAWK_EXPORT hawk_oow_t hawk_sed_getlinenum ( */ HAWK_EXPORT void hawk_sed_setlinenum ( hawk_sed_t* sed, /**< stream editor */ - hawk_oow_t num /**< a line number */ + hawk_oow_t num /**< a line number */ ); /** @@ -751,7 +751,7 @@ HAWK_EXPORT void hawk_sed_getspace ( */ HAWK_EXPORT void* hawk_sed_allocmem ( hawk_sed_t* sed, - hawk_oow_t size + hawk_oow_t size ); /** @@ -760,7 +760,7 @@ HAWK_EXPORT void* hawk_sed_allocmem ( */ HAWK_EXPORT void* hawk_sed_callocmem ( hawk_sed_t* sed, - hawk_oow_t size + hawk_oow_t size ); /** @@ -769,8 +769,8 @@ HAWK_EXPORT void* hawk_sed_callocmem ( */ HAWK_EXPORT void* hawk_sed_reallocmem ( hawk_sed_t* sed, - void* ptr, - hawk_oow_t size + void* ptr, + hawk_oow_t size ); /** @@ -779,7 +779,7 @@ HAWK_EXPORT void* hawk_sed_reallocmem ( */ HAWK_EXPORT void hawk_sed_freemem ( hawk_sed_t* sed, - void* ptr + void* ptr ); /* ------------------------------------------------------------------------ */ diff --git a/lib/hawk-xma.h b/lib/hawk-xma.h index b2dd2326..78621ace 100644 --- a/lib/hawk-xma.h +++ b/lib/hawk-xma.h @@ -25,7 +25,7 @@ #ifndef _HAWK_XMA_H_ #define _HAWK_XMA_H_ -/** @file +/** \file * This file defines an extravagant memory allocator. Why? It may be so. * The memory allocator allows you to maintain memory blocks from a * larger memory chunk allocated with an outer memory allocator. @@ -34,7 +34,7 @@ * * See the example below. Note it omits error handling. * - * @code + * \code * #include * #include * #include @@ -68,14 +68,14 @@ * hawk_xma_close (xma); // destroy the memory allocator * return 0; * } - * @endcode + * \endcode */ #include /*#define HAWK_XMA_ENABLE_STAT*/ #define HAWK_XMA_ENABLE_STAT -/** @struct hawk_xma_t +/** \struct hawk_xma_t * The hawk_xma_t type defines a simple memory allocator over a memory zone. * It can obtain a relatively large zone of memory and manage it. */ @@ -141,11 +141,11 @@ extern "C" { /** * The hawk_xma_open() function creates a memory allocator. It obtains a memory - * zone of the @a zonesize bytes with the memory manager @a mmgr. It also makes - * available the extension area of the @a xtnsize bytes that you can get the + * zone of the \a zonesize bytes with the memory manager \a mmgr. It also makes + * available the extension area of the \a xtnsize bytes that you can get the * pointer to with hawk_xma_getxtn(). * - * @return pointer to a memory allocator on success, #HAWK_NULL on failure + * \return pointer to a memory allocator on success, #HAWK_NULL on failure */ HAWK_EXPORT hawk_xma_t* hawk_xma_open ( hawk_mmgr_t* mmgr, /**< memory manager */ @@ -180,9 +180,9 @@ static HAWK_INLINE void* hawk_xma_getxtn (hawk_xma_t* xma) { return (void*)(xma * The hawk_xma_init() initializes a memory allocator. If you have the hawk_xma_t * structure statically declared or already allocated, you may pass the pointer * to this function instead of calling hawk_xma_open(). It obtains a memory zone - * of @a zonesize bytes with the memory manager @a mmgr. Unlike hawk_xma_open(), + * of \a zonesize bytes with the memory manager \a mmgr. Unlike hawk_xma_open(), * it does not accept the extension size, thus not creating an extention area. - * @return 0 on success, -1 on failure + * \return 0 on success, -1 on failure */ HAWK_EXPORT int hawk_xma_init ( hawk_xma_t* xma, /**< memory allocator */ @@ -200,8 +200,8 @@ HAWK_EXPORT void hawk_xma_fini ( ); /** - * The hawk_xma_alloc() function allocates @a size bytes. - * @return pointer to a memory block on success, #HAWK_NULL on failure + * The hawk_xma_alloc() function allocates \a size bytes. + * \return pointer to a memory block on success, #HAWK_NULL on failure */ HAWK_EXPORT void* hawk_xma_alloc ( hawk_xma_t* xma, /**< memory allocator */ @@ -214,8 +214,8 @@ HAWK_EXPORT void* hawk_xma_calloc ( ); /** - * The hawk_xma_alloc() function resizes the memory block @a b to @a size bytes. - * @return pointer to a resized memory block on success, #HAWK_NULL on failure + * The hawk_xma_alloc() function resizes the memory block \a b to \a size bytes. + * \return pointer to a resized memory block on success, #HAWK_NULL on failure */ HAWK_EXPORT void* hawk_xma_realloc ( hawk_xma_t* xma, /**< memory allocator */ @@ -224,7 +224,7 @@ HAWK_EXPORT void* hawk_xma_realloc ( ); /** - * The hawk_xma_alloc() function frees the memory block @a b. + * The hawk_xma_alloc() function frees the memory block \a b. */ HAWK_EXPORT void hawk_xma_free ( hawk_xma_t* xma, /**< memory allocator */ @@ -233,7 +233,7 @@ HAWK_EXPORT void hawk_xma_free ( /** * The hawk_xma_dump() function dumps the contents of the memory zone - * with the output function @a dumper provided. The debug build shows + * with the output function \a dumper provided. The debug build shows * more statistical counters. */ HAWK_EXPORT void hawk_xma_dump ( diff --git a/lib/hawk.h b/lib/hawk.h index 1483b788..406e4b72 100644 --- a/lib/hawk.h +++ b/lib/hawk.h @@ -58,14 +58,13 @@ * hawk_rtx_t* rtx; * hawk_sio_cbs_t sio; // need to initialize it with callback functions * hawk_rio_cbs_t rio; // need to initialize it with callback functions - * - * hawk = hawk_open(mmgr, 0, prm); // create an interpreter + * hawk = hawk_open(mmgr, 0, hawk_get_cmgr_by_id(HAWK_CMGR_UTF8), prm, HAWK_NULL); // create an interpreter * hawk_parse(hawk, &sio); // parse a script * rtx = hawk_rtx_open(hawk, 0, &rio); // create a runtime context * retv = hawk_rtx_loop(rtx); // run a standard AWK loop - * if (retv) hawk_rtx_refdownval (rtx, retv); // free return value - * hawk_rtx_close (rtx); // destroy the runtime context - * hawk_close (hawk); // destroy the interpreter + * if (retv) hawk_rtx_refdownval(rtx, retv); // free return value + * hawk_rtx_close(rtx); // destroy the runtime context + * hawk_close(hawk); // destroy the interpreter * \endcode * * It provides an interface to change the conventional behavior of the @@ -1550,10 +1549,11 @@ extern "C" { * { * hawk_mmgr_t mmgr; * hawk_prm_t prm; - * return hawk_open ( + * return hawk_open( * &mmgr, // NOT OK because the contents of mmgr is * // invalidated when dummy() returns. * 0, + * hawk_get_cmgr_by_id(HAWK_CMGR_UTF8), * &prm, // OK * HAWK_NULL * ); @@ -1961,7 +1961,10 @@ HAWK_EXPORT int hawk_parse ( hawk_sio_cbs_t* sio /**< source script I/O handler */ ); - +/** + * The hawk_isvalidident() function determines if a given string is + * a valid identifier. + */ HAWK_EXPORT int hawk_isvalidident ( hawk_t* hawk, const hawk_ooch_t* str @@ -2237,7 +2240,6 @@ HAWK_EXPORT int hawk_concatoochartosbuf ( /* ----------------------------------------------------------------------- */ - /** * The hawk_rtx_open() creates a runtime context associated with \a hawk. * It also allocates an extra memory block as large as the \a xtn bytes.