diff options
author | Marius Vollmer <mvo@zagadka.de> | 2004-10-04 18:54:18 +0000 |
---|---|---|
committer | Marius Vollmer <mvo@zagadka.de> | 2004-10-04 18:54:18 +0000 |
commit | 7719ef223450da79b8b8bbe2b50afa469faab93e (patch) | |
tree | 439dcf51ac82202f52ee6edac3db9d26ec1b8d9f | |
parent | 83e1ab6ddf36d2384880f9cb4cf9f78f9c357be6 (diff) | |
download | guile-7719ef223450da79b8b8bbe2b50afa469faab93e.tar.gz |
* api-data.texi: Removed primitive keyword section, updated
keyword docs.
* api-undocumented.texi: Moved keyword dash-symbol docs here.
-rwxr-xr-x | doc/ref/api-data.texi | 88 | ||||
-rw-r--r-- | doc/ref/api-undocumented.texi | 12 |
2 files changed, 34 insertions, 66 deletions
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index a86320870..7da085064 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -4714,7 +4714,6 @@ syntax extension to permit keywords to begin with @code{:} as well as * Coding With Keywords:: How to use keywords. * Keyword Read Syntax:: Read syntax for keywords. * Keyword Procedures:: Procedures for dealing with keywords. -* Keyword Primitives:: The underlying primitive procedures. @end menu @node Why Use Keywords? @@ -4841,13 +4840,13 @@ facilities provided by the @code{(ice-9 optargs)} module, see @node Keyword Read Syntax @subsubsection Keyword Read Syntax -Guile, by default, only recognizes the keyword syntax specified by R5RS. -A token of the form @code{#:NAME}, where @code{NAME} has the same syntax -as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external -representation of the keyword named @code{NAME}. Keyword objects print -using this syntax as well, so values containing keyword objects can be -read back into Guile. When used in an expression, keywords are -self-quoting objects. +Guile, by default, only recognizes a keyword syntax that is compatible +with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the +same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the +external representation of the keyword named @code{NAME}. Keyword +objects print using this syntax as well, so values containing keyword +objects can be read back into Guile. When used in an expression, +keywords are self-quoting objects. If the @code{keyword} read option is set to @code{'prefix}, Guile also recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens @@ -4884,75 +4883,32 @@ ABORT: (unbound-variable) @node Keyword Procedures @subsubsection Keyword Procedures -The following procedures can be used for converting symbols to keywords -and back. - -@deffn {Scheme Procedure} symbol->keyword sym -Return a keyword with the same characters as in @var{sym}. -@end deffn - -@deffn {Scheme Procedure} keyword->symbol kw -Return a symbol with the same characters as in @var{kw}. -@end deffn - - -@node Keyword Primitives -@subsubsection Keyword Primitives - -Internally, a keyword is implemented as something like a tagged symbol, -where the tag identifies the keyword as being self-evaluating, and the -symbol, known as the keyword's @dfn{dash symbol} has the same name as -the keyword name but prefixed by a single dash. For example, the -keyword @code{#:name} has the corresponding dash symbol @code{-name}. - -Most keyword objects are constructed automatically by the reader when it -reads a token beginning with @code{#:}. However, if you need to -construct a keyword object programmatically, you can do so by calling -@code{make-keyword-from-dash-symbol} with the corresponding dash symbol -(as the reader does). The dash symbol for a keyword object can be -retrieved using the @code{keyword-dash-symbol} procedure. - -@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol -@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol) -Make a keyword object from a @var{symbol} that starts with a dash. -For example, - -@example -(make-keyword-from-dash-symbol '-foo) -@result{} #:foo -@end example -@end deffn - @deffn {Scheme Procedure} keyword? obj @deffnx {C Function} scm_keyword_p (obj) Return @code{#t} if the argument @var{obj} is a keyword, else @code{#f}. @end deffn -@deffn {Scheme Procedure} keyword-dash-symbol keyword -@deffnx {C Function} scm_keyword_dash_symbol (keyword) -Return the dash symbol for @var{keyword}. -This is the inverse of @code{make-keyword-from-dash-symbol}. -For example, - -@example -(keyword-dash-symbol #:foo) -@result{} -foo -@end example +@deffn {Scheme Procedure} keyword->symbol keyword +@deffnx {C Function} scm_keyword_to_symbol (keyword) +Return the symbol with the same name as @var{keyword}. @end deffn -@deftypefn {C Function} SCM scm_c_make_keyword (char *@var{str}) -Make a keyword object from a string. For example, +@deffn {Scheme Procedure} symbol->keyword symbol +@deffnx {C Function} scm_symbol_to_keyword (symbol) +Return the keyword with the same name as @var{symbol}. +@end deffn -@example -scm_c_make_keyword ("foo") -@result{} #:foo -@end example -@c -@c FIXME: What can be said about the string argument? Currently it's -@c not used after creation, but should that be documented? +@deftypefn {C Function} int scm_is_keyword (SCM obj) +Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}. @end deftypefn +@deftypefn {C Function} SCM scm_from_locale_keyword (const char *str) +@deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *str, size_t len) +Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol +(@var{str}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln +(@var{str}, @var{len}))}, respectively. +@end deftypefn @node Other Types @subsection ``Functionality-Centric'' Data Types diff --git a/doc/ref/api-undocumented.texi b/doc/ref/api-undocumented.texi index d7507faa5..353e1669e 100644 --- a/doc/ref/api-undocumented.texi +++ b/doc/ref/api-undocumented.texi @@ -843,3 +843,15 @@ Return the value from @var{obj}'s slot with the name @deffnx {C Function} scm_sys_tag_body (body) Internal GOOPS magic---don't use this function! @end deffn + +@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol +@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol) +Make a keyword object from a @var{symbol} that starts with a dash. +@end deffn + +@deffn {Scheme Procedure} keyword-dash-symbol keyword +@deffnx {C Function} scm_keyword_dash_symbol (keyword) +Return the dash symbol for @var{keyword}. +This is the inverse of @code{make-keyword-from-dash-symbol}. +@end deffn + |