diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-16 20:30:07 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-16 20:30:07 +0000 |
commit | 78c8bbc4157d577c291b289602794ecd1ff24c42 (patch) | |
tree | 288be46fb3bd79e6a7bf01ee90a17b6511cd1b99 /doc | |
parent | 979486e1b46a894fc9de2abe6eb8985536a5013c (diff) | |
download | gdbm-78c8bbc4157d577c291b289602794ecd1ff24c42.tar.gz gdbm-78c8bbc4157d577c291b289602794ecd1ff24c42.tar.bz2 |
Provide support for a simplified "define" construct.
* doc/gdbm.texinfo: Document the "define" statement.
* src/datconv.c: Support short and ushort data types.
* src/gdbmtool.c: Don't call checkdb prior to handling
the "hash" command.
* src/gram.y: Support simplified definition construct:
"define key|content type".
Diffstat (limited to 'doc')
-rw-r--r-- | doc/gdbm.texinfo | 140 |
1 files changed, 137 insertions, 3 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo index d5bb7f3..00acc41 100644 --- a/doc/gdbm.texinfo +++ b/doc/gdbm.texinfo | |||
@@ -1957,7 +1957,7 @@ command sets the @samp{delim2} variable to @samp{;} and the | |||
1957 | @samp{confirm} variable to @samp{false}: | 1957 | @samp{confirm} variable to @samp{false}: |
1958 | 1958 | ||
1959 | @example | 1959 | @example |
1960 | srt delim2=";" noconfirm | 1960 | set delim2=";" noconfirm |
1961 | @end example | 1961 | @end example |
1962 | @end deffn | 1962 | @end deffn |
1963 | 1963 | ||
@@ -1965,8 +1965,8 @@ srt delim2=";" noconfirm | |||
1965 | Unsets the listed variables. The effect of unsetting depends on the | 1965 | Unsets the listed variables. The effect of unsetting depends on the |
1966 | variable. Unless explicitly described in the discussion of the | 1966 | variable. Unless explicitly described in the discussion of the |
1967 | variables above, unsetting a boolean variable is equivalent to setting it to | 1967 | variables above, unsetting a boolean variable is equivalent to setting it to |
1968 | @samp{false}. Unsetting a string variable is equivalent to setting it | 1968 | @samp{false}. Unsetting a string variable is equivalent to assigning it |
1969 | to an empty string. | 1969 | an empty string. |
1970 | @end deffn | 1970 | @end deffn |
1971 | 1971 | ||
1972 | @node commands | 1972 | @node commands |
@@ -2125,6 +2125,140 @@ Print the version of @command{gdbm}. | |||
2125 | 2125 | ||
2126 | @node definitions | 2126 | @node definitions |
2127 | @subsection Data Definitions | 2127 | @subsection Data Definitions |
2128 | GDBM databases are able to keep data of any type, both in the key and | ||
2129 | in the content part of a record. Quite often these data are | ||
2130 | structured, i.e. they consist of several fields of various types. | ||
2131 | @command{Gdbmtool} provides a mechanism for handling such kind of | ||
2132 | records. | ||
2133 | |||
2134 | The @code{define} command defines a record structure. The general | ||
2135 | syntax is: | ||
2136 | |||
2137 | @example | ||
2138 | define @var{what} @var{definition} | ||
2139 | @end example | ||
2140 | |||
2141 | @noindent | ||
2142 | where @var{what} is @samp{key} to defining the structure of key data and | ||
2143 | @samp{content} to define the structure of the content records. | ||
2144 | |||
2145 | The @var{definition} can be of two distinct formats. In the simplest | ||
2146 | case it is a single data type. For example, | ||
2147 | |||
2148 | @example | ||
2149 | define content int | ||
2150 | @end example | ||
2151 | |||
2152 | @noindent | ||
2153 | defines content records consisting of a single integer field. | ||
2154 | Supported data types are: | ||
2155 | |||
2156 | @table @asis | ||
2157 | @item char | ||
2158 | Single byte (signed). | ||
2159 | @item short | ||
2160 | Signed short integer. | ||
2161 | @item ushort | ||
2162 | Unsigned short integer. | ||
2163 | @item int | ||
2164 | Signed integer. | ||
2165 | @item unsigned | ||
2166 | @itemx uint | ||
2167 | Unsigned integer. | ||
2168 | @item long | ||
2169 | Signed long integer. | ||
2170 | @item ulong | ||
2171 | Unsigned long integer. | ||
2172 | @item llong | ||
2173 | Signed long long integer. | ||
2174 | @item ullong | ||
2175 | Unsigned long long integer. | ||
2176 | @item float | ||
2177 | A float. | ||
2178 | @item double | ||
2179 | A double. | ||
2180 | @item string | ||
2181 | Null-terminated string, trailing null being part of the string. | ||
2182 | @item zstring | ||
2183 | A string of characters without the terminating null. | ||
2184 | @end table | ||
2185 | |||
2186 | All numeric data types (integer as well as floating point) have the | ||
2187 | same respective widths as in C language on the host where the database | ||
2188 | file resides. | ||
2189 | |||
2190 | The @samp{string} and @samp{zstring} are special. Both define a | ||
2191 | string of bytes, similar to @samp{char x[]} in C. The former | ||
2192 | defines a null-terminated string, the latter - a string without null | ||
2193 | terminator. This makes difference when the string is the only part of | ||
2194 | datum. Consider the following two definitions: | ||
2195 | |||
2196 | @enumerate 1 | ||
2197 | @item @code{define key string} | ||
2198 | @item @code{define key zstring} | ||
2199 | @end enumerate | ||
2200 | |||
2201 | @noindent | ||
2202 | Now, suppose we want to store the string "ab" in the key. Using the | ||
2203 | definition (1), the @code{dptr} member of GDBM @code{datum} will | ||
2204 | contain three bytes: @samp{a}, @samp{b}, and ASCII 0. The | ||
2205 | @code{dsize} member will have the value 3. Using the definition (2), | ||
2206 | the @code{dptr} member will contain two bytes: @samp{a} and @samp{b}, | ||
2207 | and the @code{dsize} member will have the value 2. | ||
2208 | |||
2209 | The second form of the @code{define} statement is similar to the C | ||
2210 | @code{struct} statement and allows for defining structural data. In | ||
2211 | this form, the @var{definition} part is a comma-separated list of data | ||
2212 | types and variables enclosed in curly braces. In contrast to the | ||
2213 | rest of @command{gdbm} commands, this command is inherently | ||
2214 | multiline and is terminated with the closing curly brace. For | ||
2215 | example: | ||
2216 | |||
2217 | @example | ||
2218 | define content @{ | ||
2219 | int status, | ||
2220 | pad 8, | ||
2221 | char id[3], | ||
2222 | string name | ||
2223 | @} | ||
2224 | @end example | ||
2225 | |||
2226 | @noindent | ||
2227 | This defines a structure consisting of three members: an integer | ||
2228 | @code{status}, an array of 8 bytes @code{id}, and a null-terminated | ||
2229 | string @code{name}. Notice the @code{pad} statement: it allows to | ||
2230 | introduce padding between structure members. Another useful statement | ||
2231 | is @code{offset}: it specifies that the member following it begins at | ||
2232 | the given offset in the structure. Assuming the size of @code{int} is | ||
2233 | 8 bytes, the above definition can also be written as | ||
2234 | |||
2235 | @example | ||
2236 | define content @{ | ||
2237 | int status, | ||
2238 | offset 16, | ||
2239 | char id[3], | ||
2240 | string name | ||
2241 | @} | ||
2242 | @end example | ||
2243 | |||
2244 | When displaying the structured data, @command{gdbmtool} precedes each | ||
2245 | value with the corresponding field name and delimits parts of the | ||
2246 | structure with the string defined in the @samp{delim1} variable | ||
2247 | (@pxref{variables}). Array elements are delimited using the string from | ||
2248 | @samp{delim2}. For example: | ||
2249 | |||
2250 | @example | ||
2251 | gdbmtool> fetch foo | ||
2252 | status=2,id=@{ a, u, x @},name="quux" | ||
2253 | @end example | ||
2254 | |||
2255 | To supply a structured datum as an argument to a @command{gdbmtool} | ||
2256 | command, use the same notation, but without field names, e.g.: | ||
2257 | |||
2258 | @example | ||
2259 | gdbmtool> hash @{ 2, @{a,u,x@}, "quux" @} | ||
2260 | hash value = 13089969. | ||
2261 | @end example | ||
2128 | 2262 | ||
2129 | @node startup files | 2263 | @node startup files |
2130 | @subsection Startup Files | 2264 | @subsection Startup Files |