futurile/guix-play
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Suggest keeping record type descriptors private.

Browse Source 
* doc/contributing.texi (Data Types and Pattern Matching): Add paragraph
about keeping RTDs private.

Suggested-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
This commit is contained in:
Ludovic Courtès 2023-10-05 16:15:24 +02:00
parent 97927608cb
commit 7b710836a1
No known key found for this signature in database
GPG Key ID: 090B11993D9AEBB5
1 changed files with 11 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/contributing.texi
View File

@ -1308,6 +1308,17 @@ Guile Reference Manual}); pattern matching for records is better done
using @code{match-record} from @code{(guix records)}, which, unlike
@code{match}, verifies field names at macro-expansion time.
When defining a new record type, keep the @dfn{record type descriptor}
(RTD) private (@pxref{Records,,, guile, GNU Guile Reference Manual}, for
more on records and RTDs). As an example, the @code{(guix packages)}
module defines @code{<package>} as the RTD for package records but it
does not export it; instead, it exports a type predicate, a constructor,
and field accessors. Exporting RTDs would make it harder to change the
application binary interface (because code in other modules might be
matching fields by position) and would make it trivial for users to
forge records of that type, bypassing any checks we may have in the
official constructor (such as ``field sanitizers'').
@node Formatting Code
@subsection Formatting Code