From: Matt Birkholz Date: Sat, 23 Dec 2017 18:06:56 +0000 (-0700) Subject: gdbm plugin: Add a manual, a translation of the gdbm texinfo manual. X-Git-Tag: mit-scheme-pucked-9.2.12~14^2 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=c982f80355a653f5b43a3d3ccef9d2fbb6cdd8b0;p=mit-scheme.git gdbm plugin: Add a manual, a translation of the gdbm texinfo manual. And take advantage of new Unicode string support in the FFI. --- diff --git a/src/gdbm/Makefile.am b/src/gdbm/Makefile.am index a8625dd2c..c12960e82 100644 --- a/src/gdbm/Makefile.am +++ b/src/gdbm/Makefile.am @@ -41,8 +41,8 @@ binaries = @MIT_SCHEME_BCIs@ @MIT_SCHEME_COMs@ scmlib_sub_DATA = $(sources) $(binaries) scmlib_sub_DATA += make.scm @MIT_SCHEME_PKD@ -#info_TEXINFOS = mit-scheme-gdbm.texi -#AM_MAKEINFOHTMLFLAGS = --no-split +info_TEXINFOS = mit-scheme-gdbm.texi +AM_MAKEINFOHTMLFLAGS = --no-split AM_CPPFLAGS = -I@MIT_SCHEME_INCLUDEDIR@ AM_CFLAGS = @MIT_CFLAGS@ diff --git a/src/gdbm/NEWS b/src/gdbm/NEWS index f0bb04453..436e8e1d4 100644 --- a/src/gdbm/NEWS +++ b/src/gdbm/NEWS @@ -22,6 +22,12 @@ along with MIT/GNU Scheme; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. +mit-scheme-gdbm 0.3 - Matt Birkholz, 2017-12-23 +=============================================== + +Use new FFI Unicode support. Include the gdbm manual, translated into +Scheme. + mit-scheme-gdbm 0.2 - Matt Birkholz, 2017-05-18 =============================================== diff --git a/src/gdbm/gdbm.scm b/src/gdbm/gdbm.scm index 26062f526..f806cd73e 100644 --- a/src/gdbm/gdbm.scm +++ b/src/gdbm/gdbm.scm @@ -352,18 +352,24 @@ USA. (if (alien-null? data) #f (let* ((size (C-> args "gdbm_args key dsize")) - (string ((ucode-primitive string-allocate 1) size))) - (c-peek-bytes data 0 size string 0) - string)))) + (bytes ((ucode-primitive c-peek-csubstring 3) data 0 size))) + (if (string? bytes) + bytes + (let ((s (utf8->string bytes))) + (outf-error ";got a utf8 key: "s"\n") + s)))))) (define (gdbf-args-get-content args) (let ((data (C-> args "gdbm_args content dptr"))) (if (alien-null? data) #f (let* ((size (C-> args "gdbm_args content dsize")) - (string ((ucode-primitive string-allocate 1) size))) - (c-peek-bytes data 0 size string 0) - string)))) + (bytes ((ucode-primitive c-peek-csubstring 3) data 0 size))) + (if (string? bytes) + bytes + (let ((s (utf8->string bytes))) + (outf-error ";got utf8 content: "s"\n") + s)))))) (define open-gdbfs '()) (define open-gdbfs-mutex) diff --git a/src/gdbm/make.scm b/src/gdbm/make.scm index 75f71ebbf..f942ccc55 100644 --- a/src/gdbm/make.scm +++ b/src/gdbm/make.scm @@ -6,4 +6,4 @@ (lambda () (load-package-set "gdbm"))) -(add-subsystem-identification! "GDBM2" '(0 2)) \ No newline at end of file +(add-subsystem-identification! "GDBM2" '(0 3)) \ No newline at end of file diff --git a/src/gdbm/mit-scheme-gdbm.texi b/src/gdbm/mit-scheme-gdbm.texi new file mode 100644 index 000000000..f6a58eacd --- /dev/null +++ b/src/gdbm/mit-scheme-gdbm.texi @@ -0,0 +1,434 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header +@setfilename mit-scheme-gdbm.info +@include version.texi +@set SCMVERS 9.2.1 +@settitle MIT/GNU Scheme GDBM Plugin Manual +@comment %**end of header + +@copying +This manual documents MIT/GNU Scheme GDBM @value{VERSION}. + +Copyright @copyright{} 2017 Matthew Birkholz +Copyright @copyright{} 1993-99 Free Software Foundation, Inc. + +@quotation +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end quotation +@end copying + +@dircategory Programming Languages +@direntry +* MIT/GNU Scheme GDBM: (mit-scheme-gdbm). + GNU database manager plugin +@end direntry + +@titlepage +@title MIT/GNU Scheme GDBM Plugin Manual +@subtitle a GNU database manager plugin (version @value{VERSION}) +@subtitle for MIT/GNU Scheme version @value{SCMVERS} +@subtitle @value{UPDATED} +@author by Matt Birkholz +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnottex +@node Top +@top GDBM Plugin Manual + +@insertcopying +@end ifnottex + +@menu +* Introduction:: + +Functions: + +* List:: The exported bindings. +* Open:: Opening the database. +* Close:: Closing the database. +* Store:: Inserting and replacing records in the database. +* Fetch:: Searching records in the database. +* Delete:: Removing records from the database. +* Sequential:: Sequential access to records. +* Reorganization:: Database reorganization. +* Sync:: Insure all writes to disk have competed. +* Options:: Setting internal options. +@end menu + + +@node Introduction +@chapter Introduction to GNU dbm. + +This plugin is a dynamically loadable wrapper for the GNU dbm +(DataBase Management) C library. This manual is a derivative of +Edition 1.5 of the @cite{GNU dbm Manual}, for library version +1.8.3, last updated October 15, 2002. + +GNU dbm (gdbm) is a library of database functions that +use extendible hashing; it works similarly to the standard UNIX dbm +functions. +The basic use of gdbm is to store key/data pairs in a data file. +Each key must be unique and each key is paired with only one data item. +The keys can not be directly accessed in sorted order. + +The key/data pairs are stored in a gdbm disk file, called a gdbm +database. A program must connect to a gdbm database to be able +manipulate the keys and data contained in it. Gdbm allows Scheme to +connect to multiple databases at the same time. When Scheme connects +to a gdbm database, the connection is designated as a @dfn{reader} or +a @dfn{writer}. A gdbm database may be connected to at most one +writer at a time. However, many readers may connect to the database +simultaneously. Readers and writers may not connect to the database +at the same time. + +Each connection is encapsulated in a Scheme @code{gdbf} structure +which should be used by one Scheme thread at a time. A mutex is used +to block any thread attempting to access the database while an +operation is in progress. + + +@node List +@chapter The exported bindings. + +The following is a quick list of the procedures provided by the plugin. + +@example + gdbm-open + gdbm-close + gdbm-store + gdbm-fetch + gdbm-delete + gdbm-firstkey + gdbm-nextkey + gdbm-reorganize + gdbm-sync + gdbm-exists? + gdbm-setopt +@end example + +Neither @code{gdbm_errno} nor @code{gdbm_strerror} are exposed because +the plugin automatically tests and calls them to detect errors and +convert codes into strings. @code{gdbm_fdesc} is also not exposed, +treated as an implementation detail the plugin should probably hide, +used by tricky code that cooperates with multiple file locking +libraries. + +There is one global variable, @code{gdbm-version}, which is +initialized from the library's @code{gdbm_version} string. + +And several constants: +@example + gdbm_cachesize + gdbm_fast + gdbm_insert + gdbm_newdb + gdbm_reader + gdbm_replace + gdbm_wrcreat + gdbm_writer +@end example + +You can load these bindings into your global environment with the +following expresson. +@smallexample + (load-option 'gdbm) +@end smallexample + +And you can include these bindings in your package description +(@file{.pkg}) file with the following expression. +@smallexample + (global-definitions gdbm/) +@end smallexample + + +@node Open +@chapter Opening the database. + +Connect to the file. If the file has a size of zero bytes, a file +initialization procedure is performed, setting up the initial structure in the +file. + +The procedure for opening a gdbm file is: + +@deffn Procedure gdbm-open name block-size flags mode +The parameters are: + +@table @var +@item name +The name of the file (the complete name, gdbm does not append any +characters to this name). +@item block-size +It is used during initialization to determine the size of various constructs. It +is the size of a single transfer from disk to memory. This parameter is ignored +if the file has been previously initialized. The minimum size is 512. +If the value is less than 512, the file system blocksize is used, otherwise the +value of @var{block-size} is used. +@item flags +If @var{flags} is @code{gdbm_reader}, the user wants to just read the +database and any call to @code{gdbm-store} or @code{gdbm-delete} will fail. +Many readers can access the database at the same time. If @var{flags} is +@code{gdbm_writer}, the user wants both read and write access to the database +and requires exclusive access. If @var{flags} is @code{gdbm_wrcreat}, the +user wants both read and write access to the database and if the database does +not exist, create a new one. If @var{flags} is @code{gdbm_newdb}, the +user want a new database created, regardless of whether one existed, and wants +read and write access to the new database. The following may also be logically +or'd into the database flags: @code{gdbm_sync}, which causes all database operations +to be synchronized to the disk, and @code{gdbm_nolock}, which prevents the library +from performing any locking on the database file. @code{gdbm_fast} is +now obsolete, since gdbm defaults to no-sync mode. +@item mode +File mode (see chmod(2) and open(2) if the file is created). +@end table + +The return value is the object needed by all other procedures to +access that gdbm file. +@end deffn + + +@node Close +@chapter Closing the database. + +It is important that every file opened is also closed. This is needed to +update the reader/writer count on the file. Scheme will do this +automatically if an open gdbm object is garbage collected, but you can +close the file immediately with the @code{gdbm-close} procedure. + +@deffn Procedure gdbm-close dbf +The parameter is: + +@table @var +@item dbf +The object returned by @code{gdbm-open}. +@end table + +Closes the gdbm file and frees all memory associated with @var{dbf}. +@end deffn + + +@node Store +@chapter Inserting and replacing records in the database. + +The procedure @code{gdbm-store} inserts or replaces records in the database. + +@deffn Procedure gdbm-store dbf key content flag +The parameters are: + +@table @var +@item dbf +The object returned by @code{gdbm-open}. +@item key +A non-empty string, converted to utf-8 bytes for lookup in the database. +@item content +Another non-empty string, the content to be stored in the database file, also +converted to utf-8. +@item flag +The action to take when @var{key} is already in the database. The value +of @code{gdbm_replace} indicates that the old content should be replaced +by @var{content}. The value of @code{gdbm_insert} indicates that +@code{#f} should be returned and no action taken if @var{key} already +exists. +@end table + +The values returned are: + +@table @code +@item #t +Success. @var{content} is keyed by @var{key}. The file on disk is updated +to reflect the structure of the new database before returning from this +procedure. +@item #f +The item was not stored because @var{flag} was @code{gdbm_insert} and +@var{key} was already in the database. +@end table + +An error is signaled if the caller is not a writer. + +If you store content for a key that is already in the database, +gdbm replaces the old content with the new content if called with +@code{gdbm_replace}. You do not get two content items for the same key and you do +not get an error from @code{gdbm-store}. + +The size in gdbm is not restricted like dbm or ndbm. Your +content can be as large as you want. +@end deffn + + +@node Fetch +@chapter Searching for records in the database. + +Read content associated with a key. + +@deffn Procedure gdbm-fetch dbf key +The parameters are: + +@table @var +@item dbf +The object returned by @code{gdbm-open}. +@item key +A non-empty string, converted to utf-8 bytes for lookup in the database. +@end table + +The return value is a string created from the utf-8 bytes found in the +database, or @code{#f} if no content was found. +@end deffn + +You may also search for a particular key without retrieving it, using: + +@deffn Procedure gdbm-exists? dbf key +The parameters are: + +@table @var +@item dbf +The pointer returned by @code{gdbm-open}. +@item key +A non-empty string, converted to utf-8 bytes for lookup in the database. +@end table + +Unlike @code{gdbm-fetch} this procedure does not read any content and +simply returns true or false depending on whether @var{key} exists. +@end deffn + + +@node Delete +@chapter Removing records from the database. + +To remove some content from the database: + +@deffn Procedure gdbm-delete dbg key +The parameters are: + +@table @var +@item dbf +The object returned by @code{gdbm-open}. +@item key +A non-empty string, converted to utf-8 bytes for lookup in the database. +@end table + +The return value is @code{#f} if the item is not present or the requester is a reader. +The return value is @code{#t} if there was a successful delete. + +The keyed content and the key are removed from the database. The file +on disk is updated to reflect the structure of the new database before +returning from this procedure. +@end deffn + + +@node Sequential +@chapter Sequential access to records. + +The next two functions allow for accessing all content in a database +@var{dbf}. This access is not key sequential, but it is guaranteed to +visit every key in the database once. (The order has to do with the +hash values.) + +@deffn Procedure gdbm-firstkey dbf +Starts the visit of all keys in the database @var{dbf}. +Returns the first key to visit, converting its utf-8 bytes to a string. +If there are no keys, returns @code{#f}. +@end deffn + +@deffn Procedure gdbm-nextkey dbf key +Returns the key to visit after @var{key}, converting its utf-8 bytes +to a string. +If there are no more keys, returns @code{#f}. +@end deffn + +These functions were intended to visit the database in read-only algorithms, +for instance, to validate the database or similar operations. + +Visiting keys traverses a hash table which writers may re-arrange. +The original key order is @emph{not} guaranteed to +remain unchanged in all instances. It is possible that some key will not be +visited if the database is changed while traversing the table. + + +@node Reorganization +@chapter Database reorganization. + +The following procedure should be used very seldom. + +@deffn Procedure gdbm-reorganize dbf +If you have made a lot of deletions and would like to shrink the space +used by the gdbm file, this function will reorganize the database. +Gdbm will not shorten a gdbm file (will not reuse deleted space) +until this procedure is called. + +The reorganization requires creating a new file and inserting all the elements +in the old file @code{dbf} into the new file. The new file is then renamed to +the same name as the old file and @code{dbf} is updated to contain all the +correct information about the new file. +@end deffn + +@node Sync +@chapter Database Synchronization + +Unless you opened your database with the @code{gdbm_sync} flag, gdbm does not +wait for writes to be flushed to the disk. This allows +faster writing of databases at the risk of having a corrupted database if +Scheme terminates in an abnormal fashion. The following function +allows the programmer to flush all changes to disk. + +@deffn Procedure gdbm-sync dbf +This would usually be called after a complete set of changes have been +made to the database and before some long waiting time. +@code{Gdbm-close} always flushes any changes to disk. +@end deffn + + +@node Options +@chapter Seting options. + +Gdbm supports the ability to set certain options on an already +open database. + +@deffn Procedure gdbm-setopt dbf option value +The parameters are: + +@table @var +@item dbf +The pointer returned by @code{gdbm-open}. +@item option +The option to be set, the value of @code{gdbm_cachesize} or +@code{gdbm_syncmode}. +@item value +The value to be set, an integer. +@end table + +If @var{option} is @code{gdbm_cachesize} the size of the internal +bucket cache is set to the given integer. This option may only be set +once on a database, and is set to 100 by default when the database is +first accessed. + +If @var{option} is @code{gdbm_syncmode} file system synchronization is +turned on or off. By default it is off. @var{Value} should @code{1} +to turn it on, or @code{0} to turn it off. +@end deffn + +The obsolete and experimental options @code{GDBM_FASTMODE}, +@code{GDBM_CENTFREE} and @code{GDBM_COALESCEBLKS} are not supported by +this plugin. + +@bye