6.6.7.4 Keyword Procedures

Scheme Procedure: keyword? obj

C Function: scm_keyword_p (obj)

Return #t if the argument obj is a keyword, else #f.

Scheme Procedure: keyword->symbol keyword

C Function: scm_keyword_to_symbol (keyword)

Return the symbol with the same name as keyword.

Scheme Procedure: symbol->keyword symbol

C Function: scm_symbol_to_keyword (symbol)

Return the keyword with the same name as symbol.

C Function: int scm_is_keyword (SCM obj)

Equivalent to scm_is_true (scm_keyword_p (obj)).

C Function: SCM scm_from_locale_keyword (const char *name)

C Function: SCM scm_from_locale_keywordn (const char *name, size_t len)

Equivalent to scm_symbol_to_keyword (scm_from_locale_symbol (name)) and scm_symbol_to_keyword (scm_from_locale_symboln (name, len)), respectively.

Note that these functions should not be used when name is a C string constant, because there is no guarantee that the current locale will match that of the execution character set, used for string and character constants. Most modern C compilers use UTF-8 by default, so in such cases we recommend scm_from_utf8_keyword.

C Function: SCM scm_from_latin1_keyword (const char *name)

C Function: SCM scm_from_utf8_keyword (const char *name)

Equivalent to scm_symbol_to_keyword (scm_from_latin1_symbol (name)) and scm_symbol_to_keyword (scm_from_utf8_symbol (name)), respectively.

C Function: void scm_c_bind_keyword_arguments (const char *subr, SCM rest, scm_t_keyword_arguments_flags flags, SCM keyword1, SCM *argp1, …, SCM keywordN, SCM *argpN, SCM_UNDEFINED)

Extract the specified keyword arguments from rest, which is not modified. If the keyword argument keyword1 is present in rest with an associated value, that value is stored in the variable pointed to by argp1, otherwise the variable is left unchanged. Similarly for the other keywords and argument pointers up to keywordN and argpN. The argument list to scm_c_bind_keyword_arguments must be terminated by SCM_UNDEFINED.

Note that since the variables pointed to by argp1 through argpN are left unchanged if the associated keyword argument is not present, they should be initialized to their default values before calling scm_c_bind_keyword_arguments. Alternatively, you can initialize them to SCM_UNDEFINED before the call, and then use SCM_UNBNDP after the call to see which ones were provided.

If an unrecognized keyword argument is present in rest and flags does not contain SCM_ALLOW_OTHER_KEYS, or if non-keyword arguments are present and flags does not contain SCM_ALLOW_NON_KEYWORD_ARGUMENTS, an exception is raised. subr should be the name of the procedure receiving the keyword arguments, for purposes of error reporting.

For example:

SCM k_delimiter;
SCM k_grammar;
SCM sym_infix;

SCM my_string_join (SCM strings, SCM rest)
{
  SCM delimiter = SCM_UNDEFINED;
  SCM grammar   = sym_infix;

  scm_c_bind_keyword_arguments ("my-string-join", rest, 0,
                                k_delimiter, &delimiter,
                                k_grammar, &grammar,
                                SCM_UNDEFINED);

  if (SCM_UNBNDP (delimiter))
    delimiter = scm_from_utf8_string (" ");

  return scm_string_join (strings, delimiter, grammar);
}

void my_init ()
{
  k_delimiter = scm_from_utf8_keyword ("delimiter");
  k_grammar   = scm_from_utf8_keyword ("grammar");
  sym_infix   = scm_from_utf8_symbol  ("infix");
  scm_c_define_gsubr ("my-string-join", 1, 0, 1, my_string_join);
}