Re: [PATCH, doc RFA] Add guile gdb parameter support

[ludo at gnu dot org (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â.