[PATCH, doc RFA] Add guile gdb parameter support

[Ludovic Courtès]

Doug Evans <xdje42@gmail.com> skribis:

> Here is a revised version of guile parameter support.
> I plan to check it in in a few days.

Thanks for incorporating the suggestions!

Just minor comments; the only thing I’m unsure about is the ‘set-func’
protocol (see below.)

> +@node Parameters In Guile
> +@subsubsection Parameters In Guile
> +
> +@cindex parameters in guile
> +@cindex guile parameters
> +@tindex Parameter
> +You can implement new @value{GDBN} parameters using Guile.  A new

@dfn{parameters}

Also, after “Guile”, I would add something like:

  @footnote{Note that @value{GDBN} parameters must not be confused with
  Guile’s parameter objects (@pxref{Parameters,,, guile, GNU Guile
  Reference Manual}).}

> +parameter is defined with the @code{make-parameter} Guile function,
> +and added to @value{GDBN} with the @code{register-parameter!} Guile function.
> +This two-step approach is taken to separate out the side-effect of adding
> +the command to @value{GDBN} from @code{make-parameter}.
> +
> +Parameters are exposed to the user via the @code{set} and
> +@code{show} commands.  @xref{Help}.
> +
> +There are many parameters that already exist and can be set in
> +@value{GDBN}.  Two examples are: @code{set follow-fork} and
> +@code{set charset}.  Setting these parameters influences certain
> +behavior in @value{GDBN}.  Similarly, you can define parameters that
> +can be used to influence behavior in custom Guile scripts and commands.

I would also move the paragraph that starts with “There are many
parameters that already exist” right after the first sentence, which is
where I would expect parameters to be defined.  WDYT?

> +@c TODO line length

Yup.  :-)

> +@deffn {Scheme Procedure} (make-parameter name @r{[}#:command-class command-class@r{]} @r{[}#:parameter-type parameter-type{]} @r{[}#:enum-list enum-list@r{]} @r{[}#:set-func set-func{]} @r{[}#:show-func show-func{]} @r{[}#:doc doc{]} @r{[}#:set-doc set-doc{]} @r{[}#:show-doc show-doc{]} @r{[}#:initial-value initial-value{]})

[...]

> +The argument @var{set-func} is a function of one argument: @var{self} which
> +is the @code{<gdb:parameter>} object representing the parameter.
> +@value{GDBN} will call this function when a @var{parameter}'s value has
> +been changed via the @code{set} API (for example, @kbd{set foo off}).

It would be nicer if ‘set-func’ were passed both the parameter and the
new value, such that it would be its responsibility to validate the
value and set it, but it seems that that’s not how ‘cmd_sfunc_ftype’
callbacks work.

Alternately, parameters could have just a “conversion” function, rather
than a real ‘set’ function, just like SRFI-39 parameters (info "(guile)
Parameters").  That would free users from the need to explicitly call
‘set-parameter-value!’.

Thoughts?

> +/* A GDB parameter.
> +
> +   Note: Parameteres are added to gdb using a two step process:

“Parameters”

[...]

> +/* A helper which computes the list of enum values.
> +   Throw's an exception if there's a problem with the values.

“Throws”

Maybe a more descriptive first sentence could be “Return an array of
strings corresponding to the value enum values for ENUM_VALUES_SCM.”?

[...]

> +/* Subroutine of pascm_set_value, pascm_show_value to simplify them.

‘pascm_set_value’ now has a different name.

> +gdb_test_multiline "restricted gdb parameter" \
> +    "guile" "" \
> +    "(register-parameter! (make-parameter \"test-restricted-param\"" "" \
> +    "   #:command-class COMMAND_DATA" "" \
> +    "   #:parameter-type PARAM_ZINTEGER" "" \
> +    "   #:set-func (lambda (self)" "" \
> +    "      (let ((value (parameter-value self)))" "" \
> +    "        (if (and (>= value 0) (<= value 10))" "" \
> +    "            \"\"" "" \
> +    "            (begin" "" \
> +    "              (set-parameter-value! self (object-property self 'value))" "" \
> +    "              \"Error: Range of parameter is 0-10.\"))))" "" \
> +    "   #:show-func (lambda (self value)" "" \
> +    "      (format #f \"The value of the restricted parameter is ~a.\" value))" "" \
> +    "   #:initial-value (lambda (self)" "" \
> +    "      (set-object-property! self 'value 2)" "" \
> +    "      2)))" "" \
> +    "end"

This example is what makes me think that current ‘set-func’ callbacks
are inconvenient.

Ludo’.