From: Nick Bowler Date: Fri, 28 Jul 2023 06:04:52 +0000 (-0400) Subject: Expand some sections of the libcdecl manual. X-Git-Tag: v1.3~88 X-Git-Url: https://git.draconx.ca/gitweb/cdecl99.git/commitdiff_plain/bc35d987289cb3815a2b59d99c05034cc13a8f40 Expand some sections of the libcdecl manual. - Clarify that the memory management details wrt. cdecl_parse_decl and cdecl_parse_english are unspecified. - Add more detail to the description of cdecl_explain and cdecl_declare. - Clarify that it is allowed to pass a 'struct cdecl' with a NULL specifiers list to cdecl_declare. --- diff --git a/doc/libcdecl.3 b/doc/libcdecl.3 index 74ce280..0d17d2b 100644 --- a/doc/libcdecl.3 +++ b/doc/libcdecl.3 @@ -1,4 +1,4 @@ -.Dd March 13, 2021 +.Dd July 27, 2023 .Os cdecl99 .Dt LIBCDECL \&3 "Cdecl99 Developer's Manual" .Sh NAME @@ -11,8 +11,8 @@ .Fd struct cdecl *cdecl_parse_english(const char *english); .Fd void cdecl_free(struct cdecl *decl); .Pp -.Fd size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl); .Fd size_t cdecl_declare(char *buf, size_t n, struct cdecl *decl); +.Fd size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl); .Pp .Fd const struct cdecl_error *cdecl_get_error(void); .Pp @@ -338,41 +338,71 @@ from calling .Fn cdecl_get_error is unspecified. .Sh PARSING DECLARATIONS -To parse a declaration, the function -.Pp -.Fd struct cdecl *cdecl_parse_decl(const char *declstr); +The functions .Pp -can be used. -The provided string is parsed as a C declaration. -If successful, this function returns a pointer to an abstract syntax tree -representing the declaration. -If the parse fails for any reason, the function returns NULL. +.Fd struct cdecl *cdecl_parse_decl(const char *decl); +.Fd struct cdecl *cdecl_parse_english(const char *english); .Pp -Similarly, English declarations can be parsed by using the function +parse a string into an abstract syntax tree representing the declaration. +The +.Fn cdecl_parse_decl +function interprets the string as C declaration syntax, while +.Fn cdecl_parse_english +uses the English declaration syntax. +If successful, a pointer to the abstract syntax tree representing the +declaration is returned. +If the parse fails for any reason, the function returns NULL, and +.Fn cdecl_get_error +may be used to retrieve the reason for failure. .Pp -.Fd struct cdecl *cdecl_parse_english(const char *english); +The manner in which memory is allocated by these functions for the returned +tree structure is unspecified. +In particular, multiple nodes may share memory or may be implemented as +read-only static allocations. +Thus, the caller should not directly modify any part of the returned structure, +as the results may be unexpected. +A copy should be made if modifications are required. .Pp -When the AST is no longer needed, it must be freed by passing it to the +When the structure returned by either parsing function is no longer needed, the function .Pp .Fd void cdecl_free(struct cdecl *decl); +.Pp +may be used to release all memory allocations associated with that parse tree. .Sh RENDERING DECLARATIONS -After parsing, the abstract syntax tree can be rendered to a string for output. -Use the function +An abstract syntax tree (which may be the result of calling one of the parsing +functions or constructed explicitly by the program) can be rendered to a string +for output. +The functions .Pp +.Fd size_t cdecl_declare(char *buf, size_t n, struct cdecl *decl); .Fd size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl); .Pp -to format the AST pointed to by +perform this rendering. +The +.Fa cdecl_declare +function produces output in C declaration syntax, while the +.Fa cdecl_explain +function produces output in the English declaration syntax. +.Pp +Only one top-level full declarator is rendered by each call; that is, these +functions do not traverse the +.Fa decl +linked list at the top level. +The caller can traverse this list to render multiple declarators. +In order to assist with generating C declaration syntax, as a special case, +when calling +.Fn cdecl_declare +the +.Va specifiers +member of the .Fa decl -into something resembling English. -At most one full declarator is rendered in this way; for declarations with more -than one full declarator, this function should be called on each -.Dv struct cdecl -in the singly-linked list. -.Pp -In a manner similar to that of -.Xr snprintf 3 , -at most +structure may be a null pointer. +In this case, only the declarator is rendered. +.Pp +The string is output in a manner similar to that of +.Xr snprintf 3 . +At most .Fa n bytes, including the '\\0' terminator, are written to .Fa buf . @@ -381,27 +411,21 @@ If is zero, it is acceptable for .Fa buf to be a null pointer. -Regardless, the function returns the number of characters that would be written -to +.Pp +The number of characters that would be written to .Fa buf if .Fa n -were long enough, not including the '\\0' terminator. -Thus, the entire string was written if a value less than +were large enough is returned, not including the '\\0' terminator. +Hence the entire string was written if the returned value is less than +.Fa n . +If .Fa n -is returned. -.Pp -Similarly, the function -.Pp -.Fd size_t cdecl_declare(char *buf, size_t n, struct cdecl *decl); -.Pp -will render the AST pointed to by -.Fa decl -into C code. +is non-zero, the resulting string is '\\0' terminated even if it was truncated. .Sh AUTHORS Nick Bowler .Sh COPYRIGHT -Copyright \(co 2011\(en2012, 2021 Nick Bowler +Copyright \(co 2011\(en2012, 2021, 2023 Nick Bowler .Pp Permission is granted to copy, distribute and/or modify this manual under the terms of the GNU General Public License as published by the Free Software