* [PATCH v1 02/36] Guile extension language: doc additions
@ 2013-12-24 19:03 Doug Evans
2013-12-25 19:27 ` Eli Zaretskii
0 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2013-12-24 19:03 UTC (permalink / raw)
To: gdb-patches
This patch has the doc additions.
There's still some to be written, but I think it's in good enough shape
to get feedback on.
2013-12-24 Doug Evans <xdje42@gmail.com>
doc/
* Makefile.in (GDB_DOC_FILES): Add guile.texi.
* gdb.texinfo
* guile.texi: New file.
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index 60feae3..4c5023f 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -130,6 +130,7 @@ GDB_DOC_BUILD_INCLUDES = \
GDBvn.texi
GDB_DOC_FILES = \
$(srcdir)/gdb.texinfo \
+ $(srcdir)/guile.texi \
$(GDB_DOC_SOURCE_INCLUDES) \
$(GDB_DOC_BUILD_INCLUDES)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7560152..f1834a0 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -22247,6 +22247,12 @@ These are @value{GDBN} control commands for the auto-loading:
@tab Show setting of @value{GDBN} Python scripts.
@item @xref{info auto-load python-scripts}.
@tab Show state of @value{GDBN} Python scripts.
+@item @xref{set auto-load guile-scripts}.
+@tab Control for @value{GDBN} Guile scripts.
+@item @xref{show auto-load guile-scripts}.
+@tab Show setting of @value{GDBN} Guile scripts.
+@item @xref{info auto-load guile-scripts}.
+@tab Show state of @value{GDBN} Guile scripts.
@item @xref{set auto-load scripts-directory}.
@tab Control for @value{GDBN} auto-loaded scripts location.
@item @xref{show auto-load scripts-directory}.
@@ -22873,7 +22879,9 @@ being debugged.
@menu
* Sequences:: Canned Sequences of @value{GDBN} Commands
* Python:: Extending @value{GDBN} using Python
+* Guile:: Extending @value{GDBN} using Guile
* Auto-loading extensions:: Automatically loading extensions
+* Multiple Extension Languages:: Working with multiple extension languages
* Aliases:: Creating new spellings of existing commands
@end menu
@@ -27868,6 +27876,9 @@ substitute_prompt (``frame: \f,
@end smallexample
@end table
+@c Guile docs live in a separate file.
+@include guile.texi
+
@node Auto-loading extensions
@section Auto-loading extensions
@cindex auto-loading extensions
@@ -27913,6 +27924,8 @@ where @var{ext} is the file extension for the extension language:
GDB's own command language
@item @file{@var{objfile}-gdb.py}
Python
+@item @file{@var{objfile}-gdb.scm}
+Guile
@end table
@var{script-name} is formed by ensuring that the file name of @var{objfile}
@@ -28006,6 +28019,7 @@ for example, this GCC macro for Python scripts.
@end example
@noindent
+For Guile scripts, replace @code{.byte 1} with @code{.byte 3}.
Then one can reference the macro in a header or source file like this:
@example
@@ -28077,6 +28091,26 @@ cumbersome. It may be easier to specify the scripts in the
top of the source tree to the source search path.
@end itemize
+@node Multiple Extension Languages
+@section Multiple Extension Languages
+
+The Guile and Python extension languages do not share any state,
+and generally do not interfere with each other.
+There are some things to be aware of, however.
+
+@subsection Python comes first
+
+Python was @value{GDBN}'s first extension language, and to avoid breaking
+existing behaviour Python comes first. This is generally solved by the
+``first one wins'' principle. @value{GDBN} maintains a list of enabled
+extension languages, and when it makes a call to an extension language,
+(say to pretty-print a value), it tries each in turn until an extension
+language indicates it has performed the request (e.g., has returned the
+pretty-printed form of a value).
+This extends to errors while performing such requests: If an error happens
+while, for example, trying to pretty-print an object then the error is
+reported and any following extension languages are not tried.
+
@node Aliases
@section Creating new spellings of existing commands
@cindex aliases for commands
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
new file mode 100644
index 0000000..0c050d4
--- /dev/null
+++ b/gdb/doc/guile.texi
@@ -0,0 +1,3095 @@
+@node Guile
+@section Extending @value{GDBN} using Guile
+@cindex guile scripting
+@cindex scripting with guile
+
+You can extend @value{GDBN} using the @uref{http://www.gnu.org/software/guile/,
+Guile implementation of the Scheme programming language}.
+This feature is available only if @value{GDBN} was configured using
+@option{--with-guile}.
+
+@menu
+* Guile Introduction:: Introduction to Guile scripting in @value{GDBN}
+* Guile Commands:: Accessing Guile from @value{GDBN}
+* Guile API:: Accessing @value{GDBN} from Guile
+* Guile Auto-loading:: Automatically loading Guile code
+* Guile Modules:: Guile modules provided by @value{GDBN}
+@end menu
+
+@node Guile Introduction
+@subsection Guile Introduction
+
+Guile is an implementation of the Scheme programming language
+and is the GNU project's official extension language.
+
+Guile support in @value{GDBN} follows the Python support in @value{GDBN}
+reasonably closely, so concepts there should carry over.
+However, some things are done differently where it makes sense.
+
+@value{GDBN} requires Guile version 2.0 or greater.
+Older versions are not supported.
+Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
+
+The implementation uses Guile's @code{smob} (small object)
+data type for all @value{GDBN} objects. This allows gluing Guile
+into @value{GDBN} very easily.
+
+@cindex guile directory
+Guile scripts used by @value{GDBN} should be installed in
+@file{@var{data-directory}/guile}, where @var{data-directory} is
+the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
+This directory, known as the @dfn{guile directory},
+is automatically added to the Guile Search Path in order to allow
+the Guile interpreter to locate all scripts installed at this location.
+
+@node Guile Commands
+@subsection Guile Commands
+@cindex guile commands
+@cindex commands to access guile
+
+@value{GDBN} provides two commands for accessing the Guile interpreter:
+
+@table @code
+@kindex guile-interactive
+@kindex gi
+@item guile-interactive
+@itemx gi
+The @code{guile-interactive} command can be used
+to start an interactive Guile prompt. To return to @value{GDBN},
+type @kbd{,q} or the @code{EOF} character (e.g., @kbd{Ctrl-D} on
+an empty prompt). These commands do not take any arguments.
+
+@kindex guile
+@kindex gu
+@item guile @r{[}@var{command}@r{]}
+@itemx gu @r{[}@var{command}@r{]}
+The @code{guile} command can be used to evaluate a Scheme expression.
+
+If given an argument, @value{GDBN} will pass the argument to the Guile
+interpreter for evaluation.
+
+@smallexample
+(@value{GDBP}) guile (display (+ 20 3)) (newline)
+23
+@end smallexample
+
+The result of the Scheme expression is displayed using normal Guile rules.
+
+@smallexample
+(@value{GDBP}) guile (+ 20 3)
+23
+@end smallexample
+
+If you do not provide an argument to @code{guile}, it will act as a
+multi-line command, like @code{define}. In this case, the Guile
+script is made up of subsequent command lines, given after the
+@code{guile} command. This command list is terminated using a line
+containing @code{end}. For example:
+
+@smallexample
+(@value{GDBP}) guile
+>(display 23)
+>(newline)
+>end
+23
+@end smallexample
+@end table
+
+It is also possible to execute a Guile script from the @value{GDBN}
+interpreter:
+
+@table @code
+@item source @file{script-name}
+The script name must end with @samp{.scm} and @value{GDBN} must be configured
+to recognize the script language based on filename extension using
+the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
+
+@item guile (load "script-name")
+This method uses the @code{load} Guile function.
+It takes a string argument that is the name of the script to load.
+See the Guile documentation for a description of this function.
+@end table
+
+@node Guile API
+@subsection Guile API
+@cindex guile api
+@cindex programming in guile
+
+You can get quick online help for @value{GDBN}'s Guile API by issuing
+the command @w{@kbd{help guile}}, or by issuing the command @kbd{,help}
+from an interactive Guile session. Furthermore, most Guile procedures
+provided by @value{GDBN} have doc strings which can be obtained with
+@kbd{,describe @var{procedure-name}} or @kbd{,d @var{procedure-name}}
+from the Guile interactive prompt.
+
+@menu
+* Basic Guile:: Basic Guile Functions
+* Guile Configuration:: Guile configuration variables
+* Guile Exception Handling:: How Guile exceptions are translated
+* Values From Inferior In Guile:: Guile representation of values
+* Arithmetic In Guile:: Arithmetic in Guile
+* Types In Guile:: Guile representation of types
+* Guile Pretty Printing API:: Pretty-printing values with Guile
+* Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer
+* Writing a Guile Pretty-Printer:: Writing a pretty-printer
+* Objfiles In Guile:: Object files in Guile
+* Frames In Guile:: Accessing inferior stack frames from Guile
+* Blocks In Guile:: Accessing blocks from Guile
+* Symbols In Guile:: Guile representation of symbols
+* Symbol Tables In Guile:: Guile representation of symbol tables
+* Breakpoints In Guile:: Manipulating breakpoints using Guile
+* Lazy Strings In Guile:: Guile representation of lazy strings
+* Architectures In Guile:: Guile representation of architectures
+* Disassembly In Guile:: Disassembling instructions from Guile
+* I/O Ports in Guile:: GDB I/O ports
+* Memory Ports in Guile:: Accessing memory through ports and bytevectors
+* Iterators In Guile:: Basic iterator support
+@end menu
+
+@node Basic Guile
+@subsubsection Basic Guile
+
+@cindex guile stdout
+@cindex guile pagination
+At startup, @value{GDBN} overrides Guile's @code{current-output-port} and
+@code{current-error-port} to print using @value{GDBN}'s output-paging streams.
+A Guile program which outputs to one of these streams may have its
+output interrupted by the user (@pxref{Screen Size}). In this
+situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}.
+
+Guile's history mechanism uses the same naming as @value{GDBN}'s,
+namely the user of dollar-variables (e.g., $1, $2, etc.).
+However, the values are independent, @code{$1} in Guile is not the
+same value as @code{$1} in @value{GDBN}.
+
+@value{GDBN} is not thread-safe. If your Guile program uses multiple
+threads, you must be careful to only call @value{GDBN}-specific
+functions in the main @value{GDBN} thread.
+
+Some care must be taken when writing Guile code to run in
+@value{GDBN}. Two things are worth noting in particular:
+
+@itemize @bullet
+@item
+@value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}.
+Guile code must not override these, or even change the options using
+@code{sigaction}. If your program changes the handling of these
+signals, @value{GDBN} will most likely stop working correctly. Note
+that it is unfortunately common for GUI toolkits to install a
+@code{SIGCHLD} handler.
+
+@item
+@value{GDBN} takes care to mark its internal file descriptors as
+close-on-exec. However, this cannot be done in a thread-safe way on
+all platforms. Your Guile programs should be aware of this and
+should both create new file descriptors with the close-on-exec flag
+set and arrange to close unneeded file descriptors before starting a
+child process.
+@end itemize
+
+@cindex guile gdb module
+@value{GDBN} introduces a new Guile module, named @code{gdb}. All
+methods and classes added by @value{GDBN} are placed in this module.
+@value{GDBN} does not automatically @code{import} the @code{gdb} module,
+scripts must do this themselves. There are various options for how to
+import a module, so @value{GDBN} leaves the choice of how the @code{gdb}
+module is imported to the user.
+To simplify interactive use, it is recommended to add one of the following
+to your ~/.gdbinit.
+
+@smallexample
+guile (use-modules (gdb))
+@end smallexample
+
+@smallexample
+guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
+@end smallexample
+
+Which one to choose depends on your preference.
+The second one adds @code{gdb:} as a prefix to all module functions
+and variables.
+
+The rest of this manual assumes the @code{gdb} module has been imported
+without any prefix. See the Guile documentation for @code{use-modules}
+for more information.
+
+Example:
+
+@smallexample
+(gdb) guile (value-type (make-value 1))
+ERROR: Unbound variable: value-type
+Error while executing Scheme code.
+(gdb) guile (use-modules (gdb))
+(gdb) guile (value-type (make-value 1))
+int
+(gdb)
+@end smallexample
+
+The @code{(gdb)} module provides these basic Guile functions.
+
+@c TODO: line length
+@defun execute command @r{[}#:from-tty boolean@r{]}@r{[}#:to-string boolean@r{]}
+Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
+If a @value{GDBN} exception happens while @var{command} runs, it is
+translated as described in
+@ref{Guile Exception Handling,,Guile Exception Handling}.
+
+@var{from-tty} specifies whether @value{GDBN} ought to consider this
+command as having originated from the user invoking it interactively.
+It must be a boolean value. If omitted, it defaults to @code{#f}.
+
+By default, any output produced by @var{command} is sent to
+@value{GDBN}'s standard output. If the @var{to-string} parameter is
+@code{#t}, then output will be collected by @code{gdb.execute} and
+returned as a string. The default is @code{#f}, in which case the
+return value is unspecified. If @var{to-string} is @code{#t}, the
+@value{GDBN} virtual terminal will be temporarily set to unlimited width
+and height, and its pagination will be disabled; @pxref{Screen Size}.
+@end defun
+
+@defun history-ref number
+Return a value from @value{GDBN}'s value history (@pxref{Value
+History}). @var{number} indicates which history element to return.
+If @var{number} is negative, then @value{GDBN} will take its absolute value
+and count backward from the last element (i.e., the most recent element) to
+find the value to return. If @var{number} is zero, then @value{GDBN} will
+return the most recent element. If the element specified by @var{number}
+doesn't exist in the value history, a @code{gdb:error} exception will be
+raised.
+
+If no exception is raised, the return value is always an instance of
+@code{<gdb:value>} (@pxref{Values From Inferior In Guile}).
+
+@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
+@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
+history, nor is the reverse true.
+@end defun
+
+@defun parse-and-eval expression
+Parse @var{expression} as an expression in the current language,
+evaluate it, and return the result as a @code{<gdb:value>}.
+@var{expression} must be a string.
+
+This function is useful when computing values.
+For example, it is the only way to get the value of a
+convenience variable (@pxref{Convenience Vars}) as a @code{<gdb:value>}.
+@end defun
+
+@defun string->argv string
+Convert a string to a list of strings split up according to
+@value{GDBN}'s argv parsing rules.
+@end defun
+
+@node Guile Configuration
+@subsubsection Guile Configuration
+
+@value{GDBN} provides these variables that specify various configuration
+parameters. They are read-only.
+By convention global variables are named @code{*variable*}.
+
+@defun data-directory
+Return a string containing @value{GDBN}'s data directory.
+This directory contains @value{GDBN}'s ancillary files, including
+the Guile modules provided by @value{GDBN}.
+@end defun
+
+@defun gdb-version
+Return a string containing the @value{GDBN} version.
+@end defun
+
+@defun host-config
+Return a string containing the host configuration.
+This is the string passed to @code{--host} when @value{GDBN} was configured.
+@end defun
+
+@defun target-config
+Return a string containing the target configuration.
+This is the string passed to @code{--target} when @value{GDBN} was configured.
+@end defun
+
+@node Guile Exception Handling
+@subsubsection Guile Exception Handling
+@cindex guile exceptions
+@cindex exceptions, guile
+@kindex set guile print-stack
+
+When executing the @code{guile} command, Guile exceptions
+uncaught within the Guile code are translated to calls to the
+@value{GDBN} error-reporting mechanism. If the command that called
+@code{guile} does not handle the error, @value{GDBN} will
+terminate it and report the error according to the setting of
+the @code{guile print-stack} parameter.
+
+The @code{guile print-stack} parameter has three settings:
+
+@table @code
+@item none
+Nothing is printed.
+
+@item message
+An error message is printed containing the Guile exception name,
+the associated value, and the Guile call stack backtrace at the
+point where the exception was raised. Example:
+
+@smallexample
+(@value{GDBP}) guile (display foo)
+ERROR: In procedure memoize-variable-access!:
+ERROR: Unbound variable: foo
+Error while executing Scheme code.
+@end smallexample
+
+@item full
+In addition to an error message a full backtrace is printed.
+
+@smallexample
+(@value{GDBP}) set guile print-stack full
+(@value{GDBP}) guile (display foo)
+Backtrace:
+In ice-9/boot-9.scm:
+ 157: 10 [catch #t #<catch-closure 2c76e20> ...]
+In unknown file:
+ ?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
+In ice-9/boot-9.scm:
+ 157: 8 [catch #t #<catch-closure 2c76d20> ...]
+In unknown file:
+ ?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
+ ?: 6 [call-with-input-string "(display foo)" ...]
+In ice-9/boot-9.scm:
+2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
+In ice-9/eval-string.scm:
+ 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
+ 37: 3 [lp (display foo)]
+In ice-9/eval.scm:
+ 387: 2 [eval # ()]
+ 393: 1 [eval #<memoized foo> ()]
+In unknown file:
+ ?: 0 [memoize-variable-access! #<memoized foo> ...]
+
+ERROR: In procedure memoize-variable-access!:
+ERROR: Unbound variable: foo
+Error while executing Scheme code.
+@end smallexample
+@end table
+
+@value{GDBN} errors that happen in @value{GDBN} commands invoked by
+Guile code are converted to Guile exceptions. The type of the
+Guile exception depends on the error.
+
+Guile procedures provided by @value{GDBN} can throw the standard
+Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}.
+
+User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
+prompt) is translated to a Guile @code{signal} exception with value
+@code{SIGINT}.
+
+@value{GDBN} Guile procedures can also throw these exceptions:
+
+@ftable @code
+@item gdb:error
+This exception is a catch-all for errors generated from within @value{GDBN}.
+
+@item gdb:invalid-object
+This exception is thrown when accessing Guile objects that wrap underlying
+@value{GDBN} objects have become invalid. For example, a
+@code{<gdb:breakpoint>} object becomes invalid if the user deletes it
+from the command line. The object still exists in Guile, but the
+object it represents is gone. Further operations on this breakpoint
+will throw this exception.
+
+@item gdb:memory-error
+This exception is thrown when an operation tried to access invalid
+memory in the inferior.
+
+@item gdb:pp-type-error
+This exception is thrown when a Guile pretty-printer passes a bad object
+to @value{GDBN}.
+@end ftable
+
+The following exception-related procedures are provided by the
+@code{(gdb)} module.
+
+@defun make-exception key args
+Return a @code{<gdb:exception>} object.
+@var{key} and @var{args} are the standard Guile parameters of an exception.
+See Guile documentation for more information.
+@end defun
+
+@defun exception? object
+Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
+@end defun
+
+@defun exception-key exception
+Return the @var{args} field of a @code{<gdb:exception>} object.
+@end defun
+
+@defun exception-args exception
+Return the @var{args} field of a @code{<gdb:exception>} object.
+@end defun
+
+@node Values From Inferior In Guile
+@subsubsection Values From Inferior In Guile
+@cindex values from inferior, in guile
+@cindex guile, working with values from inferior
+
+@tindex @code{<gdb:value>}
+@value{GDBN} provides values it obtains from the inferior program in
+an object of type @code{<gdb:value>}. @value{GDBN} uses this object
+for its internal bookkeeping of the inferior's values, and for
+fetching values when necessary.
+
+@value{GDBN} does not memoize @code{<gdb:value>} objects.
+Therefore @code{eq?} does not work as expected.
+However @code{equal?} does work.
+
+@smallexample
+(gdb) guile (eq? (make-value 1) (make-value 1))
+$1 = #f
+(gdb) guile (equal? (make-value 1) (make-value 1))
+$1 = #t
+@end smallexample
+
+A @code{<gdb:value>} that represents a function can be executed via
+inferior function call with @code{value-call}.
+Any arguments provided to the call must match the function's prototype,
+and must be provided in the order specified by that prototype.
+
+For example, @code{some-val} is a @code{<gdb:value>} instance
+representing a function that takes two integers as arguments. To
+execute this function, call it like so:
+
+@smallexample
+(define result (value-call some-val 10 20))
+@end smallexample
+
+Any values returned from a function call are @code{<gdb:value>} objects.
+
+Note: Unlike Python scripting in @value{GDBN},
+inferior values that are simple scalars cannot be used directly in
+Scheme expressions that are valid for the value's data type.
+For example, @code{(+ (parse-and-eval "int_variable") 2)} does not work.
+And inferior values that are structures or instances of some class cannot
+be accessed using any special syntax, instead @code{value-field} must be used.
+
+The following value-related procedures are provided by the
+@code{(gdb)} module.
+
+@defun value? object
+Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
+@end defun
+
+@defun make-value value @r{[}#:type type@r{]}
+Many Scheme values can be converted directly to a @code{<gdb:value>} via
+with this procedure. If @var{type} is specified, the result is a value
+of this type, and if @var{value} can't be represented with this type
+an exception is thrown. Otherwise the type of the result is determined from
+@var{value} as described below.
+
+The following Scheme objects are accepted for @var{value}:
+
+@table @asis
+@item Scheme boolean
+A Scheme boolean is converted to @var{type} if provided, otherwise
+the boolean type for the current language.
+
+@item Scheme integer
+A Scheme integer is converted to a value of type @var{type} if provided.
+
+If @var{type} is not provided,
+a Scheme integer is converted to the first of a C @code{int},
+@code{unsigned int}, @code{long}, @code{unsigned long},
+@code{long long} or @code{unsigned long long} type
+for the current architecture that can represent the value.
+To force a particular type use
+@code{(make-value @var{value} #:type @var{type})}.
+@xref{Architectures In Guile}, for a list of the builtin
+types for an architecture.
+
+If the Scheme integer cannot be represented as a target integer
+an @code{out-of-range} exception is thrown.
+
+@item Scheme real
+A Scheme real is converted to a value of type @var{type} if provided.
+
+If @var{type} is not provided,
+a Scheme real is converted to the C @code{double} type for the
+current architecture.
+
+@item Scheme string
+A Scheme string is converted to a target string, using the current
+target encoding.
+
+Passing @var{type} is not supported in this case,
+if it is provided a @code{wrong-type-arg} exception is thrown.
+
+@item @code{<gdb:lazy-string>}
+If @var{value} is a @code{<gdb:lazy-string>} object (@pxref{Lazy Strings In
+Guile}), then the @code{lazy-string->value} procedure is called, and
+its result is used.
+
+Passing @var{type} is not supported in this case,
+if it is provided a @code{wrong-type-arg} exception is thrown.
+
+@item Scheme bytevector
+If @var{value} is a Scheme bytevector and @var{type} is provided,
+@var{value} must be the same size, in bytes, of values of type @var{type},
+and the result is essentially created by using @code{memcpy}.
+
+If @var{value} is a Scheme bytevector and @var{type} is not provided,
+the result is an array of type @code{uint8} of the same length.
+@end table
+@end defun
+
+@cindex optimized out value in guile
+@defun value-optimized-out? value
+Return @code{#t} if the compiler optimized out @var{value},
+thus it is not available for fetching from the inferior.
+@end defun
+
+@defun value-address value
+If @var{value} is addressable, returns a
+@code{<gdb:value>} object representing the address.
+Otherwise, @code{#f} is returned.
+@end defun
+
+@defun value-type value
+Return the type of @var{value} as a @code{<gdb:type>} object
+(@pxref{Types In Guile}).
+@end defun
+
+@defun value-dynamic-type value
+Return the dynamic type of @var{value}. This uses C@t{++} run-time
+type information (@acronym{RTTI}) to determine the dynamic type of the
+value. If the value is of class type, it will return the class in
+which the value is embedded, if any. If the value is of pointer or
+reference to a class type, it will compute the dynamic type of the
+referenced object, and return a pointer or reference to that type,
+respectively. In all other cases, it will return the value's static
+type.
+
+Note that this feature will only work when debugging a C@t{++} program
+that includes @acronym{RTTI} for the object in question. Otherwise,
+it will just return the static type of the value as in @kbd{ptype foo}.
+@xref{Symbols, ptype}.
+@end defun
+
+@defun value-cast value type
+Return a new instance of @code{<gdb:value>} that is the result of
+casting @var{value} to the type described by @var{type}, which must
+be a @code{<gdb:type>} object. If the cast cannot be performed for some
+reason, this method throws an exception.
+@end defun
+
+@defun value-dynamic-cast value type
+Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast}
+operator were used. Consult a C@t{++} reference for details.
+@end defun
+
+@defun value-reinterpret-cast value type
+Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast}
+operator were used. Consult a C@t{++} reference for details.
+@end defun
+
+@defun value-dereference value
+For pointer data types, this method returns a new @code{<gdb:value>} object
+whose contents is the object pointed to by @var{value}. For example, if
+@code{foo} is a C pointer to an @code{int}, declared in your C program as
+
+@smallexample
+int *foo;
+@end smallexample
+
+@noindent
+then you can use the corresponding @code{<gdb:value>} to access what
+@code{foo} points to like this:
+
+@smallexample
+(define bar (value-dereference foo))
+@end smallexample
+
+The result @code{bar} will be a @code{<gdb:value>} object holding the
+value pointed to by @code{foo}.
+
+A similar function @code{value-referenced-value} exists which also
+returns @code{<gdb:value>} objects corresonding to the values pointed to
+by pointer values (and additionally, values referenced by reference
+values). However, the behavior of @code{value-dereference}
+differs from @code{value-referenced-value} by the fact that the
+behavior of @code{value-dereference} is identical to applying the C
+unary operator @code{*} on a given value. For example, consider a
+reference to a pointer @code{ptrref}, declared in your C@t{++} program
+as
+
+@smallexample
+typedef int *intptr;
+...
+int val = 10;
+intptr ptr = &val;
+intptr &ptrref = ptr;
+@end smallexample
+
+Though @code{ptrref} is a reference value, one can apply the method
+@code{value-dereference} to the @code{<gdb:value>} object corresponding
+to it and obtain a @code{<gdb:value>} which is identical to that
+corresponding to @code{val}. However, if you apply the method
+@code{value-referenced-value}, the result would be a @code{<gdb:value>}
+object identical to that corresponding to @code{ptr}.
+
+@smallexample
+(define scm-ptrref (parse-and-eval "ptrref"))
+(define scm-val (value-dereference scm-ptrref))
+(define scm-ptr (value-referenced-value scm-ptrref))
+@end smallexample
+
+The @code{<gdb:value>} object @code{scm-val} is identical to that
+corresponding to @code{val}, and @code{scm-ptr} is identical to that
+corresponding to @code{ptr}. In general, @code{value-dereference} can
+be applied whenever the C unary operator @code{*} can be applied
+to the corresponding C value. For those cases where applying both
+@code{value-dereference} and @code{value-referenced-value} is allowed,
+the results obtained need not be identical (as we have seen in the above
+example). The results are however identical when applied on
+@code{<gdb:value>} objects corresponding to pointers (@code{<gdb:value>}
+objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
+@end defun
+
+@defun value-referenced-value value
+For pointer or reference data types, this method returns a new
+@code{<gdb:value>} object corresponding to the value referenced by the
+pointer/reference value. For pointer data types,
+@code{value-dereference} and @code{value-referenced-value} produce
+identical results. The difference between these methods is that
+@code{value-dereference} cannot get the values referenced by reference
+values. For example, consider a reference to an @code{int}, declared
+in your C@t{++} program as
+
+@smallexample
+int val = 10;
+int &ref = val;
+@end smallexample
+
+@noindent
+then applying @code{value-dereference} to the @code{<gdb:value>} object
+corresponding to @code{ref} will result in an error, while applying
+@code{value-referenced-value} will result in a @code{<gdb:value>} object
+identical to that corresponding to @code{val}.
+
+@smallexample
+(define scm-ref (parse-and-eval "ref"))
+(define err-ref (value-dereference scm-ref)) ;; error
+(define scm-val (value-referenced-value scm-ref)) ;; ok
+@end smallexample
+
+The @code{<gdb:value>} object @code{scm-val} is identical to that
+corresponding to @code{val}.
+@end defun
+
+@defun value-field value field-name
+Return field @var{field-name} from @code{<gdb:value>} object @var{value}.
+@end defun
+
+@defun value-subscript value index
+Return the value of array @var{value} at index @var{index}.
+@var{value} must be a subscriptable @code{<gdb:value>} object.
+@end defun
+
+@defun value-call value arg-list
+Perform an inferior function call, taking @var{value} as a pointer
+to the function to call.
+Each element of list @var{arg-list} must be a <gdb:value> object or an object
+that can be converted to one.
+The result is the value returned by the function.
+@end defun
+
+@defun value->bool value
+Return the Scheme boolean representing @code{<gdb:value>} @var{value}.
+The value must be ``integer like''. Pointers are ok.
+@end defun
+
+@defun value->integer
+Return the Scheme integer representing @code{<gdb:value>} @var{value}.
+The value must be ``integer like''. Pointers are ok.
+@end defun
+
+@defun value->real
+Return the Scheme real number representing @code{<gdb:value>} @var{value}.
+The value must be a number.
+@end defun
+
+@defun value->bytevector
+Return a Scheme bytevector with the raw contents of @code{<gdb:value>}
+@var{value}. No transformation, endian or otherwise, is performed.
+@end defun
+
+@c TODO: line length
+@defun value->string value @r{[}#:encoding encoding@r{]} @r{[}#:errors errors@r{]} @r{[}#:length length@r{]}
+If @var{value>} represents a string, then this method
+converts the contents to a Guile string. Otherwise, this method will
+throw an exception.
+
+Strings are recognized in a language-specific way; whether a given
+@code{<gdb:value>} represents a string is determined by the current
+language.
+
+For C-like languages, a value is a string if it is a pointer to or an
+array of characters or ints. The string is assumed to be terminated
+by a zero of the appropriate width. However if the optional length
+argument is given, the string will be converted to that given length,
+ignoring any embedded zeros that the string may contain.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the string in the @code{<gdb:value>}, such as
+@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
+the same encodings as the corresponding argument to Guile's
+@code{scm_from_stringn} function, and the Guile codec machinery will be used
+to convert the string. If @var{encoding} is not given, or if
+@var{encoding} is the empty string, then either the @code{target-charset}
+(@pxref{Character Sets}) will be used, or a language-specific encoding
+will be used, if the current language is able to supply one.
+
+The optional @var{errors} argument is either @code{"strict"}
+or @code{"replace"}. A value of @code{"strict"} corresponds to
+Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
+corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
+
+If the optional @var{length} argument is given, the string will be
+fetched and converted to the given length.
+The length must be a Scheme integer and not a @code{<gdb:value>} integer.
+@end defun
+
+@c TODO: line length
+@defun value->lazy-string value @r{[}#:encoding encoding@r{]} @r{[}#:length length@r{]})
+If this @code{<gdb:value>} represents a string, then this method
+converts @var{value} to a @code{<gdb:lazy-string} (@pxref{Lazy Strings
+In Guile}). Otherwise, this method will throw an exception.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the @code{<gdb:lazy-string}. Some examples are:
+@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. If the
+@var{encoding} argument is an encoding that @value{GDBN} does not
+recognize, @value{GDBN} will raise an error.
+
+When a lazy string is printed, the @value{GDBN} encoding machinery is
+used to convert the string during printing. If the optional
+@var{encoding} argument is not provided, or is an empty string,
+@value{GDBN} will automatically select the encoding most suitable for
+the string type. For further information on encoding in @value{GDBN}
+please see @ref{Character Sets}.
+
+If the optional @var{length} argument is given, the string will be
+fetched and encoded to the length of characters specified. If
+the @var{length} argument is not provided, the string will be fetched
+and encoded until a null of appropriate width is found.
+The length must be a Scheme integer and not a @code{<gdb:value>} integer.
+@end defun
+
+@defun value-lazy? value
+Return @code{#t} if @var{value} has not yet been fetched
+from the inferior.
+@value{GDBN} does not fetch values until necessary, for efficiency.
+For example:
+
+@smallexample
+(define myval (parse-and-eval "somevar"))
+@end smallexample
+
+The value of @code{somevar} is not fetched at this time. It will be
+fetched when the value is needed, or when the @code{fetch-lazy}
+procedure is invoked.
+@end defun
+
+@defun make-lazy-value type address
+Return a @code{<gdb:value>} that will be lazily fetched from the target.
+@var{type} is an object of type @code{<gdb:type>} and @var{address} is
+a Scheme integer of the address of the object in target memory.
+@end defun
+
+@defun value-fetch-lazy! value
+If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}),
+then the value is fetched from the inferior.
+Any errors that occur in the process will produce a Guile exception.
+
+If @var{value} is not a lazy value, this method has no effect.
+
+The result of this function is unspecified.
+@end defun
+
+@defun value-print value
+Return the string representation (print form) of @code{<gdb:value>}
+@var{value}.
+@end defun
+
+@node Arithmetic In Guile
+@subsubsection Arithmetic In Guile
+
+The @code{(gdb)} module provides several functions for performing
+arithmetic on @code{<gdb:value>} objects.
+The arithmetic is performed as if it were done by the target,
+and therefore has target semantics which are not necessarily
+those of Scheme. For example operations work with a fixed precision,
+not the arbitrary precision of Scheme.
+
+Wherever a function takes an integer or pointer as an operand,
+@value{GDBN} will convert appropriate Scheme values to perform
+the operation.
+
+@defun value-add a b
+@end defun
+
+@defun value-sub a b
+@end defun
+
+@defun value-mul a b
+@end defun
+
+@defun value-div a b
+@end defun
+
+@defun value-rem a b
+@end defun
+
+@defun value-mod a b
+@end defun
+
+@defun value-pow a b
+@end defun
+
+@defun value-not a
+@end defun
+
+@defun value-neg a
+@end defun
+
+@defun value-pos a
+@end defun
+
+@defun value-abs a
+@end defun
+
+@defun value-lsh a b
+@end defun
+
+@defun value-rsh a b
+@end defun
+
+@defun value-max a b
+@end defun
+
+@defun value-max a b
+@end defun
+
+@defun value-lognot a
+@end defun
+
+@defun value-logand a b
+@end defun
+
+@defun value-logior a b
+@end defun
+
+@defun value-logxor a b
+@end defun
+
+@defun value=? a b
+@end defun
+
+@defun value<? a b
+@end defun
+
+@defun value<=? a b
+@end defun
+
+@defun value>? a b
+@end defun
+
+@defun value>=? a b
+@end defun
+
+Scheme does not provide a @code{not-equal} function,
+and thus Guile support in @value{GDBN} does not either.
+
+@node Types In Guile
+@subsubsection Types In Guile
+@cindex types in guile
+@cindex guile, working with types
+
+@tindex <gdb:type>
+@value{GDBN} represents types from the inferior in objects of type
+@code{<gdb:type>}.
+
+The following type-related procedures are provided by the
+@code{(gdb)} module.
+
+@defun type? object
+Return @code{#t} if @var{object} is an object of type @code{<gdb:type>}.
+@end defun
+
+@defun lookup-type name @r{[}#:block block@r{]}
+This function looks up a type by name. @var{name} is the name of the
+type to look up. It must be a string.
+
+If @var{block} is given, it is an object of type @code{<gdb:block>},
+and @var{name} is looked up in that scope.
+Otherwise, it is searched for globally.
+
+Ordinarily, this function will return an instance of @code{<gdb:type>}.
+If the named type cannot be found, it will throw an exception.
+@end defun
+
+@defun type-code type
+Return the type code for this type. The type code will be one of the
+@code{TYPE_CODE_} constants defined below.
+@end defun
+
+@defun type-tag type
+Return the tag name for this type. The tag name is the name after
+@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
+languages have this concept. If this type has no tag name, then
+@code{#f} is returned.
+@end defun
+
+@defun type-sizeof type
+Return the size of this type, in target @code{char} units. Usually, a
+target's @code{char} type will be an 8-bit byte. However, on some
+unusual platforms, this type may have a different size.
+@end defun
+
+@defun type-strip-typedefs type
+Return a new @code{<gdb:type>} that represents the real type of @var{type},
+after removing all layers of typedefs.
+@end defun
+
+@defun type-array type @var{n1} @r{[}@var{n2}@r{]}
+Return a new @code{<gdb:type>} object which represents an array of this
+type. If one argument is given, it is the inclusive upper bound of
+the array; in this case the lower bound is zero. If two arguments are
+given, the first argument is the lower bound of the array, and the
+second argument is the upper bound of the array. An array's length
+must not be negative, but the bounds can be.
+@end defun
+
+@defun type-vector type @var{n1} @r{[}@var{n2}@r{]}
+Return a new @code{<gdb:type>} object which represents a vector of this
+type. If one argument is given, it is the inclusive upper bound of
+the vector; in this case the lower bound is zero. If two arguments are
+given, the first argument is the lower bound of the vector, and the
+second argument is the upper bound of the vector. A vector's length
+must not be negative, but the bounds can be.
+
+The difference between an @code{array} and a @code{vector} is that
+arrays behave like in C: when used in expressions they decay to a pointer
+to the first element whereas vectors are treated as first class values.
+@end defun
+
+@defun type-pointer type
+Return a new @code{<gdb:type>} object which represents a pointer to
+@var{type}.
+@end defun
+
+@defun type-range type
+Return a list of two elements: the low bound and high bound of @var{type}.
+If @var{type} does not have a range, an exception is thrown.
+@end defun
+
+@defun type-reference type
+Return a new @code{<gdb:type>} object which represents a reference to
+@var{type}.
+@end defun
+
+@defun type-target type
+Return a new @code{<gdb:type>} object which represents the target type
+of @var{type}.
+
+For a pointer type, the target type is the type of the pointed-to
+object. For an array type (meaning C-like arrays), the target type is
+the type of the elements of the array. For a function or method type,
+the target type is the type of the return value. For a complex type,
+the target type is the type of the elements. For a typedef, the
+target type is the aliased type.
+
+If the type does not have a target, this method will throw an
+exception.
+@end defun
+
+@defun type-const type
+Return a new @code{<gdb:type>} object which represents a
+@code{const}-qualified variant of @var{type}.
+@end defun
+
+@defun type-volatile type
+Return a new @code{<gdb:type>} object which represents a
+@code{volatile}-qualified variant of @var{type}.
+@end defun
+
+@defun type-unqualified type
+Return a new @code{<gdb:type>} object which represents an unqualified
+variant of @var{type}. That is, the result is neither @code{const} nor
+@code{volatile}.
+@end defun
+
+@defun type-name type
+Return the name of @code{<gdb:type>} @var{type}.
+@end defun
+
+@defun type-num-fields
+Return the number of fields of @code{<gdb:type>} @var{type}.
+@end defun
+
+@defun type-fields type
+Return the fields of @var{type} as a list.
+For structure and union types, @code{fields} has the usual meaning.
+Range types have two fields, the minimum and maximum values. Enum types
+have one field per enum constant. Function and method types have one
+field per parameter. The base types of C@t{++} classes are also
+represented as fields. If the type has no fields, or does not fit
+into one of these categories, an empty list will be returned.
+@xref{Fields of a Type in Guile}.
+@end defun
+
+@defun make-field-iterator type
+Return the fields of @var{type} as a <gdb:iterator> object.
+@xref{Iterators In Guile}.
+@end defun
+
+@defun type-field type field-name
+Return field named @var{field-name} in @var{type}.
+The result is an object of type @code{<gdb:field>}.
+@xref{Fields of a Type in Guile}.
+If the type does not have fields, or @var{field-name} is not a field
+of @var{type}, an exception is thrown.
+
+For example, if @code{some-type} is a @code{<gdb:type>} instance holding
+a structure type, you can access its @code{foo} field with:
+
+@smallexample
+(define bar (type-field some-type "foo"))
+@end smallexample
+
+@code{bar} will be a @code{<gdb:field>} object.
+@end defun
+
+@defun type-has-field? type name
+Return @code{#t} if @code{<gdb:type>} @var{type} has field named @var{name}.
+@end defun
+
+Each type has a code, which indicates what category this type falls
+into. The available type categories are represented by constants
+defined in the @code{(gdb)} module:
+
+@table @code
+@findex TYPE_CODE_PTR
+@item TYPE_CODE_PTR
+The type is a pointer.
+
+@findex TYPE_CODE_ARRAY
+@item TYPE_CODE_ARRAY
+The type is an array.
+
+@findex TYPE_CODE_STRUCT
+@item TYPE_CODE_STRUCT
+The type is a structure.
+
+@findex TYPE_CODE_UNION
+@item TYPE_CODE_UNION
+The type is a union.
+
+@findex TYPE_CODE_ENUM
+@item TYPE_CODE_ENUM
+The type is an enum.
+
+@findex TYPE_CODE_FLAGS
+@item TYPE_CODE_FLAGS
+A bit flags type, used for things such as status registers.
+
+@findex TYPE_CODE_FUNC
+@item TYPE_CODE_FUNC
+The type is a function.
+
+@findex TYPE_CODE_INT
+@item TYPE_CODE_INT
+The type is an integer type.
+
+@findex TYPE_CODE_FLT
+@item TYPE_CODE_FLT
+A floating point type.
+
+@findex TYPE_CODE_VOID
+@item TYPE_CODE_VOID
+The special type @code{void}.
+
+@findex TYPE_CODE_SET
+@item TYPE_CODE_SET
+A Pascal set type.
+
+@findex TYPE_CODE_RANGE
+@item TYPE_CODE_RANGE
+A range type, that is, an integer type with bounds.
+
+@findex TYPE_CODE_STRING
+@item TYPE_CODE_STRING
+A string type. Note that this is only used for certain languages with
+language-defined string types; C strings are not represented this way.
+
+@findex TYPE_CODE_BITSTRING
+@item TYPE_CODE_BITSTRING
+A string of bits. It is deprecated.
+
+@findex TYPE_CODE_ERROR
+@item TYPE_CODE_ERROR
+An unknown or erroneous type.
+
+@findex TYPE_CODE_METHOD
+@item TYPE_CODE_METHOD
+A method type, as found in C@t{++} or Java.
+
+@findex TYPE_CODE_METHODPTR
+@item TYPE_CODE_METHODPTR
+A pointer-to-member-function.
+
+@findex TYPE_CODE_MEMBERPTR
+@item TYPE_CODE_MEMBERPTR
+A pointer-to-member.
+
+@findex TYPE_CODE_REF
+@item TYPE_CODE_REF
+A reference type.
+
+@findex TYPE_CODE_CHAR
+@item TYPE_CODE_CHAR
+A character type.
+
+@findex TYPE_CODE_BOOL
+@item TYPE_CODE_BOOL
+A boolean type.
+
+@findex TYPE_CODE_COMPLEX
+@item TYPE_CODE_COMPLEX
+A complex float type.
+
+@findex TYPE_CODE_TYPEDEF
+@item TYPE_CODE_TYPEDEF
+A typedef to some other type.
+
+@findex TYPE_CODE_NAMESPACE
+@item TYPE_CODE_NAMESPACE
+A C@t{++} namespace.
+
+@findex TYPE_CODE_DECFLOAT
+@item TYPE_CODE_DECFLOAT
+A decimal floating point type.
+
+@findex TYPE_CODE_INTERNAL_FUNCTION
+@item TYPE_CODE_INTERNAL_FUNCTION
+A function internal to @value{GDBN}. This is the type used to represent
+convenience functions.
+@end table
+
+Further support for types is provided in the @code{(gdb types)}
+Guile module (@pxref{Guile Types Module}).
+
+@anchor{Fields of a Type in Guile}
+Each field is represented as an object of type @code{<gdb:field>}.
+
+The following field-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun field? object
+Return @code{#t} if @var{object} is an object of type @code{<gdb:field>}.
+@end defun
+
+@defun field-name field
+Return the name of the field, or @code{#f} for anonymous fields.
+@end defun
+
+@defun field-type field
+Return the type of the field. This is usually an instance of
+@code{<gdb:type>}, but it can be @code{#f} in some situations.
+@end defun
+
+@defun field-enumval field
+Return the enum value represented by @code{<gdb:field>} @var{field}.
+@end defun
+
+@defun field-bitpos field
+Return the bit position of @code{<gdb:field>} @var{field}.
+This attribute is not available for @code{static} fields (as in
+C@t{++} or Java).
+@end defun
+
+@defun field-bitsize field
+If the field is packed, or is a bitfield, return the size of
+@code{<gdb:field>} @var{field} in bits. Otherwise, zero is returned;
+in which case the field's size is given by its type.
+@end defun
+
+@defun field-artificial? field
+Return @code{#t} if the field is artificial, usually meaning that
+it was provided by the compiler and not the user.
+@end defun
+
+@defun field-base-class? field
+Return @code{#t} if the field represents a base class of a C@t{++}
+structure.
+@end defun
+
+@node Guile Pretty Printing API
+@subsubsection Guile Pretty Printing API
+
+An example output is provided (@pxref{Pretty Printing}).
+
+A pretty-printer is represented by an object of type <gdb:pretty-printer>.
+Pretty-printer objects are created with @code{make-pretty-printer}.
+
+The following pretty-printer-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun make-pretty-printer name lookup-function
+Return a @code{<gdb:pretty-printer>} object named @var{name}.
+
+@var{lookup-function} is a function of one parameter: the value to
+be printed. If the value is handled by this pretty-printer, then
+@var{lookup-function} returns an object of type
+<gdb:pretty-printer-worker> to perform the actual pretty-printing.
+Otherwise @var{lookup-function} returns @code{#f}.
+@end defun
+
+@defun pretty-printer? object
+Return @code{#t} if @var{object} is a @code{<gdb:pretty-printer>} object.
+@end defun
+
+@defun pretty-printer-enabled? pretty-printer
+Return @code{#t} if @var{pretty-printer} is enabled.
+@end defun
+
+@defun set-pretty-printer-enabled! pretty-printer flag
+Set the enabled flag of @var{pretty-printer} to @var{flag}.
+The value returned in unspecified.
+@end defun
+
+@defun make-pretty-printer-worker display-hint to-string children
+Return an object of type @code{<gdb:pretty-printer-worker>}.
+
+This function takes three parameters:
+
+@table @samp
+@item display-hint
+@var{display-hint} provides a hint to @value{GDBN} or @value{GDBN}
+front end via MI to change the formatting of the value being printed.
+The value must be a string or @code{#f} (meaning there is no hint).
+Several values for @var{display-hint}
+are predefined by @value{GDBN}:
+
+@table @samp
+@item array
+Indicate that the object being printed is ``array-like''. The CLI
+uses this to respect parameters such as @code{set print elements} and
+@code{set print array}.
+
+@item map
+Indicate that the object being printed is ``map-like'', and that the
+children of this value can be assumed to alternate between keys and
+values.
+
+@item string
+Indicate that the object being printed is ``string-like''. If the
+printer's @code{to-string} function returns a Guile string of some
+kind, then @value{GDBN} will call its internal language-specific
+string-printing function to format the string. For the CLI this means
+adding quotation marks, possibly escaping some characters, respecting
+@code{set print elements}, and the like.
+@end table
+
+@item to-string
+@var{to-string} is either a function of one parameter, the
+@code{<gdb:pretty-printer-worker>} object, or @code{#f}.
+
+When printing from the CLI, if the @code{to-string} method exists,
+then @value{GDBN} will prepend its result to the values returned by
+@code{children}. Exactly how this formatting is done is dependent on
+the display hint, and may change as more hints are added. Also,
+depending on the print settings (@pxref{Print Settings}), the CLI may
+print just the result of @code{to-string} in a stack trace, omitting
+the result of @code{children}.
+
+If this method returns a string, it is printed verbatim.
+
+Otherwise, if this method returns an instance of @code{<gdb:value>},
+then @value{GDBN} prints this value. This may result in a call to
+another pretty-printer.
+
+If instead the method returns a Guile value which is convertible to a
+@code{<gdb:value>}, then @value{GDBN} performs the conversion and prints
+the resulting value. Again, this may result in a call to another
+pretty-printer. Guile scalars (integers, floats, and booleans) and
+strings are convertible to @code{<gdb:value>}; other types are not.
+
+Finally, if this method returns @code{#f} then no further operations
+are peformed in this method and nothing is printed.
+
+If the result is not one of these types, an exception is raised.
+
+@var{to-string} may also be @code{#f} in which case it is left to
+@var{children} to print the value.
+
+@item children
+@var{children} is either a function of one parameter, the
+@code{<gdb:pretty-printer-worker>} object, or @code{#f}.
+
+@value{GDBN} will call this function on a pretty-printer to compute the
+children of the pretty-printer's value.
+
+This function must return a <gdb:iterator> object.
+Each item returned by the iterator must be a tuple holding
+two elements. The first element is the ``name'' of the child; the
+second element is the child's value. The value can be any Guile
+object which is convertible to a @value{GDBN} value.
+
+If @var{children} is @code{#f}, @value{GDBN} will act
+as though the value has no children.
+@end table
+@end defun
+
+@value{GDBN} provides a function which can be used to look up the
+default pretty-printer for a @code{<gdb:value>}:
+
+@defun default-visualizer value
+This function takes a @code{<gdb:value>} object as an argument. If a
+pretty-printer for this value exists, then it is returned. If no such
+printer exists, then this returns @code{#f}.
+@end defun
+
+@node Selecting Guile Pretty-Printers
+@subsubsection Selecting Guile Pretty-Printers
+
+The Guile list @code{*pretty-printers*} contains a set of
+@code{<gdb:pretty-printer>} registered objects.
+Printers in this list are called @code{global}
+printers, they're available when debugging any inferior.
+In addition to this, each @code{<gdb:objfile>} object contains its
+own set of pretty-printers (@pxref{Objfiles In Guile}).
+
+Pretty-printer lookup is done by passing the value to be printed to the
+lookup function of each enabled object in turn.
+Lookup stops when a lookup function returns a non-@code{#f} value
+or when the list is exhausted.
+
+@value{GDBN} first checks the result of @code{objfile-pretty-printers}
+of each @code{<gdb:objfile>} in the current program space and iteratively
+calls each enabled lookup function in the list for that @code{<gdb:objfile>}
+until a non-@code{#f} object is returned.
+Lookup functions must return either a @code{<gdb:pretty-printer-worker>}
+object or @code{#f}. Otherwise an exception is thrown.
+If no pretty-printer is found in the objfile lists, @value{GDBN} then
+searches the global pretty-printer list, calling each enabled function
+until a non-@code{#f} object is returned.
+
+The order in which the objfiles are searched is not specified. For a
+given list, functions are always invoked from the head of the list,
+and iterated over sequentially until the end of the list, or a
+@code{<gdb:pretty-printer-worker>} object is returned.
+
+For various reasons a pretty-printer may not work.
+For example, the underlying data structure may have changed and
+the pretty-printer is out of date.
+
+The consequences of a broken pretty-printer are severe enough that
+@value{GDBN} provides support for enabling and disabling individual
+printers. For example, if @code{print frame-arguments} is on,
+a backtrace can become highly illegible if any argument is printed
+with a broken printer.
+
+Pretty-printers are enabled and disabled from Scheme by calling
+@code{set-pretty-printer-enabled!}.
+@xref{Guile Pretty Printing API}.
+
+@node Writing a Guile Pretty-Printer
+@subsubsection Writing a Guile Pretty-Printer
+@cindex writing a Guile pretty-printer
+
+A pretty-printer consists of two basic parts: a lookup function to determine
+if the type is supported, and the printer itself.
+
+Here is an example showing how a @code{std::string} printer might be
+written. @xref{Guile Pretty Printing API}, for details.
+
+@smallexample
+(define (make-my-string-printer value)
+ "Print a my::string string"
+ (make-pretty-printer-worker
+ "string"
+ (lambda (printer)
+ (value-field value "_data"))
+ #f))
+@end smallexample
+
+And here is an example showing how a lookup function for the printer
+example above might be written.
+
+@smallexample
+(define (string-begins-with str prefix)
+ (= (string-prefix-length str prefix) (string-length prefix)))
+
+(define (str-lookup-function value)
+ (let ((tag (type-tag (value-type value))))
+ (and tag
+ (string-begins-with tag "my::string<")
+ (make-std-string-printer value))))
+@end smallexample
+
+Then to register this printer in the global printer list:
+
+@smallexample
+(append-pretty-printer!
+ (make-pretty-printer "my-string" str-lookup-function))
+@end smallexample
+
+The example lookup function extracts the value's type, and attempts to
+match it to a type that it can pretty-print. If it is a type the
+printer can pretty-print, it will return a <gdb:pretty-printer-worker> object.
+If not, it returns @code{#f}.
+
+We recommend that you put your core pretty-printers into a Guile
+package. If your pretty-printers are for use with a library, we
+further recommend embedding a version number into the package name.
+This practice will enable @value{GDBN} to load multiple versions of
+your pretty-printers at the same time, because they will have
+different names.
+
+You should write auto-loaded code (@pxref{Guile Auto-loading}) such that it
+can be evaluated multiple times without changing its meaning. An
+ideal auto-load file will consist solely of @code{import}s of your
+printer modules, followed by a call to a register pretty-printers with
+the current objfile.
+
+Taken as a whole, this approach will scale nicely to multiple
+inferiors, each potentially using a different library version.
+Embedding a version number in the Guile package name will ensure that
+@value{GDBN} is able to load both sets of printers simultaneously.
+Then, because the search for pretty-printers is done by objfile, and
+because your auto-loaded code took care to register your library's
+printers with a specific objfile, @value{GDBN} will find the correct
+printers for the specific version of the library used by each
+inferior.
+
+To continue the @code{my::string} example,
+this code might appear in @code{(my-project my-library v1)}:
+
+@smallexample
+(use-modules ((gdb)))
+(define (register-printers objfile)
+ (append-objfile-pretty-printer!
+ (make-pretty-printer "my-string" str-lookup-function)))
+@end smallexample
+
+@noindent
+And then the corresponding contents of the auto-load file would be:
+
+@smallexample
+(use-modules ((gdb) (my-project my-library v1)))
+(register-printers (current-objfile))
+@end smallexample
+
+The previous example illustrates a basic pretty-printer.
+There are a few things that can be improved on.
+The printer only handles one type, whereas a library typically has
+several types. One could install a lookup function for each desired type
+in the library, but one could also have a single lookup function recognize
+several types. The latter is the conventional way this is handled.
+If a pretty-printer can handle multiple data types, then its
+@dfn{subprinters} are the printers for the individual data types.
+
+The @code{(gdb printing)} module provides a formal way of solving this
+problem (@pxref{Guile Printing Module}).
+Here is another example that handles multiple types.
+
+These are the types we are going to pretty-print:
+
+@smallexample
+struct foo @{ int a, b; @};
+struct bar @{ struct foo x, y; @};
+@end smallexample
+
+Here are the printers:
+
+@smallexample
+(define (make-foo-printer value)
+ "Print a foo object"
+ (make-pretty-printer-worker
+ "foo"
+ (lambda (printer)
+ (format #f "a=<~a> b=<~a>"
+ (value-field value "a") (value-field value "a")))
+ #f))
+
+(define (make-bar-printer value)
+ "Print a bar object"
+ (make-pretty-printer-worker
+ "foo"
+ (lambda (printer)
+ (format #f "x=<~a> y=<~a>"
+ (value-field value "x") (value-field value "y")))
+ #f))
+@end smallexample
+
+This example doesn't need a lookup function, that is handled by the
+@code{(gdb printing)} module. Instead a function is provided to build up
+the object that handles the lookup.
+
+@smallexample
+(use-modules ((gdb printing)))
+
+(define (build-pretty-printer)
+ (let ((pp (make-pretty-printer-collection "my-library")))
+ (pp-collection-add-tag-printer "foo" make-foo-printer)
+ (pp-collection-add-tag-printer "bar" make-bar-printer)
+ pp))
+@end smallexample
+
+And here is the autoload support:
+
+@smallexample
+(use-modules ((gdb) (my-library)))
+(append-objfile-pretty-printer! (current-objfile) (build-pretty-printer))
+@end smallexample
+
+Finally, when this printer is loaded into @value{GDBN}, here is the
+corresponding output of @samp{info pretty-printer}:
+
+@smallexample
+(gdb) info pretty-printer
+my_library.so:
+ my-library
+ foo
+ bar
+@end smallexample
+
+@node Objfiles In Guile
+@subsubsection Objfiles In Guile
+
+@cindex objfiles in guile
+@tindex <gdb:objfile>
+@value{GDBN} loads symbols for an inferior from various
+symbol-containing files (@pxref{Files}). These include the primary
+executable file, any shared libraries used by the inferior, and any
+separate debug info files (@pxref{Separate Debug Files}).
+@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
+
+Each objfile is represented as an object of type @code{<gdb:objfile>}.
+
+The following objfile-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun objfile? object
+Return @code{#t} if @var{object} is a @code{<gdb:objfile>} object.
+@end defun
+
+@defun objfile-valid? objfile
+Return @code{#t} if @var{objfile} is valid, @code{#f} if not.
+A @code{<gdb:objfile>} object can become invalid
+if the object file it refers to is not loaded in @value{GDBN} any
+longer. All other @code{<gdb:objfile>} procedures will throw an exception
+if it is invalid at the time the procedure is called.
+@end defun
+
+@defun objfile-filename objfile
+Return the file name of @var{objfile} as a string.
+@end defun
+
+@defun objfile-pretty-printers objfile
+Return the list of registered @code{<gdb:pretty-printer>} objects for
+@var{objfile}. @xref{Guile Pretty Printing API}, for more information.
+@end defun
+
+@defun set-objfile-pretty-printers! objfile printer-list
+Set the list of registered @code{<gdb:pretty-printer>} objects for
+@var{objfile} to @var{printer-list}.
+@var{printer-list} must be a list of @code{<gdb:pretty-printer>} objects.
+@xref{Guile Pretty Printing API}, for more information.
+@end defun
+
+@defun current-objfile
+When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN}
+sets the ``current objfile'' to the corresponding objfile. This
+function returns the current objfile. If there is no current objfile,
+this function returns @code{#f}.
+@end defun
+
+@defun objfiles
+Return a list of all the objfiles in the current program space.
+@end defun
+
+@node Frames In Guile
+@subsubsection Accessing inferior stack frames from Guile.
+
+@cindex frames in guile
+When the debugged program stops, @value{GDBN} is able to analyze its call
+stack (@pxref{Frames,,Stack frames}). The @code{<gdb:frame>} class
+represents a frame in the stack. A @code{<gdb:frame>} object is only valid
+while its corresponding frame exists in the inferior's stack. If you try
+to use an invalid frame object, @value{GDBN} will throw a
+@code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}).
+
+Two @code{<gdb:frame>} objects can be compared for equality with the
+@code{equal?} function, like:
+
+@smallexample
+(@value{GDBP}) guile (equal? (newest-frame) (selected-frame))
+#t
+@end smallexample
+
+The following frame-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun frame? object
+Return @code{#t} if @var{object} is a @code{<gdb:frame>} object.
+@end defun
+
+@defun frame-valid? frame
+Returns @code{#t} if @var{frame} is valid, @code{#f} if not.
+A frame object can become invalid if the frame it refers to doesn't
+exist anymore in the inferior. All @code{<gdb:frame>} procedures will throw
+an exception if the frame is invalid at the time the procedure is called.
+@end defun
+
+@defun frame-name frame
+Return the function name of @var{frame}, or @code{#f} if it can't be
+obtained.
+@end defun
+
+@defun frame-arch frame
+Return the @code{<gdb:architecture>} object corresponding to @var{frame}'s
+architecture. @xref{Architectures In Guile}.
+@end defun
+
+@defun frame-type frame
+Return the type of @var{frame}. The value can be one of:
+
+@table @code
+@item NORMAL_FRAME
+An ordinary stack frame.
+
+@item DUMMY_FRAME
+A fake stack frame that was created by @value{GDBN} when performing an
+inferior function call.
+
+@item INLINE_FRAME
+A frame representing an inlined function. The function was inlined
+into a @code{NORMAL_FRAME} that is older than this one.
+
+@item TAILCALL_FRAME
+A frame representing a tail call. @xref{Tail Call Frames}.
+
+@item SIGTRAMP_FRAME
+A signal trampoline frame. This is the frame created by the OS when
+it calls into a signal handler.
+
+@item ARCH_FRAME
+A fake stack frame representing a cross-architecture call.
+
+@item SENTINEL_FRAME
+This is like @code{NORMAL_FRAME}, but it is only used for the
+newest frame.
+@end table
+@end defun
+
+@defun frame-unwind-stop-reason frame
+Return an integer representing the reason why it's not possible to find
+more frames toward the outermost frame. Use
+@code{unwind-stop-reason-string} to convert the value returned by this
+function to a string. The value can be one of:
+
+@table @code
+@item FRAME_UNWIND_NO_REASON
+No particular reason (older frames should be available).
+
+@item FRAME_UNWIND_NULL_ID
+The previous frame's analyzer returns an invalid result.
+
+@item FRAME_UNWIND_OUTERMOST
+This frame is the outermost.
+
+@item FRAME_UNWIND_UNAVAILABLE
+Cannot unwind further, because that would require knowing the
+values of registers or memory that have not been collected.
+
+@item FRAME_UNWIND_INNER_ID
+This frame ID looks like it ought to belong to a NEXT frame,
+but we got it for a PREV frame. Normally, this is a sign of
+unwinder failure. It could also indicate stack corruption.
+
+@item FRAME_UNWIND_SAME_ID
+This frame has the same ID as the previous one. That means
+that unwinding further would almost certainly give us another
+frame with exactly the same ID, so break the chain. Normally,
+this is a sign of unwinder failure. It could also indicate
+stack corruption.
+
+@item FRAME_UNWIND_NO_SAVED_PC
+The frame unwinder did not find any saved PC, but we needed
+one to unwind further.
+
+@item FRAME_UNWIND_FIRST_ERROR
+Any stop reason greater or equal to this value indicates some kind
+of error. This special value facilitates writing code that tests
+for errors in unwinding in a way that will work correctly even if
+the list of the other values is modified in future @value{GDBN}
+versions. Using it, you could write:
+
+@smallexample
+(define reason (frame-unwind-stop-readon (selected-frame)))
+(define reason-str (unwind-stop-reason-string reason))
+(if (>= reason FRAME_UNWIND_FIRST_ERROR)
+ (format #t "An error occured: ~s\n" reason-str))
+@end smallexample
+@end table
+@end defun
+
+@defun frame-pc frame
+Return the frame's resume address.
+@end defun
+
+@defun frame-block frame
+Return the frame's code block as a @code{<gdb:block>} object.
+@xref{Blocks In Guile}.
+@end defun
+
+@defun frame-function frame
+Return the symbol for the function corresponding to this frame
+as a @code{<gdb:symbol>} object, or @code{#f} if there isn't one.
+@xref{Symbols In Guile}.
+@end defun
+
+@defun frame-older frame
+Return the frame that called @var{frame}.
+@end defun
+
+@defun frame-newer frame
+Return the frame called by @var{frame}.
+@end defun
+
+@defun frame-sal frame
+Return the frame's @code{<gdb:sal>} (symtab and line) object.
+@xref{Symbol Tables In Guile}.
+@end defun
+
+@defun frame-read-var variable @r{[}#:block block@r{]}
+Return the value of @var{variable} in this frame. If the optional
+argument @var{block} is provided, search for the variable from that
+block; otherwise start at the frame's current block (which is
+determined by the frame's current program counter). @var{variable}
+must be a string or a @code{<gdb:symbol>} object. @var{block} must be a
+@code{<gdb:block>} object.
+@end defun
+
+@defun frame-select frame
+Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the
+Stack}.
+@end defun
+
+@defun selected-frame
+Return the selected frame object. @xref{Selection,,Selecting a Frame}.
+@end defun
+
+@defun newest-frame
+Return the newest frame object for the selected thread.
+@end defun
+
+@defun unwind-stop-reason-string reason
+Return a string explaining the reason why @value{GDBN} stopped unwinding
+frames, as expressed by the given @var{reason} code (an integer, see the
+@code{frame-unwind-stop-reason} procedure above in this section).
+@end defun
+
+@node Blocks In Guile
+@subsubsection Accessing blocks from Guile.
+
+@cindex blocks in guile
+@tindex <gdb:block>
+
+In @value{GDBN}, symbols are stored in blocks. A block corresponds
+roughly to a scope in the source code. Blocks are organized
+hierarchically, and are represented individually in Guile as an object
+of type @code{<gdb:block>}. Blocks rely on debugging information being
+available.
+
+A frame has a block. Please see @ref{Frames In Guile}, for a more
+in-depth discussion of frames.
+
+The outermost block is known as the @dfn{global block}. The global
+block typically holds public global variables and functions.
+
+The block nested just inside the global block is the @dfn{static
+block}. The static block typically holds file-scoped variables and
+functions.
+
+@value{GDBN} provides a method to get a block's superblock, but there
+is currently no way to examine the sub-blocks of a block, or to
+iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
+Guile}).
+
+Here is a short example that should help explain blocks:
+
+@smallexample
+/* This is in the global block. */
+int global;
+
+/* This is in the static block. */
+static int file_scope;
+
+/* 'function' is in the global block, and 'argument' is
+ in a block nested inside of 'function'. */
+int function (int argument)
+@{
+ /* 'local' is in a block inside 'function'. It may or may
+ not be in the same block as 'argument'. */
+ int local;
+
+ @{
+ /* 'inner' is in a block whose superblock is the one holding
+ 'local'. */
+ int inner;
+
+ /* If this call is expanded by the compiler, you may see
+ a nested block here whose function is 'inline_function'
+ and whose superblock is the one holding 'inner'. */
+ inline_function ();
+ @}
+@}
+@end smallexample
+
+The following block-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun block? object
+Return @code{#t} if @var{object} is a @code{<gdb:block>} object.
+@end defun
+
+@defun block-valid? block
+Returns @code{#t} if @code{<gdb:block>} @var{block} is valid,
+@code{#f} if not. A block object can become invalid if the block it
+refers to doesn't exist anymore in the inferior. All other
+@code{<gdb:block>} methods will throw an exception if it is invalid at
+the time the procedure is called. The block's validity is also checked
+during iteration over symbols of the block.
+@end defun
+
+@defun block-start block
+Return the start address of @code{<gdb:block>} @var{block}.
+@end defun
+
+@defun block-end block
+Return the end address of @code{<gdb:block>} @var{block}.
+@end defun
+
+@defun block-function block
+Return the name of @code{<gdb:block>} @var{block} represented as a
+@code{<gdb:symbol>} object.
+If the block is not named, then @code{#f} is returned.
+
+For ordinary function blocks, the superblock is the static block.
+However, you should note that it is possible for a function block to
+have a superblock that is not the static block -- for instance this
+happens for an inlined function.
+@end defun
+
+@defun block-superblock block
+Return the block containing @code{<gdb:block>} @var{block}.
+If the parent block does not exist, then @code{#f} is returned.
+@end defun
+
+@defun block-global-block block
+Return the global block associated with @code{<gdb:block>} @var{block}.
+@end defun
+
+@defun block-static-block block
+Return the static block associated with @code{<gdb:block>} @var{block}.
+@end defun
+
+@defun block-global? block
+Return @code{#t} if @code{<gdb:block>} @var{block} is a global block.
+@end defun
+
+@defun block-static? block
+Return @code{#t} if @code{<gdb:block>} @var{block} is a static block.
+@end defun
+
+@defun block-symbols
+Return a list of all symbols (as <gdb:symbol> objects) in
+@code{<gdb:block>} @var{block}.
+@end defun
+
+@defun make-block-symbols-iterator block
+Return an object of type @code{<gdb:iterator>} that will iterate
+over all symbols of the block.
+Guile programs should not assume that a specific block object will
+always contain a given symbol, since changes in @value{GDBN} features and
+infrastructure may cause symbols move across blocks in a symbol table.
+@end defun
+
+@defun block-symbols-progress?
+Return #t if the object is a <gdb:block-symbols-progress> object.
+This object would be obtained from the @code{progress} element of the
+@code{<gdb:iterator>} object returned by @code{make-block-symbols-iterator}.
+@xref{Iterators In Guile}.
+@end defun
+
+@defun lookup-block pc
+Return the innermost @code{<gdb:block>} containing the given @var{pc}
+value. If the block cannot be found for the @var{pc} value specified,
+the function will return @code{#f}.
+@end defun
+
+@node Symbols In Guile
+@subsubsection Guile representation of Symbols.
+
+@cindex symbols in guile
+@tindex <gdb:symbol>
+
+@value{GDBN} represents every variable, function and type as an
+entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
+Guile represents these symbols in @value{GDBN} with the
+@code{<gdb:symbol>} object.
+
+The following symbol-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun symbol? object
+Return @code{#t} if @var{object} is an object of type @code{<gdb:symbol>}.
+@end defun
+
+@defun symbol-valid? symbol
+Return @code{#t} if the @code{<gdb:symbol>} object is valid,
+@code{#f} if not. A @code{<gdb:symbol>} object can become invalid if
+the symbol it refers to does not exist in @value{GDBN} any longer.
+All other @code{<gdb:symbol>} procedures will throw an exception if it is
+invalid at the time the procedure is called.
+@end defun
+
+@defun symbol-type symbol
+Return the type of @var{symbol} or @code{#f} if no type is recorded.
+The result is an object of type @code{<gdb:type>}.
+@xref{Types In Guile}.
+@end defun
+
+@defun symbol-symtab symbol
+Return the symbol table in which @var{symbol} appears.
+The result is an object of type @code{<gdb:symtab>}.
+@xref{Symbol Tables In Guile}.
+@end defun
+
+@defun symbol-line symbol
+Return the line number in the source code at which @var{symbol} was defined.
+This is an integer.
+@end defun
+
+@defun symbol-name symbol
+Return the name of @var{symbol} as a string.
+@end defun
+
+@defun symbol-linkage-name symbol
+Return the name of @var{symbol}, as used by the linker (i.e., may be mangled).
+@end defun
+
+@defun symbol-print-name symbol
+Return the name of @var{symbol} in a form suitable for output. This is either
+@code{name} or @code{linkage_name}, depending on whether the user
+asked @value{GDBN} to display demangled or mangled names.
+@end defun
+
+@defun symbol-addr-class symbol
+Return the address class of the symbol. This classifies how to find the value
+of a symbol. Each address class is a constant defined in the
+@code{(gdb)} module and described later in this chapter.
+@end defun
+
+@defun symbol-needs-frame? symbol
+Return @code{#t} if evaluating @var{symbol}'s value requires a frame
+(@pxref{Frames In Guile}) and @code{#f} otherwise. Typically,
+local variables will require a frame, but other symbols will not.
+@end defun
+
+@defun symbol-argument? symbol
+Return @code{#t} if @var{symbol} is an argument of a function.
+@end defun
+
+@defun symbol-constant? symbol
+Return @code{#t} if @var{symbol} is a constant.
+@end defun
+
+@defun symbol-function? symbol
+Return @code{#t} if @var{symbol} is a function or a method.
+@end defun
+
+@defun symbol-variable? symbol
+Return @code{#t} if @var{symbol} is a variable.
+@end defun
+
+@defun symbol-value symbol @r{[}#:frame frame@r{]}
+Compute the value of @var{symbol}, as a @code{<gdb:value>}. For
+functions, this computes the address of the function, cast to the
+appropriate type. If the symbol requires a frame in order to compute
+its value, then @var{frame} must be given. If @var{frame} is not
+given, or if @var{frame} is invalid, then an exception is thrown.
+@end defun
+
+@c TODO: line length
+@defun lookup-symbol name @r{[}#:block block@r{]} @r{[}#:domain domain@r{]}
+This function searches for a symbol by name. The search scope can be
+restricted to the parameters defined in the optional domain and block
+arguments.
+
+@var{name} is the name of the symbol. It must be a string. The
+optional @var{block} argument restricts the search to symbols visible
+in that @var{block}. The @var{block} argument must be a
+@code{<gdb:block>} object. If omitted, the block for the current frame
+is used. The optional @var{domain} argument restricts
+the search to the domain type. The @var{domain} argument must be a
+domain constant defined in the @code{(gdb)} module and described later
+in this chapter.
+
+The result is a list of two elements.
+The first element is a @code{<gdb:symbol>} object or @code{#f} if the symbol
+is not found.
+If the symbol is found, the second element is @code{#t} if the symbol
+is a field of a method's object (e.g., @code{this} in C@t{++}),
+otherwise it is @code{#f}.
+If the symbol is not found, the second element is @code{#f}.
+@end defun
+
+@defun lookup-global-symbol name @r{[}#:domain domain@r{]}
+This function searches for a global symbol by name.
+The search scope can be restricted by the domain argument.
+
+@var{name} is the name of the symbol. It must be a string.
+The optional @var{domain} argument restricts the search to the domain type.
+The @var{domain} argument must be a domain constant defined in the @code{(gdb)}
+module and described later in this chapter.
+
+The result is a @code{<gdb:symbol>} object or @code{#f} if the symbol
+is not found.
+@end defun
+
+The available domain categories in @code{<gdb:symbol>} are represented
+as constants in the @code{(gdb)} module:
+
+@table @code
+@findex SYMBOL_UNDEF_DOMAIN
+@item SYMBOL_UNDEF_DOMAIN
+This is used when a domain has not been discovered or none of the
+following domains apply. This usually indicates an error either
+in the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_VAR_DOMAIN
+@item SYMBOL_VAR_DOMAIN
+This domain contains variables, function names, typedef names and enum
+type values.
+@findex SYMBOL_STRUCT_DOMAIN
+@item SYMBOL_STRUCT_DOMAIN
+This domain holds struct, union and enum type names.
+@findex SYMBOL_LABEL_DOMAIN
+@item SYMBOL_LABEL_DOMAIN
+This domain contains names of labels (for gotos).
+@findex SYMBOL_VARIABLES_DOMAIN
+@item SYMBOL_VARIABLES_DOMAIN
+This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
+contains everything minus functions and types.
+@findex SYMBOL_FUNCTIONS_DOMAIN
+@item SYMBOL_FUNCTION_DOMAIN
+This domain contains all functions.
+@findex SYMBOL_TYPES_DOMAIN
+@item SYMBOL_TYPES_DOMAIN
+This domain contains all types.
+@end table
+
+The available address class categories in @code{<gdb:symbol>} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_LOC_UNDEF
+@item SYMBOL_LOC_UNDEF
+If this is returned by address class, it indicates an error either in
+the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_LOC_CONST
+@item SYMBOL_LOC_CONST
+Value is constant int.
+@findex SYMBOL_LOC_STATIC
+@item SYMBOL_LOC_STATIC
+Value is at a fixed address.
+@findex SYMBOL_LOC_REGISTER
+@item SYMBOL_LOC_REGISTER
+Value is in a register.
+@findex SYMBOL_LOC_ARG
+@item SYMBOL_LOC_ARG
+Value is an argument. This value is at the offset stored within the
+symbol inside the frame's argument list.
+@findex SYMBOL_LOC_REF_ARG
+@item SYMBOL_LOC_REF_ARG
+Value address is stored in the frame's argument list. Just like
+@code{LOC_ARG} except that the value's address is stored at the
+offset, not the value itself.
+@findex SYMBOL_LOC_REGPARM_ADDR
+@item SYMBOL_LOC_REGPARM_ADDR
+Value is a specified register. Just like @code{LOC_REGISTER} except
+the register holds the address of the argument instead of the argument
+itself.
+@findex SYMBOL_LOC_LOCAL
+@item SYMBOL_LOC_LOCAL
+Value is a local variable.
+@findex SYMBOL_LOC_TYPEDEF
+@item SYMBOL_LOC_TYPEDEF
+Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
+have this class.
+@findex SYMBOL_LOC_BLOCK
+@item SYMBOL_LOC_BLOCK
+Value is a block.
+@findex SYMBOL_LOC_CONST_BYTES
+@item SYMBOL_LOC_CONST_BYTES
+Value is a byte-sequence.
+@findex SYMBOL_LOC_UNRESOLVED
+@item SYMBOL_LOC_UNRESOLVED
+Value is at a fixed address, but the address of the variable has to be
+determined from the minimal symbol table whenever the variable is
+referenced.
+@findex SYMBOL_LOC_OPTIMIZED_OUT
+@item SYMBOL_LOC_OPTIMIZED_OUT
+The value does not actually exist in the program.
+@findex SYMBOL_LOC_COMPUTED
+@item SYMBOL_LOC_COMPUTED
+The value's address is a computed location.
+@end table
+
+@node Symbol Tables In Guile
+@subsubsection Symbol table representation in Guile.
+
+@cindex symbol tables in guile
+@tindex <gdb:symtab>
+@tindex <gdb:sal>
+
+Access to symbol table data maintained by @value{GDBN} on the inferior
+is exposed to Guile via two objects: @code{<gdb:sal>} (symtab-and-line) and
+@code{<gdb:symtab>}. Symbol table and line data for a frame is returned
+from the @code{frame-find-sal} @code{<gdb:frame>} procedure.
+@xref{Frames In Guile}.
+
+For more information on @value{GDBN}'s symbol table management, see
+@ref{Symbols, ,Examining the Symbol Table}.
+
+The following symtab-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun symtab? object
+Return @code{#t} if @var{object} is an object of type @code{<gdb:symtab>}.
+@end defun
+
+@defun symtab-valid? symtab
+Return @code{#t} if the @code{<gdb:symtab>} object is valid,
+@code{#f} if not. A @code{<gdb:symtab>} object becomes invalid when
+the symbol table it refers to no longer exists in @value{GDBN}.
+All other @code{<gdb:symtab>} procedures will throw an exception
+if it is invalid at the time the procedure is called.
+@end defun
+
+@defun symtab-filename symtab
+Return the symbol table's source filename.
+@end defun
+
+@defun symtab-fullname symtab
+Return the symbol table's source absolute file name.
+@end defun
+
+@defun symtab-objfile symtab
+Return the symbol table's backing object file. @xref{Objfiles In Guile}.
+@end defun
+
+@defun symtab-global-block symtab
+Return the global block of the underlying symbol table.
+@xref{Blocks In Guile}.
+@end defun
+
+@defun symtab-static-block symtab
+Return the static block of the underlying symbol table.
+@xref{Blocks In Guile}.
+@end defun
+
+The following symtab-and-line-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun sal? object
+Return @code{#t} if @var{object} is an object of type @code{<gdb:sal>}.
+@end defun
+
+@defun sal-valid? sal
+Return @code{#t} if @var{sal} is valid, @code{#f} if not.
+A @code{<gdb:sal>} object becomes invalid when the Symbol table object
+it refers to no longer exists in @value{GDBN}. All other
+@code{<gdb:sal>} procedures will throw an exception if it is
+invalid at the time the procedure is called.
+@end defun
+
+@defun sal-symtab sal
+Return the symbol table object (@code{<gdb:symtab>}) for @var{sal}.
+@end defun
+
+@defun sal-line sal
+Return the line number for @var{sal}.
+@end defun
+
+@defun sal-pc sal
+Return the start of the address range occupied by code for @var{sal}.
+@end defun
+
+@defun sal-last sal
+Return the end of the address range occupied by code for @var{sal}.
+@end defun
+
+@defun find-pc-line pc
+Return the @code{<gdb:sal>} object corresponding to the @var{pc} value.
+If an invalid value of @var{pc} is passed as an argument, then the
+@code{symtab} and @code{line} attributes of the returned @code{<gdb:sal>}
+object will be @code{#f} and 0 respectively.
+@end defun
+
+@node Breakpoints In Guile
+@subsubsection Manipulating breakpoints using Guile
+
+@cindex breakpoints in guile
+@tindex <gdb:breakpoint>
+
+Breakpoints in Guile are represented by objects of type
+@code{<gdb:breakpoint>}.
+
+The following breakpoint-related procedures are provided by the
+@code{(gdb)} module:
+
+@c TODO: line length
+@defun make-breakpoint location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]}
+Create a new breakpoint. @var{spec} is a string naming the
+location of the breakpoint, or an expression that defines a watchpoint.
+The contents can be any location recognized by the @code{break} command,
+or in the case of a watchpoint, by the @code{watch} command.
+
+The optional @var{type} denotes the breakpoint to create.
+This argument can be either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}.
+@var{type} defaults to @code{BP_BREAKPOINT}.
+
+The optional @var{wp-class} argument defines the class of watchpoint to
+create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is
+not provided, it is assumed to be a @code{WP_WRITE} class.
+
+The optional @var{internal} argument allows the breakpoint to become
+invisible to the user. The breakpoint will neither be reported when
+created, nor will it be listed in the output from @code{info breakpoints}
+(but will be listed with the @code{maint info breakpoints} command).
+If an internal flag is not provided, the breakpoint is visible
+(non-internal).
+
+When a watchpoint is created, @value{GDBN} will try to create a
+hardware assisted watchpoint. If successful, the type of the watchpoint
+is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT}
+for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ},
+and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}.
+If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}.
+
+The available types are represented by constants defined in the @code{gdb}
+module:
+
+@table @code
+@findex BP_BREAKPOINT
+@item BP_BREAKPOINT
+Normal code breakpoint.
+
+@findex BP_WATCHPOINT
+@item BP_WATCHPOINT
+Watchpoint breakpoint.
+
+@findex BP_HARDWARE_WATCHPOINT
+@item BP_HARDWARE_WATCHPOINT
+Hardware assisted watchpoint.
+This value cannot be specified when creating the breakpoint.
+
+@findex BP_READ_WATCHPOINT
+@item BP_READ_WATCHPOINT
+Hardware assisted read watchpoint.
+This value cannot be specified when creating the breakpoint.
+
+@findex BP_ACCESS_WATCHPOINT
+@item BP_ACCESS_WATCHPOINT
+Hardware assisted access watchpoint.
+This value cannot be specified when creating the breakpoint.
+@end table
+
+The available watchpoint types represented by constants are defined in the
+@code{(gdb)} module:
+
+@table @code
+@findex WP_READ
+@item WP_READ
+Read only watchpoint.
+
+@findex WP_WRITE
+@item WP_WRITE
+Write only watchpoint.
+
+@findex WP_ACCESS
+@item WP_ACCESS
+Read/Write watchpoint.
+@end table
+
+@end defun
+
+@defun breakpoint-delete! breakpoint
+Permanently delete @var{breakpoint}. This also invalidates the
+Guile @var{breakpoint} object. Any further attempt to access the
+object will throw an exception.
+@end defun
+
+@defun breakpoints
+Return a list of all breakpoints.
+Each element of the list is a @code{<gdb:breakpoint>} object.
+@end defun
+
+@defun breakpoint? object
+Return @code{#t} if @var{object} is a @code{<gdb:breakpoint>} object,
+and @code{#f} otherwise.
+@end defun
+
+@defun breakpoint-valid? breakpoint
+Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise.
+A @code{<gdb:breakpoint>} object can become invalid
+if the user deletes the breakpoint. In this case, the object still
+exists, but the underlying breakpoint does not. In the cases of
+watchpoint scope, the watchpoint remains valid even if execution of the
+inferior leaves the scope of that watchpoint.
+@end defun
+
+@defun breakpoint-number breakpoint
+Return the breakpoint's number --- the identifier used by
+the user to manipulate the breakpoint.
+@end defun
+
+@defun breakpoint-type breakpoint
+Return the breakpoint's type --- the identifier used to
+determine the actual breakpoint type or use-case.
+@end defun
+
+@defun breakpoint-visible? breakpoint
+Return @code{#t} if the breakpoint is visible to the user
+when hit, or when the @samp{info breakpoints} command is run.
+@end defun
+
+@defun breakpoint-location breakpoint
+Return the location of the breakpoint, as specified by
+the user. It is a string. If the breakpoint does not have a location
+(that is, it is a watchpoint) return @code{#f}.
+@end defun
+
+@defun breakpoint-expression breakpoint
+Return the breakpoint expression, as specified by the user. It is a string.
+If the breakpoint does not have an expression (the breakpoint is not a
+watchpoint) return @code{#f}.
+@end defun
+
+@defun breakpoint-enabled? breakpoint
+Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise.
+@end defun
+
+@defun set-breakpoint-enabled! breakpoint flag
+Set the enabled state of @var{breakpoint} to @var{flag}.
+If flag is @code{#f} it is disabled, otherwise it is enabled.
+@end defun
+
+@defun breakpoint-silent? breakpoint
+Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise.
+
+Note that a breakpoint can also be silent if it has commands and the
+first command is @code{silent}. This is not reported by the
+@code{silent} attribute.
+@end defun
+
+@defun set-breakpoint-silent! breakpoint flag
+Set the silent state of @var{breakpoint} to @var{flag}.
+If flag is @code{#f} the breakpoint is made silent,
+otherwise it is made non-silent (or noisy).
+@end defun
+
+@defun breakpoint-ignore-count breakpoint
+Return the ignore count for @var{breakpoint}.
+@end defun
+
+@defun set-breakpoint-ignore-count! breakpoint count
+Set the ignore count for @var{breakpoint} to @var{count}.
+@end defun
+
+@defun breakpoint-hit-count breakpoint
+Return hit count of @var{breakpoint}.
+@end defun
+
+@defun set-breakpoint-hit-count! breakpoint count
+Set the hit count of @var{breakpoint} to @var{count}.
+At present, @var{count} must be zero.
+@end defun
+
+@defun breakpoint-thread breakpoint
+Return the thread-id for thread-specific breakpoint @var{breakpoint}.
+Return #f if @var{breakpoint} is not thread-specific.
+@end defun
+
+@defun set-breakpoint-thread! breakpoint thread-id|#f
+Set the thread-id for @var{breakpoint} to @var{thread-id}.
+If set to @code{#f}, the breakpoint is no longer thread-specific.
+@end defun
+
+@defun breakpoint-task breakpoint
+If the breakpoint is Ada task-specific, return the Ada task id.
+If the breakpoint is not task-specific (or the underlying
+language is not Ada), return @code{#f}.
+@end defun
+
+@defun set-breakpoint-task! breakpoint task
+Set the Ada task of @var{breakpoint} to @var{task}.
+If set to @code{#f}, the breakpoint is no longer task-specific.
+@end defun
+
+@defun breakpoint-condition breakpoint
+Return the condition of @var{breakpoint}, as specified by the user.
+It is a string. If there is no condition, return @code{#f}.
+@end defun
+
+@defun set-breakpoint-condition! breakpoint condition
+Set the condition of @var{breakpoint} to @var{condition},
+which must be a string. If set to @code{#f} then the breakpoint
+becomes unconditional.
+@end defun
+
+@defun breakpoint-stop breakpoint
+Return the stop predicate of @var{breakpoint}.
+See @code{set-breakpoint-stop!} below in this section.
+@end defun
+
+@defun set-breakpoint-stop! breakpoint procedure|#f
+Set the stop predicate of @var{breakpoint}.
+@var{procedure} takes one argument: the <gdb:breakpoint> object.
+If this predicate is set to a procedure then it is invoked whenever
+the inferior reaches this breakpoint. If it returns @code{#t},
+or any non-@code{#f} value, then the inferior is stopped,
+otherwise the inferior will continue.
+
+If there are multiple breakpoints at the same location with a
+@code{stop} predicate, each one will be called regardless of the
+return status of the previous. This ensures that all @code{stop}
+predicates have a chance to execute at that location. In this scenario
+if one of the methods returns @code{#t} but the others return
+@code{#f}, the inferior will still be stopped.
+
+You should not alter the execution state of the inferior (i.e.@:, step,
+next, etc.), alter the current frame context (i.e.@:, change the current
+active frame), or alter, add or delete any breakpoint. As a general
+rule, you should not alter any data within @value{GDBN} or the inferior
+at this time.
+
+Example @code{stop} implementation:
+
+@smallexample
+(define (my-stop? bkpt)
+ (let ((int-val (parse-and-eval "foo")))
+ (value=? int-val 3)))
+(define bkpt (make-breakpoint "main.c:42"))
+(set-breakpoint-stop! bkpt my-stop?)
+@end smallexample
+@end defun
+
+@defun breakpoint-commands breakpoint
+Return the commands attached to @var{breakpoint} as a string,
+or @code{#f} if there are none.
+@end defun
+
+@node Lazy Strings In Guile
+@subsubsection Guile representation of lazy strings.
+
+@cindex lazy strings in guile
+@tindex <gdb:lazy-string>
+
+A @dfn{lazy string} is a string whose contents is not retrieved or
+encoded until it is needed.
+
+A @code{<gdb:lazy-string>} is represented in @value{GDBN} as an
+@code{address} that points to a region of memory, an @code{encoding}
+that will be used to encode that region of memory, and a @code{length}
+to delimit the region of memory that represents the string. The
+difference between a @code{<gdb:lazy-string>} and a string wrapped within
+a @code{<gdb:value>} is that a @code{<gdb:lazy-string>} will be treated
+differently by @value{GDBN} when printing. A @code{<gdb:lazy-string>} is
+retrieved and encoded during printing, while a @code{<gdb:value>}
+wrapping a string is immediately retrieved and encoded on creation.
+
+The following lazy-string-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun lazy-string? object
+Return @code{#t} if @var{object} is an object of type @code{<gdb:lazy-string>}.
+@end defun
+
+@defun lazy-string-address lazy-sring
+Return the address of @var{lazy-string}.
+@end defun
+
+@defun lazy-string-length lazy-string
+Return the length of @var{lazy-string} in characters. If the
+length is -1, then the string will be fetched and encoded up to the
+first null of appropriate width.
+@end defun
+
+@defun lazy-string-encoding lazy-string
+Return the encoding that will be applied to @var{lazy-string}
+when the string is printed by @value{GDBN}. If the encoding is not
+set, or contains an empty string, then @value{GDBN} will select the
+most appropriate encoding when the string is printed.
+@end defun
+
+@defun lazy-string-type lazy-string
+Return the type that is represented by @var{lazy-string}'s type.
+For a lazy string this will always be a pointer type. To
+resolve this to the lazy string's character type, use @code{type-target-type}.
+@xref{Types In Guile}.
+@end defun
+
+@defun lazy-string->value lazy-string
+Convert the @code{<gdb:lazy-string>} to a @code{<gdb:value>}. This value
+will point to the string in memory, but will lose all the delayed
+retrieval, encoding and handling that @value{GDBN} applies to a
+@code{<gdb:lazy-string>}.
+@end defun
+
+@node Architectures In Guile
+@subsubsection Guile representation of architectures
+
+@cindex guile architectures
+@tindex <gdb:arch>
+
+@value{GDBN} uses architecture specific parameters and artifacts in a
+number of its various computations. An architecture is represented
+by an instance of the @code{<gdb:arch>} class.
+
+The following architecture-related procedures are provided by the
+@code{(gdb)} module:
+
+@defun arch? object
+Return @code{#t} if @var{object} is an object of type @code{<gdb:arch>}.
+@end defun
+
+@defun current-arch
+Return the current architecture as a @code{<gdb:arch>} object.
+@end defun
+
+@defun arch-name arch
+Return the name (string value) of @code{<gdb:arch>} @var{arch}.
+@end defun
+
+@defun arch-charset arch
+Return name of target character set of @code{<gdb:arch>} @var{arch}.
+@end defun
+
+@defun arch-wide-charset
+Return name of target wide character set of @code{<gdb:arch>} @var{arch}.
+@end defun
+
+Each architecture provides a set of predefined types, obtained by
+the following functions.
+
+@defun arch-void-type arch
+Return the @code{<gdb:type>} object for a @code{void} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-char-type arch
+Return the @code{<gdb:type>} object for a @code{char} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-short-type arch
+Return the @code{<gdb:type>} object for a @code{short} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-int-type arch
+Return the @code{<gdb:type>} object for an @code{int} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-long-type arch
+Return the @code{<gdb:type>} object for a @code{long} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-schar-type arch
+Return the @code{<gdb:type>} object for a @code{signed char} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-uchar-type arch
+Return the @code{<gdb:type>} object for an @code{unsigned char} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-ushort-type arch
+Return the @code{<gdb:type>} object for an @code{unsigned short} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-uint-type arch
+Return the @code{<gdb:type>} object for an @code{unsigned int} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-ulong-type arch
+Return the @code{<gdb:type>} object for an @code{unsigned long} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-float-type arch
+Return the @code{<gdb:type>} object for a @code{float} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-double-type arch
+Return the @code{<gdb:type>} object for a @code{double} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-longdouble-type arch
+Return the @code{<gdb:type>} object for a @code{long double} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-bool-type arch
+Return the @code{<gdb:type>} object for a @code{bool} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-longlong-type arch
+Return the @code{<gdb:type>} object for a @code{long long} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-ulonglong-type arch
+Return the @code{<gdb:type>} object for an @code{unsigned long long} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-int8-type arch
+Return the @code{<gdb:type>} object for an @code{int8} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-uint8-type arch
+Return the @code{<gdb:type>} object for a @code{uint8} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-int16-type arch
+Return the @code{<gdb:type>} object for an @code{int16} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-uint16-type arch
+Return the @code{<gdb:type>} object for a @code{uint16} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-int32-type arch
+Return the @code{<gdb:type>} object for an @code{int32} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-uint32-type arch
+Return the @code{<gdb:type>} object for a @code{uint32} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-int64-type arch
+Return the @code{<gdb:type>} object for an @code{int64} type
+of architecture @var{arch}.
+@end defun
+
+@defun arch-uint64-type arch
+Return the @code{<gdb:type>} object for a @code{uint64} type
+of architecture @var{arch}.
+@end defun
+
+Example:
+
+@smallexample
+(gdb) guile (type-name (arch-uchar-type (current-arch)))
+"unsigned char"
+@end smallexample
+
+@node Disassembly In Guile
+@subsubsection Disassembly In Guile
+
+The disassembler can be invoked from Scheme code.
+Furthermore, the disassembler can take a Guile port as input,
+allowing one to disassemble from any source, and not just target memory.
+
+@c TODO: line length
+@defun arch-disassemble arch @var{start-pc} @r{[}#:port port@r{]} @r{[}#:offset offset@r{]} @r{[}#:size @var{size}@r{]} @r{[}#:count @var{count}@r{]})
+Return a list of disassembled instructions starting from the memory
+address @var{start-pc}.
+
+The optional argument @var{port} specifies the input port to read bytes from.
+If @var{port} is @code{#f} then bytes are read from target memory.
+
+The optional argument @var{offset} specifies the address offset of the
+first byte in @var{port}. This is useful, for example, when @var{port}
+specifies a @samp{bytevector} and you want the bytevector to be disassembled
+as if it came from that address. The @var{start-pc} passed to the reader
+for @var{port} is offset by the same amount.
+
+Example:
+@smallexample
+(gdb) guile (use-modules (rnrs io ports))
+(gdb) guile (define pc (value->integer (parse-and-eval "$pc")))
+(gdb) guile (define mem (open-memory #:start pc))
+(gdb) guile (define bv (get-bytevector-n mem 10))
+(gdb) guile (define bv-port (open-bytevector-input-port bv))
+(gdb) guile (define arch (current-arch))
+(gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc)
+(((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5)))
+@end smallexample
+
+The optional arguments @var{size} and
+@var{count} determine the number of instructions in the returned list.
+If either @var{size} or @var{count} is specified as zero, then
+no instructions are disassembled and an empty list is returned.
+If both the optional arguments @var{size} and @var{count} are
+specified, then a list of at most @var{count} disassembled instructions
+whose start address falls in the closed memory address interval from
+@var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned.
+If @var{size} is not specified, but @var{count} is specified,
+then @var{count} number of instructions starting from the address
+@var{start-pc} are returned. If @var{count} is not specified but
+@var{size} is specified, then all instructions whose start address
+falls in the closed memory address interval from @var{start-pc} to
+(@var{start-pc} + @var{size} - 1) are returned.
+If neither @var{size} nor @var{count} are specified, then a single
+instruction at @var{start-pc} is returned.
+
+Each element of the returned list is an alist (associative list)
+with the following keys:
+
+@table @code
+
+@item address
+The value corresponding to this key is a Guile integer of
+the memory address of the instruction.
+
+@item asm
+The value corresponding to this key is a string value which represents
+the instruction with assembly language mnemonics. The assembly
+language flavor used is the same as that specified by the current CLI
+variable @code{disassembly-flavor}. @xref{Machine Code}.
+
+@item length
+The value corresponding to this key is the length of the instruction in bytes.
+
+@end table
+@end defun
+
+@node I/O Ports in Guile
+@subsubsection I/O Ports in Guile
+
+@defun input-port
+Return @value{GDBN}'s input port as a Guile port object.
+@end defun
+
+@defun output-port
+Return @value{GDBN}'s output port as a Guile port object.
+@end defun
+
+@defun error-port
+Return @value{GDBN}'s error port as a Guile port object.
+@end defun
+
+@node Memory Ports in Guile
+@subsubsection Memory Ports in Guile
+
+@value{GDBN} provides a @code{port} interface to target memory.
+This allows Guile code to read/write target memory using Guile's port and
+bytevector functionality. The main routine is @code{open-memory} which
+returns a port object. One can then read/write memory using that object.
+
+@defun open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]}
+Return a port object that can be used for reading and writing memory.
+@var{mode} is the standard mode argument to Guile port open routines,
+except that it is restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}.
+For compatibility @samp{"b"} (binary) may also be present,
+but we ignore it: memory ports are binary only.
+The default is @samp{"r"}, read-only.
+
+The chunk of memory that can be accessed can be bounded.
+If both @var{start} and @var{size} are unspecified, all of memory can be
+accessed. If only @var{start} is specified, all of memory from that point
+on can be accessed. If only @var{size} if specified, all memory in the
+range [0,@var{size} can be accessed. If both are specified, all memory
+in the rane [@var{start},@var{start}+@var{size}) can be accessed.
+@end defun
+
+@defun memory-port?
+Return @code{#t} if @var{object} is an object of type @code{<gdb:memory-port>}.
+@end defun
+
+@defun memory-port-range memory-port
+Return the range of @code{<gdb:memory-port>} @var{memory-port} as a list
+of two elements: @code{(start end)}. The range is @var{start} to @var{end}
+inclusive.
+@end defun
+
+@defun memory-port-read-buffer-size memory-port
+Return the size of the read buffer of @code{<gdb:memory-port>}
+@var{memory-port}.
+@end defun
+
+@defun set-memory-port-read-buffer-size! memory-port size
+Set the size of the read buffer of @code{<gdb:memory-port>}
+@var{memory-port} to @var{size}. The result is unspecified.
+@end defun
+
+@defun memory-port-write-buffer-size memory-port
+Return the size of the write buffer of @code{<gdb:memory-port>}
+@var{memory-port}.
+@end defun
+
+@defun set-memory-port-write-buffer-size! memory-port size
+Set the size of the write buffer of @code{<gdb:memory-port>}
+@var{memory-port} to @var{size}. The result is unspecified.
+@end defun
+
+A memory port is closed like any other port, with @code{close-port}.
+
+Combined with Guile's @code{bytevectors}, memory ports provide a lot
+of utility. For example, to fill a buffer of 10 integers in memory,
+one can do something like the following.
+
+@smallexample
+;; In the program: int buffer[10];
+(use-modules (rnrs bytevectors))
+(use-modules (rnrs io ports))
+(define addr (parse-and-eval "buffer"))
+(define n 10)
+(define byte-size (* n 4))
+(define mem-port (open-memory #:mode "r+" #:start
+ (value->integer addr) #:size byte-size))
+(define byte-vec (make-bytevector byte-size))
+(do ((i 0 (+ i 1)))
+ ((>= i n))
+ (bytevector-s32-native-set! byte-vec (* i 4) (* i 42)))
+(put-bytevector mem-port byte-vec)
+(close-port mem-port)
+@end smallexample
+
+@node Iterators In Guile
+@subsubsection Iterators In Guile
+
+@cindex guile iterators
+@tindex <gdb:iterator>
+
+An experimental iterator facility is provided to allow, for example,
+iterating over the set of program symbols without having to first
+construct a list of all of them. Scheme has support for iterators via,
+for example, SRFI 41 and SRFI 45. Hopefully something efficient and
+agreeable can be worked out that uses them or something else.
+
+@defun make-iterator
+A @code{<gdb:iterator>} object is constructed with the @code{make-iterator}
+procedure. It takes three arguments: the object to be iterated over,
+an object to record the progress of the iteration, and a procedure to
+return the next element in the iteration, or an implementation chosen value
+to denote the end of iteration.
+
+A trivial example for illustration's sake:
+
+@smallexample
+(use-modules (gdb experimental))
+(define my-list (list 1 2 3))
+(define end-marker #f)
+(define iter (make-iterator my-list my-list
+ (lambda (iter)
+ (let ((l (iterator-progress iter)))
+ (if (eq? l '())
+ end-marker
+ (begin
+ (set-iterator-progress! iter (cdr l))
+ (car l)))))))
+@end smallexample
+
+It is not expected that iterators will be used like that,
+that was just for illustration's sake.
+Here is a slightly more realistic example, which computes a list of all the
+functions in @code{my-global-block}.
+
+@smallexample
+(use-modules (gdb experimental))
+(define this-sal (find-pc-line (frame-pc (selected-frame))))
+(define this-symtab (sal-symtab this-sal))
+(define this-global-block (symtab-global-block this-symtab))
+(define syms-iter (make-block-symbols-iterator this-global-block))
+(define functions (iterator-filter symbol-function? syms-iter #f))
+@end smallexample
+@end defun
+
+These functions are provided to assist in writing the @code{next!} procedure:
+
+@table @code
+@item iterator-object
+Return the first argument that was passed to @code{make-iterator}.
+This is the object being iterated over.
+
+@item iterator-progress
+Return the object tracking iteration progress.
+
+@item set-iterator-progress!
+Set the object tracking iteration progress.
+
+@item iterator-next!
+Invoke the procedure that was the third argument to @code{make-iterator},
+passing it one argument, the @code{<gdb:iterator>} object.
+The result is either the next element in the iteration, or and end
+marker as implemented by the @code{next!} procedure.
+@end table
+
+@node Guile Auto-loading
+@subsection Guile Auto-loading
+@cindex guile auto-loading
+
+When a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library),
+@value{GDBN} will look for Guile support scripts in two ways:
+@file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section.
+@xref{Auto-loading extensions}.
+
+The auto-loading feature is useful for supplying application-specific
+debugging commands and scripts.
+
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
+
+@table @code
+@anchor{set auto-load guile-scripts}
+@kindex set auto-load guile-scripts
+@item set auto-load guile-scripts [on|off]
+Enable or disable the auto-loading of Guile scripts.
+
+@anchor{show auto-load guile-scripts}
+@kindex show auto-load guile-scripts
+@item show auto-load guile-scripts
+Show whether auto-loading of Guile scripts is enabled or disabled.
+
+@anchor{info auto-load guile-scripts}
+@kindex info auto-load guile-scripts
+@cindex print list of auto-loaded Guile scripts
+@item info auto-load guile-scripts [@var{regexp}]
+Print the list of all Guile scripts that @value{GDBN} auto-loaded.
+
+Also printed is the list of Guile scripts that were mentioned in
+the @code{.debug_gdb_scripts} section and were not found.
+This is useful because their names are not printed when @value{GDBN}
+tries to load them and fails. There may be many of them, and printing
+an error message for each one is problematic.
+
+If @var{regexp} is supplied only Guile scripts with matching names are printed.
+
+Example:
+
+@smallexample
+(gdb) info auto-load guile-scripts
+Loaded Script
+Yes scm-section-script.scm
+ full name: /tmp/scm-section-script.scm
+No my-foo-pretty-printers.scm
+@end smallexample
+@end table
+
+When reading an auto-loaded file, @value{GDBN} sets the
+@dfn{current objfile}. This is available via the @code{current-objfile}
+procedure (@pxref{Objfiles In Guile}). This can be useful for
+registering objfile-specific pretty-printers.
+
+@node Guile Modules
+@subsection Guile Modules
+@cindex guile modules
+
+@value{GDBN} comes with several modules to assist writing Guile code.
+
+@menu
+* Guile Printing Module:: Building and registering pretty-printers
+* Guile Types Module:: Utilities for working with types
+@end menu
+
+@node Guile Printing Module
+@subsubsection Guile Printing Module
+@cindex (gdb printing)
+
+This module provides a collection of utilities for working with
+pretty-printers.
+
+Usage:
+
+@smallexample
+(use-modules (gdb printing))
+@end smallexample
+
+@table @code
+@item prepend-pretty-printer! @var{obj} @var{printer}
+Add @var{printer} to the front of the list of pretty-printers for @var{obj}.
+@var{obj} must either be a @code{<gdb:objfile>} object or @code{#f} in which
+case @var{printer} is added to the global list of printers.
+
+@item append-pretty-printer! @var{obj} @var{printer}
+Add @var{printer} to the end of the list of pretty-printers for @var{obj}.
+@var{obj} must either be a @code{<gdb:objfile>} object or @code{#f} in which
+case @var{printer} is added to the global list of printers.
+@end table
+
+@node Guile Types Module
+@subsubsection Guile Types Module
+@cindex (gdb types)
+
+This module provides a collection of utilities for working with
+@code{<gdb:type>} objects.
+
+Usage:
+
+@smallexample
+(use-modules (gdb types))
+@end smallexample
+
+@table @code
+@item get-basic-type @var{type}
+Return @var{type} with const and volatile qualifiers stripped,
+and with typedefs and C@t{++} references converted to the underlying type.
+
+C@t{++} example:
+
+@smallexample
+typedef const int const_int;
+const_int foo (3);
+const_int& foo_ref (foo);
+int main () @{ return 0; @}
+@end smallexample
+
+Then in gdb:
+
+@smallexample
+(gdb) start
+(gdb) guile (use-modules ((gdb) (gdb types)))
+(gdb) guile (define foo-ref (parse-and-eval "foo_ref"))
+(gdb) guile (get-basic-type (value-type foo-ref))
+int
+@end smallexample
+
+@item type-has-field-deep? @var{type} @var{field}
+Return @code{#t} if @var{type}, assumed to be a type with fields
+(e.g., a structure or union), has field @var{field}.
+This searches baseclasses, whereas @code{type-has-field?} does not.
+
+@item make-enum-hashtable @var{enum-type}
+Return a Guile hash table produced from @var{enum-type}.
+Elements in the hash table are referenced with @code{hashq-ref}.
+@end table
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2013-12-24 19:03 [PATCH v1 02/36] Guile extension language: doc additions Doug Evans
@ 2013-12-25 19:27 ` Eli Zaretskii
2014-01-03 21:31 ` Ludovic Courtès
2014-01-18 20:06 ` Doug Evans
0 siblings, 2 replies; 35+ messages in thread
From: Eli Zaretskii @ 2013-12-25 19:27 UTC (permalink / raw)
To: Doug Evans; +Cc: gdb-patches
> Date: Tue, 24 Dec 2013 11:02:24 -0800
> From: Doug Evans <xdje42@gmail.com>
>
> This patch has the doc additions.
> There's still some to be written, but I think it's in good enough shape
> to get feedback on.
Thanks.
> +Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
I'm not sure we should say this in the manual. Would you like to keep
track of others testing other versions and update this as they report
to you? I don't think so.
It might be good for NEWS, though.
> +The implementation uses Guile's @code{smob} (small object)
^^^^^^^^^^^^
This should be in @dfn, as it's new terminology. Also, an index entry
about that would be nice.
> +@cindex guile directory
I think "guile scripts directory" is a better index entry.
> +@item guile @r{[}@var{command}@r{]}
> +@itemx gu @r{[}@var{command}@r{]}
> +The @code{guile} command can be used to evaluate a Scheme expression.
If it's a Scheme expression, then why do you use "command" in the
@item? why not "scheme-expression"?
> +See the Guile documentation for a description of this function.
A cross-reference to the appropriate node in the Guile manual would be
good there.
> +Guile's history mechanism uses the same naming as @value{GDBN}'s,
> +namely the user of dollar-variables (e.g., $1, $2, etc.).
> +However, the values are independent, @code{$1} in Guile is not the
> +same value as @code{$1} in @value{GDBN}.
This is not clear enough. I'm guessing you wanted to say that results
of evaluations in Guile and in GDB are counted separately? If so, I
suggest to say just that.
> +@value{GDBN} is not thread-safe. If your Guile program uses multiple
> +threads, you must be careful to only call @value{GDBN}-specific
> +functions in the main @value{GDBN} thread.
What is "the main GDB thread" here?
> +The rest of this manual assumes the @code{gdb} module has been imported
> +without any prefix. See the Guile documentation for @code{use-modules}
> +for more information.
Again, a cross-reference would be good here.
> +By default, any output produced by @var{command} is sent to
> +@value{GDBN}'s standard output.
What happens if logging has been turned on?
> +@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
> +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
> +history, nor is the reverse true.
See comment about this above. Also, which history are you talking
about here: the one from Guile evaluation or the one from GDB?
> +@node Guile Configuration
> +@subsubsection Guile Configuration
An index entry would be nice here.
> +@defun data-directory
> +Return a string containing @value{GDBN}'s data directory.
Should we mention that this string is in UTF-8 (I think) encoding?
> +@defun make-exception key args
> +Return a @code{<gdb:exception>} object.
> +@var{key} and @var{args} are the standard Guile parameters of an exception.
> +See Guile documentation for more information.
^^^^^^^^^^^^^^^^^^^^^^^
Cross-reference, please.
> +@defun exception? object
> +Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
And #f otherwise, I guess.
> +@value{GDBN} does not memoize @code{<gdb:value>} objects.
Why not?
> +Therefore @code{eq?} does not work as expected.
> +However @code{equal?} does work.
> +
> +@smallexample
> +(gdb) guile (eq? (make-value 1) (make-value 1))
> +$1 = #f
> +(gdb) guile (equal? (make-value 1) (make-value 1))
> +$1 = #t
> +@end smallexample
Wouldn't this be confusing for Scheme programmers? Is it terribly
hard to make eq? work?
> +@defun value? object
> +Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
And #f otherwise?
> +Many Scheme values can be converted directly to a @code{<gdb:value>} via
> +with this procedure.
Either "via" or 'with", but not both.
> +A Scheme boolean is converted to @var{type} if provided, otherwise
You already described how "type" is handled, no need to repeat that
(here and elsewhere in this part).
> +If @var{type} is not provided,
> +a Scheme real is converted to the C @code{double} type for the
> +current architecture.
Isn't Guile built with libgmp? If so, doesn't it support floats
which, when converted to a double, will lose accuracy?
Also, what about long double, if it is supported by the host?
> +A Scheme string is converted to a target string, using the current
> +target encoding.
What if target encoding doesn't support some of the characters in the
string?
And what does "target string" mean anyway? A string in C and a string
in Fortran are two different objects, no?
> +If @var{value} is a Scheme bytevector and @var{type} is provided,
> +@var{value} must be the same size, in bytes, of values of type @var{type},
> +and the result is essentially created by using @code{memcpy}.
Can type be 'double' in this case? If so, what happens with denormals
and such likes that are created by such a memcpy? Wouldn't it be
better to allow only integer types here?
> +If @var{value} is a Scheme bytevector and @var{type} is not provided,
> +the result is an array of type @code{uint8} of the same length.
I would suggest using 'unsigned char' instead of uint8.
> +A similar function @code{value-referenced-value} exists which also
> +returns @code{<gdb:value>} objects corresonding to the values pointed to
> +by pointer values (and additionally, values referenced by reference
> +values). However, the behavior of @code{value-dereference}
> +differs from @code{value-referenced-value} by the fact that the
> +behavior of @code{value-dereference} is identical to applying the C
> +unary operator @code{*} on a given value. For example, consider a
> +reference to a pointer @code{ptrref}, declared in your C@t{++} program
> +as
> +
> +@smallexample
> +typedef int *intptr;
> +...
> +int val = 10;
> +intptr ptr = &val;
> +intptr &ptrref = ptr;
> +@end smallexample
Here and below you describe 2 related functions, and explain how they
are different twice, each explanation is part of its @defun. This in
effect says the same things twice slightly differently, and is thus
confusing.
Instead, I suggest to provide a concise description of both functions,
and then explain their differences only once.
> +Each element of list @var{arg-list} must be a <gdb:value> object or an object
> +that can be converted to one.
^^^^^^^^^^^^^^^^
"converted to a value" is less ambiguous.
> +For C-like languages, a value is a string if it is a pointer to or an
> +array of characters or ints.
"Array of ints" meaning a wchar_t string? If so, they might not be
ints on some platforms (e.g., Windows).
> +The optional @var{errors} argument is either @code{"strict"}
> +or @code{"replace"}. A value of @code{"strict"} corresponds to
> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
Suggest a cross-reference to Guile documentation here.
> +If the optional @var{length} argument is given, the string will be
> +fetched and encoded to the length of characters specified. If
> +the @var{length} argument is not provided, the string will be fetched
> +and encoded until a null of appropriate width is found.
Isn't this null termination description skewed towards C-like
languages? Aren't there languages where strings don't have to be
null-terminated?
> +@defun value-max a b
> +@end defun
> +
> +@defun value-max a b
> +@end defun
One of these should be value-min, I presume.
> +@table @code
> +@findex TYPE_CODE_PTR
> +@item TYPE_CODE_PTR
Using @ftable here would have saved you from the need to type @findex
for each @item.
> +@findex TYPE_CODE_INTERNAL_FUNCTION
> +@item TYPE_CODE_INTERNAL_FUNCTION
> +A function internal to @value{GDBN}. This is the type used to represent
> +convenience functions.
A cross-reference to where convenience functions are described would
be nice here.
> +@anchor{Fields of a Type in Guile}
Why capitalized words?
> +@node Guile Pretty Printing API
> +@subsubsection Guile Pretty Printing API
@cindex missing here.
> +@node Selecting Guile Pretty-Printers
> +@subsubsection Selecting Guile Pretty-Printers
@cindex.
> +For compatibility @samp{"b"} (binary) may also be present,
> +but we ignore it: memory ports are binary only.
Which means strings read from memory cannot be decoded?
> +on can be accessed. If only @var{size} if specified, all memory in the
> +range [0,@var{size} can be accessed. If both are specified, all memory
^^^^^^^^^^^^^
Missing closing paren.
> +@node Guile Printing Module
> +@subsubsection Guile Printing Module
> +@cindex (gdb printing)
Is this really a useful index entry?
> +@node Guile Types Module
> +@subsubsection Guile Types Module
> +@cindex (gdb types)
Likewise here.
Thanks again for doing this.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2013-12-25 19:27 ` Eli Zaretskii
@ 2014-01-03 21:31 ` Ludovic Courtès
2014-01-04 7:12 ` Eli Zaretskii
` (2 more replies)
2014-01-18 20:06 ` Doug Evans
1 sibling, 3 replies; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-03 21:31 UTC (permalink / raw)
To: gdb-patches
Eli Zaretskii <eliz@gnu.org> skribis:
>> +Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
>
> I'm not sure we should say this in the manual.
In practice the parts that are used (mostly the C API) have seen few
additions over 2.0, so it’s likely that it would work with any 2.0.x.
>> +The implementation uses Guile's @code{smob} (small object)
> ^^^^^^^^^^^^
> This should be in @dfn, as it's new terminology.
Better yet:
(@pxref{Smobs,,, guile, GNU Guile Reference Manual})
[...]
>> +Therefore @code{eq?} does not work as expected.
>> +However @code{equal?} does work.
>> +
>> +@smallexample
>> +(gdb) guile (eq? (make-value 1) (make-value 1))
>> +$1 = #f
>> +(gdb) guile (equal? (make-value 1) (make-value 1))
>> +$1 = #t
>> +@end smallexample
>
> Wouldn't this be confusing for Scheme programmers? Is it terribly
> hard to make eq? work?
We discussed this before, and I think that’s fine if it’s not doable, as
long as it’s clearly documented.
However, rather than “does not work as expected†(which could be
misleading), what about something like:
‘make-value’ always returns a fresh object. Therefore,
@code{<gdb:value>} returned by different calls to ‘make-value’ are
usually different:
@example
(eq? (make-value 1) (make-value 1))
@result{} #f
(equal? (make-value 1) (make-value 1))
@result{} #t
@end example
>> +@defun value? object
What about distinguishing Scheme functions, like:
@deffn {Scheme Procedure} value? object
>> +If @var{type} is not provided,
>> +a Scheme real is converted to the C @code{double} type for the
>> +current architecture.
>
> Isn't Guile built with libgmp? If so, doesn't it support floats
> which, when converted to a double, will lose accuracy?
Guile uses GMP, but GMP is for integers (bignums).
Real numbers in Guile (numbers for which ‘real?’ returns #t) are either
doubles or rationals–called “inexact†and “exactâ€, respectively (info
"(guile) Real and Rational Numbers"):
scheme@(guile-user)> (real? 3.14)
$2 = #t
scheme@(guile-user)> (real? 22/7)
$3 = #t
scheme@(guile-user)> 22/7
$4 = 22/7
scheme@(guile-user)> (exact->inexact 22/7)
$5 = 3.142857142857143
There’s loss of accuracy only when converting a rational to a double.
>> +A Scheme string is converted to a target string, using the current
>> +target encoding.
>
> What if target encoding doesn't support some of the characters in the
> string?
Guile’s behavior can be controlled with
‘%default-port-conversion-strategy’: it can raise an exception, or
substitute any characters that could not be converted, or escape them
(info "(guile) Ports").
Perhaps this should be briefly mentioned, with a cross-ref.
>> +The optional @var{errors} argument is either @code{"strict"}
>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>
> Suggest a cross-reference to Guile documentation here.
Agreed. Also, Guile talks of “conversion strategy†and “conversion
error handlerâ€, with values ‘error’, ‘substitute’, and ‘escape’ (at the
Scheme level), and I’d recommend sticking to those names and terminology.
>> +If the optional @var{length} argument is given, the string will be
>> +fetched and encoded to the length of characters specified. If
>> +the @var{length} argument is not provided, the string will be fetched
>> +and encoded until a null of appropriate width is found.
>
> Isn't this null termination description skewed towards C-like
> languages? Aren't there languages where strings don't have to be
> null-terminated?
Yes, and that’s when LENGTH should be provided, AIUI.
(I agree with most of Eli’s other suggestions.)
Thanks to both of you,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-03 21:31 ` Ludovic Courtès
@ 2014-01-04 7:12 ` Eli Zaretskii
2014-01-04 11:57 ` Ludovic Courtès
2014-01-18 20:16 ` Doug Evans
2014-01-18 22:32 ` Doug Evans
2 siblings, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-04 7:12 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: gdb-patches
> From: ludo@gnu.org (Ludovic Courtès)
> Date: Fri, 03 Jan 2014 22:30:54 +0100
>
> >> +The implementation uses Guile's @code{smob} (small object)
> > ^^^^^^^^^^^^
> > This should be in @dfn, as it's new terminology.
>
> Better yet:
>
> (@pxref{Smobs,,, guile, GNU Guile Reference Manual})
Yes, a cross-reference in addition to @dfn is the best.
> However, rather than “does not work as expected†(which could be
> misleading), what about something like:
>
> ‘make-value’ always returns a fresh object. Therefore,
> @code{<gdb:value>} returned by different calls to ‘make-value’ are
> usually different:
>
> @example
> (eq? (make-value 1) (make-value 1))
> @result{} #f
>
> (equal? (make-value 1) (make-value 1))
> @result{} #t
> @end example
This is better, thanks.
> >> +@defun value? object
>
> What about distinguishing Scheme functions, like:
>
> @deffn {Scheme Procedure} value? object
If it's important (is it?), then yes.
> >> +If @var{type} is not provided,
> >> +a Scheme real is converted to the C @code{double} type for the
> >> +current architecture.
> >
> > Isn't Guile built with libgmp? If so, doesn't it support floats
> > which, when converted to a double, will lose accuracy?
>
> Guile uses GMP, but GMP is for integers (bignums).
What about long double support?
> >> +A Scheme string is converted to a target string, using the current
> >> +target encoding.
> >
> > What if target encoding doesn't support some of the characters in the
> > string?
>
> Guile’s behavior can be controlled with
> ‘%default-port-conversion-strategy’: it can raise an exception, or
> substitute any characters that could not be converted, or escape them
> (info "(guile) Ports").
>
> Perhaps this should be briefly mentioned, with a cross-ref.
It should, because the issue will certainly arise, especially since
(AFAIU) Guile prefers UTF-8.
> >> +The optional @var{errors} argument is either @code{"strict"}
> >> +or @code{"replace"}. A value of @code{"strict"} corresponds to
> >> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
> >> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
> >
> > Suggest a cross-reference to Guile documentation here.
>
> Agreed. Also, Guile talks of “conversion strategy†and “conversion
> error handlerâ€, with values ‘error’, ‘substitute’, and ‘escape’ (at the
> Scheme level), and I’d recommend sticking to those names and terminology.
Right.
> >> +If the optional @var{length} argument is given, the string will be
> >> +fetched and encoded to the length of characters specified. If
> >> +the @var{length} argument is not provided, the string will be fetched
> >> +and encoded until a null of appropriate width is found.
> >
> > Isn't this null termination description skewed towards C-like
> > languages? Aren't there languages where strings don't have to be
> > null-terminated?
>
> Yes, and that’s when LENGTH should be provided, AIUI.
Then I guess the above should say that explicitly. But it would be
nice if GDB could support strings in languages that don't
null-terminate even without LENGTH.
Thanks.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-04 7:12 ` Eli Zaretskii
@ 2014-01-04 11:57 ` Ludovic Courtès
2014-01-04 14:41 ` Eli Zaretskii
2014-01-18 20:36 ` Doug Evans
0 siblings, 2 replies; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-04 11:57 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
Eli Zaretskii <eliz@gnu.org> skribis:
>> >> +@defun value? object
>>
>> What about distinguishing Scheme functions, like:
>>
>> @deffn {Scheme Procedure} value? object
>
> If it's important (is it?), then yes.
I think I would find it clearer, to someone who skims over the manual.
>> >> +If @var{type} is not provided,
>> >> +a Scheme real is converted to the C @code{double} type for the
>> >> +current architecture.
>> >
>> > Isn't Guile built with libgmp? If so, doesn't it support floats
>> > which, when converted to a double, will lose accuracy?
>>
>> Guile uses GMP, but GMP is for integers (bignums).
>
> What about long double support?
Guile doesn’t support it out of the box.
If needed, it could easily be implemented as an extension: one would use
a SMOB to wrap long doubles and pass them to Scheme, and possibly define
methods for ‘+’, ‘-’, etc. for objects of this type.
Of course, this wouldn’t be terribly efficient, but that’s not so
important here I think; what matters is that it would allow ‘long
double’ values to be passed around without loss of accuracy.
That said, my feeling is that leaving things as is (with long doubles
cast to doubles) may prove to be sufficient for most practical uses of
GDB.
WDYT?
>> >> +A Scheme string is converted to a target string, using the current
>> >> +target encoding.
>> >
>> > What if target encoding doesn't support some of the characters in the
>> > string?
>>
>> Guile’s behavior can be controlled with
>> ‘%default-port-conversion-strategy’: it can raise an exception, or
>> substitute any characters that could not be converted, or escape them
>> (info "(guile) Ports").
>>
>> Perhaps this should be briefly mentioned, with a cross-ref.
>
> It should, because the issue will certainly arise, especially since
> (AFAIU) Guile prefers UTF-8.
Right. (UTF-8 is just the default encoding for source code; it’s not
“preferred” in any other way.)
>> >> +If the optional @var{length} argument is given, the string will be
>> >> +fetched and encoded to the length of characters specified. If
>> >> +the @var{length} argument is not provided, the string will be fetched
>> >> +and encoded until a null of appropriate width is found.
>> >
>> > Isn't this null termination description skewed towards C-like
>> > languages? Aren't there languages where strings don't have to be
>> > null-terminated?
>>
>> Yes, and that’s when LENGTH should be provided, AIUI.
>
> Then I guess the above should say that explicitly. But it would be
> nice if GDB could support strings in languages that don't
> null-terminate even without LENGTH.
Agreed (I had misread the description above as saying that, if LENGTH is
provided, then the string is *not* assumed to be nul-terminated.)
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-04 11:57 ` Ludovic Courtès
@ 2014-01-04 14:41 ` Eli Zaretskii
2014-01-04 17:42 ` Ludovic Courtès
2014-01-18 20:36 ` Doug Evans
1 sibling, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-04 14:41 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: gdb-patches
> From: ludo@gnu.org (Ludovic Courtès)
> Cc: gdb-patches@sourceware.org
> Date: Sat, 04 Jan 2014 12:57:21 +0100
>
> > What about long double support?
>
> Guile doesn’t support it out of the box.
>
> If needed, it could easily be implemented as an extension: one would use
> a SMOB to wrap long doubles and pass them to Scheme, and possibly define
> methods for ‘+’, ‘-’, etc. for objects of this type.
>
> Of course, this wouldn’t be terribly efficient, but that’s not so
> important here I think; what matters is that it would allow ‘long
> double’ values to be passed around without loss of accuracy.
>
> That said, my feeling is that leaving things as is (with long doubles
> cast to doubles) may prove to be sufficient for most practical uses of
> GDB.
>
> WDYT?
Well, GDB supports long double if the target does, so I thought it
would be a pity to lose that when working with Guile. But maybe I
misunderstand something, and this isn't a real problem.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-04 14:41 ` Eli Zaretskii
@ 2014-01-04 17:42 ` Ludovic Courtès
2014-01-04 20:00 ` Eli Zaretskii
0 siblings, 1 reply; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-04 17:42 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
Eli Zaretskii <eliz@gnu.org> skribis:
>> From: ludo@gnu.org (Ludovic Courtès)
>> Cc: gdb-patches@sourceware.org
>> Date: Sat, 04 Jan 2014 12:57:21 +0100
>>
>> > What about long double support?
>>
>> Guile doesn’t support it out of the box.
>>
>> If needed, it could easily be implemented as an extension: one would use
>> a SMOB to wrap long doubles and pass them to Scheme, and possibly define
>> methods for ‘+’, ‘-’, etc. for objects of this type.
>>
>> Of course, this wouldn’t be terribly efficient, but that’s not so
>> important here I think; what matters is that it would allow ‘long
>> double’ values to be passed around without loss of accuracy.
>>
>> That said, my feeling is that leaving things as is (with long doubles
>> cast to doubles) may prove to be sufficient for most practical uses of
>> GDB.
>>
>> WDYT?
>
> Well, GDB supports long double if the target does, so I thought it
> would be a pity to lose that when working with Guile.
We’re talking about ‘make-value’ here, which does allow users to create
a ‘long double’ value, AIUI.
What’s lost is that users can only inject in the debuggee values with
the accuracy of a ‘double’.
This is a theoretical limitation, but I’m tempted to think that this is
rarely (if ever) a concern in practice.
How do the Python bindings handle this?
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-04 17:42 ` Ludovic Courtès
@ 2014-01-04 20:00 ` Eli Zaretskii
2014-01-16 4:20 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-04 20:00 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: gdb-patches
> From: ludo@gnu.org (Ludovic Courtès)
> Cc: gdb-patches@sourceware.org
> Date: Sat, 04 Jan 2014 18:42:44 +0100
>
> > Well, GDB supports long double if the target does, so I thought it
> > would be a pity to lose that when working with Guile.
>
> We’re talking about ‘make-value’ here, which does allow users to create
> a ‘long double’ value, AIUI.
>
> What’s lost is that users can only inject in the debuggee values with
> the accuracy of a ‘double’.
>
> This is a theoretical limitation, but I’m tempted to think that this is
> rarely (if ever) a concern in practice.
>
> How do the Python bindings handle this?
I don't know. Maybe someone else could chime in.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-04 20:00 ` Eli Zaretskii
@ 2014-01-16 4:20 ` Doug Evans
0 siblings, 0 replies; 35+ messages in thread
From: Doug Evans @ 2014-01-16 4:20 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Ludovic Courtès, gdb-patches
Eli Zaretskii <eliz@gnu.org> writes:
>> From: ludo@gnu.org (Ludovic Courtès)
>> Cc: gdb-patches@sourceware.org
>> Date: Sat, 04 Jan 2014 18:42:44 +0100
>>
>> > Well, GDB supports long double if the target does, so I thought it
>> > would be a pity to lose that when working with Guile.
>>
>> We’re talking about ‘make-value’ here, which does allow users to create
>> a ‘long double’ value, AIUI.
>>
>> What’s lost is that users can only inject in the debuggee values with
>> the accuracy of a ‘double’.
>>
>> This is a theoretical limitation, but I’m tempted to think that this is
>> rarely (if ever) a concern in practice.
>>
>> How do the Python bindings handle this?
>
> I don't know. Maybe someone else could chime in.
The python code in gdb just uses doubles.
There's nothing precluding supporting better precision in the future,
but for this pass I'd like to keep it simple.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2013-12-25 19:27 ` Eli Zaretskii
2014-01-03 21:31 ` Ludovic Courtès
@ 2014-01-18 20:06 ` Doug Evans
2014-01-18 20:24 ` Eli Zaretskii
1 sibling, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-18 20:06 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
On Wed, Dec 25, 2013 at 11:26 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Tue, 24 Dec 2013 11:02:24 -0800
>> From: Doug Evans <xdje42@gmail.com>
>>
>> This patch has the doc additions.
>> There's still some to be written, but I think it's in good enough shape
>> to get feedback on.
>
> Thanks.
>
>> +Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
>
> I'm not sure we should say this in the manual. Would you like to keep
> track of others testing other versions and update this as they report
> to you? I don't think so.
>
> It might be good for NEWS, though.
Done.
>> +The implementation uses Guile's @code{smob} (small object)
> ^^^^^^^^^^^^
> This should be in @dfn, as it's new terminology. Also, an index entry
> about that would be nice.
Done. Plus I added reference to the Guile docs for smobs.
>> +@cindex guile directory
>
> I think "guile scripts directory" is a better index entry.
Done.
>> +@item guile @r{[}@var{command}@r{]}
>> +@itemx gu @r{[}@var{command}@r{]}
>> +The @code{guile} command can be used to evaluate a Scheme expression.
>
> If it's a Scheme expression, then why do you use "command" in the
> @item? why not "scheme-expression"?
Done.
>> +See the Guile documentation for a description of this function.
>
> A cross-reference to the appropriate node in the Guile manual would be
> good there.
Done.
>> +Guile's history mechanism uses the same naming as @value{GDBN}'s,
>> +namely the user of dollar-variables (e.g., $1, $2, etc.).
>> +However, the values are independent, @code{$1} in Guile is not the
>> +same value as @code{$1} in @value{GDBN}.
>
> This is not clear enough. I'm guessing you wanted to say that results
> of evaluations in Guile and in GDB are counted separately? If so, I
> suggest to say just that.
Done.
>> +@value{GDBN} is not thread-safe. If your Guile program uses multiple
>> +threads, you must be careful to only call @value{GDBN}-specific
>> +functions in the main @value{GDBN} thread.
>
> What is "the main GDB thread" here?
I think the current wording is sufficient.
I'm not sure what else to say, and Python says something similar.
Python also has an example which may help.
There's no example for Guile (yet) because the example
uses functionality not implemented yet (events).
>> +The rest of this manual assumes the @code{gdb} module has been imported
>> +without any prefix. See the Guile documentation for @code{use-modules}
>> +for more information.
>
> Again, a cross-reference would be good here.
Done.
>> +By default, any output produced by @var{command} is sent to
>> +@value{GDBN}'s standard output.
>
> What happens if logging has been turned on?
It's handled no different than typing the command into gdb.
Do we need to say more here?
>> +@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
>> +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
>> +history, nor is the reverse true.
>
> See comment about this above. Also, which history are you talking
> about here: the one from Guile evaluation or the one from GDB?
Not sure I understand, the text refers to both.
$1 when used in a Scheme expression is not the same value as $1 used
in a GDB expression.
I'm happy to reword this as desired, I'm just not sure what.
>> +@node Guile Configuration
>> +@subsubsection Guile Configuration
>
> An index entry would be nice here.
Done.
>> +@defun data-directory
>> +Return a string containing @value{GDBN}'s data directory.
>
> Should we mention that this string is in UTF-8 (I think) encoding?
Strings don't have an encoding per se, they're sequences of unicode code points.
[One needs to specify an encoding when reading/writing them to a file
or whatever of course.]
>> +@defun make-exception key args
>> +Return a @code{<gdb:exception>} object.
>> +@var{key} and @var{args} are the standard Guile parameters of an exception.
>> +See Guile documentation for more information.
> ^^^^^^^^^^^^^^^^^^^^^^^
> Cross-reference, please.
Done.
>> +@defun exception? object
>> +Return @code{#t} if @var{object} is a @code{<gdb:exception>} object.
>
> And #f otherwise, I guess.
Yeah. Type predicates are pretty standard in Scheme so I left that as implicit.
I added another sentence to v2.
>> +@value{GDBN} does not memoize @code{<gdb:value>} objects.
>
> Why not?
I wasn't sure if there would be any unintended consequences, so I've
left it for another day.
A case of "baby steps ...".
I do memoize other things that felt important enough for this pass,
e.g. symbols.
>> +Therefore @code{eq?} does not work as expected.
>> +However @code{equal?} does work.
>> +
>> +@smallexample
>> +(gdb) guile (eq? (make-value 1) (make-value 1))
>> +$1 = #f
>> +(gdb) guile (equal? (make-value 1) (make-value 1))
>> +$1 = #t
>> +@end smallexample
>
> Wouldn't this be confusing for Scheme programmers? Is it terribly
> hard to make eq? work?
See above.
>> +@defun value? object
>> +Return @code{#t} if @var{object} is a @code{<gdb:value>} object.
>
> And #f otherwise?
Sentence added (everywhere I could find).
>> +Many Scheme values can be converted directly to a @code{<gdb:value>} via
>> +with this procedure.
>
> Either "via" or 'with", but not both.
Yikes, I messed up there alright. Fixed.
>> +A Scheme boolean is converted to @var{type} if provided, otherwise
>
> You already described how "type" is handled, no need to repeat that
> (here and elsewhere in this part).
If a type is not provided I need to say what happens and it's
different for each kind of value.
It's not clear to me how to distinguish the two cases in prose without
having something like the text that is there now.
Suggestions?
>> +If @var{type} is not provided,
>> +a Scheme real is converted to the C @code{double} type for the
>> +current architecture.
>
> Isn't Guile built with libgmp? If so, doesn't it support floats
> which, when converted to a double, will lose accuracy?
>
> Also, what about long double, if it is supported by the host?
Defaulting to double is reasonable, and if the user wants a different type
(C float or C long double) then they can explicitly specify it.
>> +A Scheme string is converted to a target string, using the current
>> +target encoding.
>
> What if target encoding doesn't support some of the characters in the
> string?
An exception is thrown. I've added more text.
[It would be nice to provide some control here, for now the
conversion is strict.]
> And what does "target string" mean anyway? A string in C and a string
> in Fortran are two different objects, no?
The current language is used. I've added more text.
>> +If @var{value} is a Scheme bytevector and @var{type} is provided,
>> +@var{value} must be the same size, in bytes, of values of type @var{type},
>> +and the result is essentially created by using @code{memcpy}.
>
> Can type be 'double' in this case? If so, what happens with denormals
> and such likes that are created by such a memcpy? Wouldn't it be
> better to allow only integer types here?
There's no need to disallow constructing denormals and such, the user
may wish to create one.
The intent here is to provide a raw interface to pass values into and
out of Scheme.
>> +If @var{value} is a Scheme bytevector and @var{type} is not provided,
>> +the result is an array of type @code{uint8} of the same length.
>
> I would suggest using 'unsigned char' instead of uint8.
I like uint8. For example, one can create a bytevector with "#vu8(1 2
3 4)" in Scheme.
>> +A similar function @code{value-referenced-value} exists which also
>> +returns @code{<gdb:value>} objects corresonding to the values pointed to
>> +by pointer values (and additionally, values referenced by reference
>> +values). However, the behavior of @code{value-dereference}
>> +differs from @code{value-referenced-value} by the fact that the
>> +behavior of @code{value-dereference} is identical to applying the C
>> +unary operator @code{*} on a given value. For example, consider a
>> +reference to a pointer @code{ptrref}, declared in your C@t{++} program
>> +as
>> +
>> +@smallexample
>> +typedef int *intptr;
>> +...
>> +int val = 10;
>> +intptr ptr = &val;
>> +intptr &ptrref = ptr;
>> +@end smallexample
>
> Here and below you describe 2 related functions, and explain how they
> are different twice, each explanation is part of its @defun. This in
> effect says the same things twice slightly differently, and is thus
> confusing.
>
> Instead, I suggest to provide a concise description of both functions,
> and then explain their differences only once.
It doesn't feel confusing to me.
Plus it's nice to have each function's docs relatively self-contained.
Can I keep it as is for now?
>> +Each element of list @var{arg-list} must be a <gdb:value> object or an object
>> +that can be converted to one.
> ^^^^^^^^^^^^^^^^
> "converted to a value" is less ambiguous.
Done.
>> +For C-like languages, a value is a string if it is a pointer to or an
>> +array of characters or ints.
>
> "Array of ints" meaning a wchar_t string? If so, they might not be
> ints on some platforms (e.g., Windows).
The underlying gdb code watches for wchar_t, char16_t, and char32_t.
ref: c-lang.c:classify_type.
I've reworded the text to mention those types.
>> +The optional @var{errors} argument is either @code{"strict"}
>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>
> Suggest a cross-reference to Guile documentation here.
Done.
>> +If the optional @var{length} argument is given, the string will be
>> +fetched and encoded to the length of characters specified. If
>> +the @var{length} argument is not provided, the string will be fetched
>> +and encoded until a null of appropriate width is found.
>
> Isn't this null termination description skewed towards C-like
> languages? Aren't there languages where strings don't have to be
> null-terminated?
C-like languages are the most popular, plus what's described is what
the underlying gdb support provides.
If/when something more is needed it can be added.
>> +@defun value-max a b
>> +@end defun
>> +
>> +@defun value-max a b
>> +@end defun
>
> One of these should be value-min, I presume.
Fixed.
>> +@table @code
>> +@findex TYPE_CODE_PTR
>> +@item TYPE_CODE_PTR
>
> Using @ftable here would have saved you from the need to type @findex
> for each @item.
Ah. I looked at the texinfo docs and see there's also @vtable.
Since these are variables (constants really) I've used that.
>> +@findex TYPE_CODE_INTERNAL_FUNCTION
>> +@item TYPE_CODE_INTERNAL_FUNCTION
>> +A function internal to @value{GDBN}. This is the type used to represent
>> +convenience functions.
>
> A cross-reference to where convenience functions are described would
> be nice here.
Righto. But that needs to wait until support for convenience
functions is implemented.
>> +@anchor{Fields of a Type in Guile}
>
> Why capitalized words?
Fixed.
@anchor{Fields of a type in Guile}
>> +@node Guile Pretty Printing API
>> +@subsubsection Guile Pretty Printing API
>
> @cindex missing here.
Done.
>> +@node Selecting Guile Pretty-Printers
>> +@subsubsection Selecting Guile Pretty-Printers
>
> @cindex.
Done.
>> +For compatibility @samp{"b"} (binary) may also be present,
>> +but we ignore it: memory ports are binary only.
>
> Which means strings read from memory cannot be decoded?
The data comes in as binary (a stream of bytes), but how it gets
decoded is up to the code doing the reading.
>> +on can be accessed. If only @var{size} if specified, all memory in the
>> +range [0,@var{size} can be accessed. If both are specified, all memory
> ^^^^^^^^^^^^^
> Missing closing paren.
Fixed.
>> +@node Guile Printing Module
>> +@subsubsection Guile Printing Module
>> +@cindex (gdb printing)
>
> Is this really a useful index entry?
Thought so, but to be honest I'm not sure.
I've removed it, it can always be added later.
>> +@node Guile Types Module
>> +@subsubsection Guile Types Module
>> +@cindex (gdb types)
>
> Likewise here.
Ditto.
> Thanks again for doing this.
I think I've addressed all the points in the subsequent emails in this thread.
[if not it's just accidental oversight]
v2 coming up soon.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-03 21:31 ` Ludovic Courtès
2014-01-04 7:12 ` Eli Zaretskii
@ 2014-01-18 20:16 ` Doug Evans
2014-01-18 20:42 ` Ludovic Courtès
2014-01-18 22:32 ` Doug Evans
2 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-18 20:16 UTC (permalink / raw)
To: Ludovic Courtès, Eli Zaretskii; +Cc: gdb-patches
On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>> +The optional @var{errors} argument is either @code{"strict"}
>>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>>
>> Suggest a cross-reference to Guile documentation here.
>
> Agreed. Also, Guile talks of “conversion strategy” and “conversion
> error handler”, with values ‘error’, ‘substitute’, and ‘escape’ (at the
> Scheme level), and I’d recommend sticking to those names and terminology.
The values chosen were to be consistent with the python support.
OTOH I *do* like being more consistent with the particular extension
language at hand.
I've tentatively changes things to use "error" and "substitute".
Question: How about exporting the SCM_FAILED_CONVERSION_* constants
and using those instead?
E.g, (value->string foo #:errors SCM_FAILED_CONVERSION_ERROR) ?
I don't have a strong opinion either way.
Also, in the same spirit of naming things with preference to being
more consistent with the extension language at hand than being more
consistent across all extension languages, does anyone mind if I
rename the "guile-interactive" command to "guile-repl"?
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:06 ` Doug Evans
@ 2014-01-18 20:24 ` Eli Zaretskii
2014-01-18 20:53 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-18 20:24 UTC (permalink / raw)
To: Doug Evans; +Cc: gdb-patches
> Date: Sat, 18 Jan 2014 12:06:46 -0800
> From: Doug Evans <xdje42@gmail.com>
> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>
> >> +@value{GDBN} is not thread-safe. If your Guile program uses multiple
> >> +threads, you must be careful to only call @value{GDBN}-specific
> >> +functions in the main @value{GDBN} thread.
> >
> > What is "the main GDB thread" here?
>
> I think the current wording is sufficient.
My pointy was that GDB, AFAIK, is single threaded. So talking about
"the main GDB thread" creates an illusion that there are other "GDB
threads", which I think don't exist.
> >> +By default, any output produced by @var{command} is sent to
> >> +@value{GDBN}'s standard output.
> >
> > What happens if logging has been turned on?
>
> It's handled no different than typing the command into gdb.
> Do we need to say more here?
I would add "(and to the log output if logging is turned on)".
> >> +@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
> >> +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
> >> +history, nor is the reverse true.
> >
> > See comment about this above. Also, which history are you talking
> > about here: the one from Guile evaluation or the one from GDB?
>
> Not sure I understand, the text refers to both.
> $1 when used in a Scheme expression is not the same value as $1 used
> in a GDB expression.
> I'm happy to reword this as desired, I'm just not sure what.
Instead of that $1 is NOT, I suggest to say what it IS.
> >> +@defun data-directory
> >> +Return a string containing @value{GDBN}'s data directory.
> >
> > Should we mention that this string is in UTF-8 (I think) encoding?
>
> Strings don't have an encoding per se, they're sequences of unicode code points.
??? Are you saying the data directory is returned as a wchar_t array?
> [One needs to specify an encoding when reading/writing them to a file
> or whatever of course.]
If characters in a string are represented as UTF-8 sequences, saying
that is a useful piece of information.
> >> +A Scheme boolean is converted to @var{type} if provided, otherwise
> >
> > You already described how "type" is handled, no need to repeat that
> > (here and elsewhere in this part).
>
> If a type is not provided I need to say what happens and it's
> different for each kind of value.
> It's not clear to me how to distinguish the two cases in prose without
> having something like the text that is there now.
> Suggestions?
Which two cases? (I've read the original way too long ago to
remember.)
> >> +A Scheme string is converted to a target string, using the current
> >> +target encoding.
> >
> > What if target encoding doesn't support some of the characters in the
> > string?
>
> An exception is thrown. I've added more text.
> [It would be nice to provide some control here, for now the
> conversion is strict.]
Why do you need it to be strict? You could replace un-encodable
characters with '?', or a blank, or even omit them. I think this is
nicer than an exception.
> >> +A similar function @code{value-referenced-value} exists which also
> >> +returns @code{<gdb:value>} objects corresonding to the values pointed to
> >> +by pointer values (and additionally, values referenced by reference
> >> +values). However, the behavior of @code{value-dereference}
> >> +differs from @code{value-referenced-value} by the fact that the
> >> +behavior of @code{value-dereference} is identical to applying the C
> >> +unary operator @code{*} on a given value. For example, consider a
> >> +reference to a pointer @code{ptrref}, declared in your C@t{++} program
> >> +as
> >> +
> >> +@smallexample
> >> +typedef int *intptr;
> >> +...
> >> +int val = 10;
> >> +intptr ptr = &val;
> >> +intptr &ptrref = ptr;
> >> +@end smallexample
> >
> > Here and below you describe 2 related functions, and explain how they
> > are different twice, each explanation is part of its @defun. This in
> > effect says the same things twice slightly differently, and is thus
> > confusing.
> >
> > Instead, I suggest to provide a concise description of both functions,
> > and then explain their differences only once.
>
> It doesn't feel confusing to me.
That's because you wrote it. I've read it, and it confused me enough
to have to read it the whole thing twice, before I understood it.
> Plus it's nice to have each function's docs relatively self-contained.
> Can I keep it as is for now?
If you insist.
> >> +@findex TYPE_CODE_INTERNAL_FUNCTION
> >> +@item TYPE_CODE_INTERNAL_FUNCTION
> >> +A function internal to @value{GDBN}. This is the type used to represent
> >> +convenience functions.
> >
> > A cross-reference to where convenience functions are described would
> > be nice here.
>
> Righto. But that needs to wait until support for convenience
> functions is implemented.
I thought we already had them in GDB.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-04 11:57 ` Ludovic Courtès
2014-01-04 14:41 ` Eli Zaretskii
@ 2014-01-18 20:36 ` Doug Evans
2014-01-18 20:52 ` Ludovic Courtès
1 sibling, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-18 20:36 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: Eli Zaretskii, gdb-patches
On Sat, Jan 4, 2014 at 3:57 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>>> >> +A Scheme string is converted to a target string, using the current
>>> >> +target encoding.
>>> >
>>> > What if target encoding doesn't support some of the characters in the
>>> > string?
>>>
>>> Guile’s behavior can be controlled with
>>> ‘%default-port-conversion-strategy’: it can raise an exception, or
>>> substitute any characters that could not be converted, or escape them
>>> (info "(guile) Ports").
>>>
>>> Perhaps this should be briefly mentioned, with a cross-ref.
>>
>> It should, because the issue will certainly arise, especially since
>> (AFAIU) Guile prefers UTF-8.
>
> Right. (UTF-8 is just the default encoding for source code; it’s not
> “preferred” in any other way.)
The default conversion strategy here (for make-value) is to throw an exception.
This isn't a port, and it doesn't feel right to use
%default-port-conversion-strategy here.
It's easy enough to add #:encoding and #:errors options to make-value
in a later patch.
>>> >> +If the optional @var{length} argument is given, the string will be
>>> >> +fetched and encoded to the length of characters specified. If
>>> >> +the @var{length} argument is not provided, the string will be fetched
>>> >> +and encoded until a null of appropriate width is found.
>>> >
>>> > Isn't this null termination description skewed towards C-like
>>> > languages? Aren't there languages where strings don't have to be
>>> > null-terminated?
>>>
>>> Yes, and that’s when LENGTH should be provided, AIUI.
>>
>> Then I guess the above should say that explicitly. But it would be
>> nice if GDB could support strings in languages that don't
>> null-terminate even without LENGTH.
>
> Agreed (I had misread the description above as saying that, if LENGTH is
> provided, then the string is *not* assumed to be nul-terminated.)
I think the text that is there now is sufficient, I'm not sure how I
would change it.
I'm happy to apply any suggested rewordings.
Note that as far as functionality goes, what's there now is what gdb provides.
ref: LA_GET_STRING, struct language_defn.la_get_string.
Any additional functionality can be added later.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:16 ` Doug Evans
@ 2014-01-18 20:42 ` Ludovic Courtès
2014-01-18 21:57 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-18 20:42 UTC (permalink / raw)
To: Doug Evans; +Cc: Eli Zaretskii, gdb-patches
Doug Evans <xdje42@gmail.com> skribis:
> On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>> +The optional @var{errors} argument is either @code{"strict"}
>>>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>>>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>>>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>>>
>>> Suggest a cross-reference to Guile documentation here.
>>
>> Agreed. Also, Guile talks of “conversion strategy” and “conversion
>> error handler”, with values ‘error’, ‘substitute’, and ‘escape’ (at the
>> Scheme level), and I’d recommend sticking to those names and terminology.
>
> The values chosen were to be consistent with the python support.
> OTOH I *do* like being more consistent with the particular extension
> language at hand.
> I've tentatively changes things to use "error" and "substitute".
> Question: How about exporting the SCM_FAILED_CONVERSION_* constants
> and using those instead?
>
> E.g, (value->string foo #:errors SCM_FAILED_CONVERSION_ERROR) ?
I’d rather use a symbol:
(value->string foo #:conversion-strategy 'error)
So that has to be converted in C but I think that’s OK.
(I just noticed that Guile’s ‘pointer->string’, which is similar, lacks
this argument.)
> Also, in the same spirit of naming things with preference to being
> more consistent with the extension language at hand than being more
> consistent across all extension languages, does anyone mind if I
> rename the "guile-interactive" command to "guile-repl"?
Fine with me.
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:36 ` Doug Evans
@ 2014-01-18 20:52 ` Ludovic Courtès
2014-01-18 20:55 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-18 20:52 UTC (permalink / raw)
To: Doug Evans; +Cc: Eli Zaretskii, gdb-patches
Doug Evans <xdje42@gmail.com> skribis:
> On Sat, Jan 4, 2014 at 3:57 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>> >> +A Scheme string is converted to a target string, using the current
>>>> >> +target encoding.
>>>> >
>>>> > What if target encoding doesn't support some of the characters in the
>>>> > string?
>>>>
>>>> Guile’s behavior can be controlled with
>>>> ‘%default-port-conversion-strategy’: it can raise an exception, or
>>>> substitute any characters that could not be converted, or escape them
>>>> (info "(guile) Ports").
>>>>
>>>> Perhaps this should be briefly mentioned, with a cross-ref.
>>>
>>> It should, because the issue will certainly arise, especially since
>>> (AFAIU) Guile prefers UTF-8.
>>
>> Right. (UTF-8 is just the default encoding for source code; it’s not
>> “preferred” in any other way.)
>
> The default conversion strategy here (for make-value) is to throw an exception.
> This isn't a port, and it doesn't feel right to use
> %default-port-conversion-strategy here.
Yes, but I mentioned it because scm_{fo,from}_locale_string use the
value of that fluid as their conversion strategy (info "(guile)
Conversion to/from C").
> It's easy enough to add #:encoding and #:errors options to make-value
> in a later patch.
Yes, that would be best.
(Actually, instead of keyword parameters, you could use optional
positional parameters like ‘string->bytevector’.)
>>>> >> +If the optional @var{length} argument is given, the string will be
>>>> >> +fetched and encoded to the length of characters specified. If
>>>> >> +the @var{length} argument is not provided, the string will be fetched
>>>> >> +and encoded until a null of appropriate width is found.
>>>> >
>>>> > Isn't this null termination description skewed towards C-like
>>>> > languages? Aren't there languages where strings don't have to be
>>>> > null-terminated?
>>>>
>>>> Yes, and that’s when LENGTH should be provided, AIUI.
>>>
>>> Then I guess the above should say that explicitly. But it would be
>>> nice if GDB could support strings in languages that don't
>>> null-terminate even without LENGTH.
>>
>> Agreed (I had misread the description above as saying that, if LENGTH is
>> provided, then the string is *not* assumed to be nul-terminated.)
>
> I think the text that is there now is sufficient, I'm not sure how I
> would change it.
> I'm happy to apply any suggested rewordings.
>
> Note that as far as functionality goes, what's there now is what gdb provides.
> ref: LA_GET_STRING, struct language_defn.la_get_string.
> Any additional functionality can be added later.
If the functionality is that only null-terminated strings are supported,
then the text is fine.
Eli was suggesting supporting non-null-terminated strings as well, but
indeed, that can always be added later.
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:24 ` Eli Zaretskii
@ 2014-01-18 20:53 ` Doug Evans
2014-01-19 16:57 ` Eli Zaretskii
0 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-18 20:53 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
On Sat, Jan 18, 2014 at 12:24 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Sat, 18 Jan 2014 12:06:46 -0800
>> From: Doug Evans <xdje42@gmail.com>
>> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>>
>> >> +@value{GDBN} is not thread-safe. If your Guile program uses multiple
>> >> +threads, you must be careful to only call @value{GDBN}-specific
>> >> +functions in the main @value{GDBN} thread.
>> >
>> > What is "the main GDB thread" here?
>>
>> I think the current wording is sufficient.
>
> My pointy was that GDB, AFAIK, is single threaded. So talking about
> "the main GDB thread" creates an illusion that there are other "GDB
> threads", which I think don't exist.
I could say "the main thread" since that's where GDB "lives".
Though one can imagine an app dlopen'ing gdb itself and in such a case
it's not clear to me gdb has to be run in the "main" thread, just as
long as it is always run in the same thread (until gdb becomes
multithreaded of course).
Thus I'm not sure what to say that isn't equivalent to what's already there.
Suggestions are welcome of course.
>> >> +By default, any output produced by @var{command} is sent to
>> >> +@value{GDBN}'s standard output.
>> >
>> > What happens if logging has been turned on?
>>
>> It's handled no different than typing the command into gdb.
>> Do we need to say more here?
>
> I would add "(and to the log output if logging is turned on)".
Ok.
>> >> +@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
>> >> +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
>> >> +history, nor is the reverse true.
>> >
>> > See comment about this above. Also, which history are you talking
>> > about here: the one from Guile evaluation or the one from GDB?
>>
>> Not sure I understand, the text refers to both.
>> $1 when used in a Scheme expression is not the same value as $1 used
>> in a GDB expression.
>> I'm happy to reword this as desired, I'm just not sure what.
>
> Instead of that $1 is NOT, I suggest to say what it IS.
How about this?
@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
@code{$1} in @value{GDBN}'s value history contains the result of evaluating
an expression from @value{GDBN}'s command line and @code{$1} from Guile's
history contains the result of evaluating an expression from Guile's
command line (@dfn{repl})
>> >> +@defun data-directory
>> >> +Return a string containing @value{GDBN}'s data directory.
>> >
>> > Should we mention that this string is in UTF-8 (I think) encoding?
>>
>> Strings don't have an encoding per se, they're sequences of unicode code points.
>
> ??? Are you saying the data directory is returned as a wchar_t array?
Unicode strings have an internal and an external representation.
Internally, they are represented using "code points".
It is only when strings are represented in an external representation
(e.g. written to a file) that the encoding comes into play.
>> [One needs to specify an encoding when reading/writing them to a file
>> or whatever of course.]
>
> If characters in a string are represented as UTF-8 sequences, saying
> that is a useful piece of information.
>
>> >> +A Scheme boolean is converted to @var{type} if provided, otherwise
>> >
>> > You already described how "type" is handled, no need to repeat that
>> > (here and elsewhere in this part).
>>
>> If a type is not provided I need to say what happens and it's
>> different for each kind of value.
>> It's not clear to me how to distinguish the two cases in prose without
>> having something like the text that is there now.
>> Suggestions?
>
> Which two cases? (I've read the original way too long ago to
> remember.)
case 1: the type is not provided and a default must be chosen
case 2: the type is provided
>
>> >> +A Scheme string is converted to a target string, using the current
>> >> +target encoding.
>> >
>> > What if target encoding doesn't support some of the characters in the
>> > string?
>>
>> An exception is thrown. I've added more text.
>> [It would be nice to provide some control here, for now the
>> conversion is strict.]
>
> Why do you need it to be strict? You could replace un-encodable
> characters with '?', or a blank, or even omit them. I think this is
> nicer than an exception.
A future patch can add the possibility of letting the user choose, but
for a default I prefer being strict.
OTOH, I see the default for Guile's port conversion strategy is "substitute".
It's the wrong choice IMO, but I can live with it.
>> >> +A similar function @code{value-referenced-value} exists which also
>> >> +returns @code{<gdb:value>} objects corresonding to the values pointed to
>> >> +by pointer values (and additionally, values referenced by reference
>> >> +values). However, the behavior of @code{value-dereference}
>> >> +differs from @code{value-referenced-value} by the fact that the
>> >> +behavior of @code{value-dereference} is identical to applying the C
>> >> +unary operator @code{*} on a given value. For example, consider a
>> >> +reference to a pointer @code{ptrref}, declared in your C@t{++} program
>> >> +as
>> >> +
>> >> +@smallexample
>> >> +typedef int *intptr;
>> >> +...
>> >> +int val = 10;
>> >> +intptr ptr = &val;
>> >> +intptr &ptrref = ptr;
>> >> +@end smallexample
>> >
>> > Here and below you describe 2 related functions, and explain how they
>> > are different twice, each explanation is part of its @defun. This in
>> > effect says the same things twice slightly differently, and is thus
>> > confusing.
>> >
>> > Instead, I suggest to provide a concise description of both functions,
>> > and then explain their differences only once.
>>
>> It doesn't feel confusing to me.
>
> That's because you wrote it. I've read it, and it confused me enough
> to have to read it the whole thing twice, before I understood it.
Not wanting to take credit where it's not due, I just copied the text
from the python text.
>> Plus it's nice to have each function's docs relatively self-contained.
>> Can I keep it as is for now?
>
> If you insist.
Thanks.
>> >> +@findex TYPE_CODE_INTERNAL_FUNCTION
>> >> +@item TYPE_CODE_INTERNAL_FUNCTION
>> >> +A function internal to @value{GDBN}. This is the type used to represent
>> >> +convenience functions.
>> >
>> > A cross-reference to where convenience functions are described would
>> > be nice here.
>>
>> Righto. But that needs to wait until support for convenience
>> functions is implemented.
>
> I thought we already had them in GDB.
GDB does, but there's no access to them yet from Guile.
When that is provided the cross-reference should point there.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:52 ` Ludovic Courtès
@ 2014-01-18 20:55 ` Doug Evans
2014-01-19 16:58 ` Eli Zaretskii
0 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-18 20:55 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: Eli Zaretskii, gdb-patches
On Sat, Jan 18, 2014 at 12:52 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Note that as far as functionality goes, what's there now is what gdb provides.
>> ref: LA_GET_STRING, struct language_defn.la_get_string.
>> Any additional functionality can be added later.
>
> If the functionality is that only null-terminated strings are supported,
> then the text is fin
Correction: Either a null-terminated string or a string with the
specified length passed in (i.e., not present in the string itself) is
supported.
> Eli was suggesting supporting non-null-terminated strings as well, but
> indeed, that can always be added later.
They are supported, but the caller has to provide the length.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:42 ` Ludovic Courtès
@ 2014-01-18 21:57 ` Doug Evans
2014-01-19 14:46 ` Ludovic Courtès
0 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-18 21:57 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: Eli Zaretskii, gdb-patches
On Sat, Jan 18, 2014 at 12:42 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> Doug Evans <xdje42@gmail.com> skribis:
>
>> On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>>> +The optional @var{errors} argument is either @code{"strict"}
>>>>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>>>>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>>>>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>>>>
>>>> Suggest a cross-reference to Guile documentation here.
>>>
>>> Agreed. Also, Guile talks of “conversion strategy” and “conversion
>>> error handler”, with values ‘error’, ‘substitute’, and ‘escape’ (at the
>>> Scheme level), and I’d recommend sticking to those names and terminology.
>>
>> The values chosen were to be consistent with the python support.
>> OTOH I *do* like being more consistent with the particular extension
>> language at hand.
>> I've tentatively changes things to use "error" and "substitute".
>> Question: How about exporting the SCM_FAILED_CONVERSION_* constants
>> and using those instead?
>>
>> E.g, (value->string foo #:errors SCM_FAILED_CONVERSION_ERROR) ?
>
> I’d rather use a symbol:
Yeah, I thought of that, but the encoding is a string,
so it'd be "#:encoding string #:errors symbol".
I don't have a strong preference, but using a symbol here while
feeling Schemey feels too weird.
It's not a strong preference though.
[I do have a strong preference that the encoding not be a symbol, not
all encodings could be valid Scheme symbols.
OTOH, support could be added for both strings and symbols for both
#:encoding and #:errors in a later patch if a compelling case for it
was presented.]
> (value->string foo #:conversion-strategy 'error)
>
> So that has to be converted in C but I think that’s OK.
#:conversion-strategy is more to type than #:errors but I'm happy to
change it if you want.
Though this is a case where I would not want to support both
#:conversion-strategy and #:errors so whatever we pick is it.
We can create a 'error symbol at start up and just use scm_eq so the
comparison is easy enough.
> (I just noticed that Guile’s ‘pointer->string’, which is similar, lacks
> this argument.)
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-03 21:31 ` Ludovic Courtès
2014-01-04 7:12 ` Eli Zaretskii
2014-01-18 20:16 ` Doug Evans
@ 2014-01-18 22:32 ` Doug Evans
2014-01-19 14:47 ` Ludovic Courtès
2 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-18 22:32 UTC (permalink / raw)
To: Ludovic Courtès, Eli Zaretskii; +Cc: gdb-patches
On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> Eli Zaretskii <eliz@gnu.org> skribis:
>
>>> +Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
>>
>> I'm not sure we should say this in the manual.
>
> In practice the parts that are used (mostly the C API) have seen few
> additions over 2.0, so it’s likely that it would work with any 2.0.x.
>
>>> +The implementation uses Guile's @code{smob} (small object)
>> ^^^^^^^^^^^^
>> This should be in @dfn, as it's new terminology.
>
> Better yet:
>
> (@pxref{Smobs,,, guile, GNU Guile Reference Manual})
fyi, I'm finding I need to use guile2 here instead of guile in order
for info to find the guile docs.
I presume that's ok.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 21:57 ` Doug Evans
@ 2014-01-19 14:46 ` Ludovic Courtès
2014-01-19 21:37 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-19 14:46 UTC (permalink / raw)
To: Doug Evans; +Cc: Eli Zaretskii, gdb-patches
Doug Evans <xdje42@gmail.com> skribis:
> On Sat, Jan 18, 2014 at 12:42 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Doug Evans <xdje42@gmail.com> skribis:
>>
>>> On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>>>> +The optional @var{errors} argument is either @code{"strict"}
>>>>>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>>>>>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>>>>>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>>>>>
>>>>> Suggest a cross-reference to Guile documentation here.
>>>>
>>>> Agreed. Also, Guile talks of “conversion strategy” and “conversion
>>>> error handler”, with values ‘error’, ‘substitute’, and ‘escape’ (at the
>>>> Scheme level), and I’d recommend sticking to those names and terminology.
>>>
>>> The values chosen were to be consistent with the python support.
>>> OTOH I *do* like being more consistent with the particular extension
>>> language at hand.
>>> I've tentatively changes things to use "error" and "substitute".
>>> Question: How about exporting the SCM_FAILED_CONVERSION_* constants
>>> and using those instead?
>>>
>>> E.g, (value->string foo #:errors SCM_FAILED_CONVERSION_ERROR) ?
>>
>> I’d rather use a symbol:
>
> Yeah, I thought of that, but the encoding is a string,
> so it'd be "#:encoding string #:errors symbol".
Right. Looks good to me.
> I don't have a strong preference, but using a symbol here while
> feeling Schemey feels too weird.
> It's not a strong preference though.
Using a symbol for #:errors? It would be natural and consistent with
the rest of Guile’s API (notably and ‘string->bytevector’,
‘set-port-conversion-strategy!’.)
>> (value->string foo #:conversion-strategy 'error)
>>
>> So that has to be converted in C but I think that’s OK.
>
> #:conversion-strategy is more to type than #:errors but I'm happy to
> change it if you want.
> Though this is a case where I would not want to support both
> #:conversion-strategy and #:errors so whatever we pick is it.
Right. Or ‘value->string’ could have this signature:
value->string VAL [ENCODING [ERRORS]]
The precedent being ‘string->pointer’ and ‘string->bytevector’.
> We can create a 'error symbol at start up and just use scm_eq so the
> comparison is easy enough.
Exactly, that’s what I would suggest.
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 22:32 ` Doug Evans
@ 2014-01-19 14:47 ` Ludovic Courtès
2014-01-19 15:56 ` Eli Zaretskii
0 siblings, 1 reply; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-19 14:47 UTC (permalink / raw)
To: Doug Evans; +Cc: Eli Zaretskii, gdb-patches
Doug Evans <xdje42@gmail.com> skribis:
> On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Eli Zaretskii <eliz@gnu.org> skribis:
>>
>>>> +Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
>>>
>>> I'm not sure we should say this in the manual.
>>
>> In practice the parts that are used (mostly the C API) have seen few
>> additions over 2.0, so it’s likely that it would work with any 2.0.x.
>>
>>>> +The implementation uses Guile's @code{smob} (small object)
>>> ^^^^^^^^^^^^
>>> This should be in @dfn, as it's new terminology.
>>
>> Better yet:
>>
>> (@pxref{Smobs,,, guile, GNU Guile Reference Manual})
>
> fyi, I'm finding I need to use guile2 here instead of guile in order
> for info to find the guile docs.
> I presume that's ok.
Yes. I don’t remember: are you targeting 1.8 as well?
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 14:47 ` Ludovic Courtès
@ 2014-01-19 15:56 ` Eli Zaretskii
2014-01-19 16:13 ` Ludovic Courtès
0 siblings, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-19 15:56 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: xdje42, gdb-patches
> From: ludo@gnu.org (Ludovic Courtès)
> Cc: Eli Zaretskii <eliz@gnu.org>, "gdb-patches\@sourceware.org" <gdb-patches@sourceware.org>
> Date: Sun, 19 Jan 2014 15:47:33 +0100
>
> >> (@pxref{Smobs,,, guile, GNU Guile Reference Manual})
> >
> > fyi, I'm finding I need to use guile2 here instead of guile in order
> > for info to find the guile docs.
> > I presume that's ok.
>
> Yes. I don’t remember: are you targeting 1.8 as well?
The cross-reference should name the file that is installed by Guile
2.x; I don't remember its name, but Ludovic certainly will ;-)
My point here is that if guile2 comes from some particular GNU/Linux
distro, and the package installs the file under a different, we should
not use guile2 in the GDB manual.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 15:56 ` Eli Zaretskii
@ 2014-01-19 16:13 ` Ludovic Courtès
2014-01-19 17:05 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-19 16:13 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: xdje42, gdb-patches
Eli Zaretskii <eliz@gnu.org> skribis:
>> From: ludo@gnu.org (Ludovic Courtès)
>> Cc: Eli Zaretskii <eliz@gnu.org>, "gdb-patches\@sourceware.org" <gdb-patches@sourceware.org>
>> Date: Sun, 19 Jan 2014 15:47:33 +0100
>>
>> >> (@pxref{Smobs,,, guile, GNU Guile Reference Manual})
>> >
>> > fyi, I'm finding I need to use guile2 here instead of guile in order
>> > for info to find the guile docs.
>> > I presume that's ok.
>>
>> Yes. I don’t remember: are you targeting 1.8 as well?
>
> The cross-reference should name the file that is installed by Guile
> 2.x; I don't remember its name, but Ludovic certainly will ;-)
All versions of Guile install guile.info*, so the @pxref above should work.
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:53 ` Doug Evans
@ 2014-01-19 16:57 ` Eli Zaretskii
2014-01-19 17:42 ` Doug Evans
2014-01-19 21:01 ` Doug Evans
0 siblings, 2 replies; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-19 16:57 UTC (permalink / raw)
To: Doug Evans; +Cc: gdb-patches
> Date: Sat, 18 Jan 2014 12:53:11 -0800
> From: Doug Evans <xdje42@gmail.com>
> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>
> On Sat, Jan 18, 2014 at 12:24 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> Date: Sat, 18 Jan 2014 12:06:46 -0800
> >> From: Doug Evans <xdje42@gmail.com>
> >> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> >>
> >> >> +@value{GDBN} is not thread-safe. If your Guile program uses multiple
> >> >> +threads, you must be careful to only call @value{GDBN}-specific
> >> >> +functions in the main @value{GDBN} thread.
> >> >
> >> > What is "the main GDB thread" here?
> >>
> >> I think the current wording is sufficient.
> >
> > My pointy was that GDB, AFAIK, is single threaded. So talking about
> > "the main GDB thread" creates an illusion that there are other "GDB
> > threads", which I think don't exist.
>
> I could say "the main thread" since that's where GDB "lives".
How about "the GDB thread"?
> >> >> +@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
> >> >> +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
> >> >> +history, nor is the reverse true.
> >> >
> >> > See comment about this above. Also, which history are you talking
> >> > about here: the one from Guile evaluation or the one from GDB?
> >>
> >> Not sure I understand, the text refers to both.
> >> $1 when used in a Scheme expression is not the same value as $1 used
> >> in a GDB expression.
> >> I'm happy to reword this as desired, I'm just not sure what.
> >
> > Instead of that $1 is NOT, I suggest to say what it IS.
>
> How about this?
>
> @emph{Note:} @value{GDBN}'s value history is independent of Guile's.
> @code{$1} in @value{GDBN}'s value history contains the result of evaluating
> an expression from @value{GDBN}'s command line and @code{$1} from Guile's
> history contains the result of evaluating an expression from Guile's
> command line (@dfn{repl})
That's fine, thanks.
> >> >> +@defun data-directory
> >> >> +Return a string containing @value{GDBN}'s data directory.
> >> >
> >> > Should we mention that this string is in UTF-8 (I think) encoding?
> >>
> >> Strings don't have an encoding per se, they're sequences of unicode code points.
> >
> > ??? Are you saying the data directory is returned as a wchar_t array?
>
> Unicode strings have an internal and an external representation.
> Internally, they are represented using "code points".
> It is only when strings are represented in an external representation
> (e.g. written to a file) that the encoding comes into play.
I'm not sure I understand (or agree). But in this case, all I care
about is the POV of the GDB user who writes a Guile script to be used
with GDB. Does such a user need to know anything about the
representation and/or encoding of the data-directory string to be able
to use it correctly, display it, etc.?
> >> >> +A Scheme boolean is converted to @var{type} if provided, otherwise
> >> >
> >> > You already described how "type" is handled, no need to repeat that
> >> > (here and elsewhere in this part).
> >>
> >> If a type is not provided I need to say what happens and it's
> >> different for each kind of value.
> >> It's not clear to me how to distinguish the two cases in prose without
> >> having something like the text that is there now.
> >> Suggestions?
> >
> > Which two cases? (I've read the original way too long ago to
> > remember.)
>
> case 1: the type is not provided and a default must be chosen
>
> case 2: the type is provided
Case 2 was already explained before this text:
+@defun make-value value @r{[}#:type type@r{]}
+Many Scheme values can be converted directly to a @code{<gdb:value>} via
+with this procedure. If @var{type} is specified, the result is a value
+of this type, and if @var{value} can't be represented with this type
+an exception is thrown. Otherwise the type of the result is determined from
+@var{value} as described below.
So all is left is to describe Case 1. Therefore, I suggest to replace
+The following Scheme objects are accepted for @var{value}:
with
Here's how Scheme values are converted when @var{type} argument to
@code{make-value} is not specified:
and then rephrase the information about the specific types like this:
@table @asis
@item Scheme boolean
A Scheme boolean is converted to the boolean type of the current
language.
@item Scheme integer
A Scheme integer is converted to the first of a C @code{int}, ...
etc., you get the idea.
> >> >> +@findex TYPE_CODE_INTERNAL_FUNCTION
> >> >> +@item TYPE_CODE_INTERNAL_FUNCTION
> >> >> +A function internal to @value{GDBN}. This is the type used to represent
> >> >> +convenience functions.
> >> >
> >> > A cross-reference to where convenience functions are described would
> >> > be nice here.
> >>
> >> Righto. But that needs to wait until support for convenience
> >> functions is implemented.
> >
> > I thought we already had them in GDB.
>
> GDB does, but there's no access to them yet from Guile.
> When that is provided the cross-reference should point there.
I meant a cross-reference to where GDB convenience functions are
described, in case the reader isn't familiar with the concept, or
wants to refresh her memory for some reason.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-18 20:55 ` Doug Evans
@ 2014-01-19 16:58 ` Eli Zaretskii
2014-01-19 17:19 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-19 16:58 UTC (permalink / raw)
To: Doug Evans; +Cc: ludo, gdb-patches
> Date: Sat, 18 Jan 2014 12:55:22 -0800
> From: Doug Evans <xdje42@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>
> > If the functionality is that only null-terminated strings are supported,
> > then the text is fin
>
> Correction: Either a null-terminated string or a string with the
> specified length passed in (i.e., not present in the string itself) is
> supported.
>
> > Eli was suggesting supporting non-null-terminated strings as well, but
> > indeed, that can always be added later.
>
> They are supported, but the caller has to provide the length.
Then let's say that explicitly. The text as is can be interpreted as
meaning that such strings aren't supported.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 16:13 ` Ludovic Courtès
@ 2014-01-19 17:05 ` Doug Evans
0 siblings, 0 replies; 35+ messages in thread
From: Doug Evans @ 2014-01-19 17:05 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: Eli Zaretskii, gdb-patches
On Sun, Jan 19, 2014 at 8:13 AM, Ludovic Courtès <ludo@gnu.org> wrote:
> Eli Zaretskii <eliz@gnu.org> skribis:
>
>>> From: ludo@gnu.org (Ludovic Courtès)
>>> Cc: Eli Zaretskii <eliz@gnu.org>, "gdb-patches\@sourceware.org" <gdb-patches@sourceware.org>
>>> Date: Sun, 19 Jan 2014 15:47:33 +0100
>>>
>>> >> (@pxref{Smobs,,, guile, GNU Guile Reference Manual})
>>> >
>>> > fyi, I'm finding I need to use guile2 here instead of guile in order
>>> > for info to find the guile docs.
>>> > I presume that's ok.
>>>
>>> Yes. I don’t remember: are you targeting 1.8 as well?
>>
>> The cross-reference should name the file that is installed by Guile
>> 2.x; I don't remember its name, but Ludovic certainly will ;-)
>
> All versions of Guile install guile.info*, so the @pxref above should work.
Ah. Then that's what we should use.
Also, for reference sake, I'm not targeting 1.8 (or earlier).
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 16:58 ` Eli Zaretskii
@ 2014-01-19 17:19 ` Doug Evans
2014-01-19 17:34 ` Eli Zaretskii
0 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-19 17:19 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Ludovic Courtès, gdb-patches
On Sun, Jan 19, 2014 at 8:58 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Sat, 18 Jan 2014 12:55:22 -0800
>> From: Doug Evans <xdje42@gmail.com>
>> Cc: Eli Zaretskii <eliz@gnu.org>, "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>>
>> > If the functionality is that only null-terminated strings are supported,
>> > then the text is fin
>>
>> Correction: Either a null-terminated string or a string with the
>> specified length passed in (i.e., not present in the string itself) is
>> supported.
>>
>> > Eli was suggesting supporting non-null-terminated strings as well, but
>> > indeed, that can always be added later.
>>
>> They are supported, but the caller has to provide the length.
>
> Then let's say that explicitly. The text as is can be interpreted as
> meaning that such strings aren't supported.
The text does say that strings are either zero-terminated or
the length is explicitly specified.
Here's my current wording.
For C-like languages, a value is a string if it is a pointer to or an
array of characters or ints of type @code{wchar_t}, @code{char16_t},
or @code{char32_t}. The string is assumed to be terminated
by a zero of the appropriate width. However if the optional length
argument is given, the string will be converted to that given length,
and will include any embedded zeros that the string may contain.
I'm happy to change it, but I'm going to need some help on what
to change it to.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 17:19 ` Doug Evans
@ 2014-01-19 17:34 ` Eli Zaretskii
2014-01-19 17:53 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-19 17:34 UTC (permalink / raw)
To: Doug Evans; +Cc: ludo, gdb-patches
> Date: Sun, 19 Jan 2014 09:19:45 -0800
> From: Doug Evans <xdje42@gmail.com>
> Cc: Ludovic Courtès <ludo@gnu.org>,
> "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>
> For C-like languages, a value is a string if it is a pointer to or an
> array of characters or ints of type @code{wchar_t}, @code{char16_t},
> or @code{char32_t}. The string is assumed to be terminated
> by a zero of the appropriate width. However if the optional length
> argument is given, the string will be converted to that given length,
> and will include any embedded zeros that the string may contain.
The only problem with this text is that it seems to cover _only_
C-like languages. It says nothing about the other languages.
How about this:
For C-like languages, a value is a string if it is a pointer to or an
array of characters or ints of type @code{wchar_t}, @code{char16_t},
or @code{char32_t}. For other languages ... [say here how string
values are distinguished in other languages]. If the string is
terminated by a zero of the appropriate width, it will be converted up
to that zero. For strings that are not zero-terminated (which
includes strings in non C-like languages), you must specify the length
for conversion.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 16:57 ` Eli Zaretskii
@ 2014-01-19 17:42 ` Doug Evans
2014-01-19 21:01 ` Doug Evans
1 sibling, 0 replies; 35+ messages in thread
From: Doug Evans @ 2014-01-19 17:42 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
On Sun, Jan 19, 2014 at 8:57 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> > My pointy was that GDB, AFAIK, is single threaded. So talking about
>> > "the main GDB thread" creates an illusion that there are other "GDB
>> > threads", which I think don't exist.
>>
>> I could say "the main thread" since that's where GDB "lives".
>
> How about "the GDB thread"?
Done.
>> >> >> +@defun data-directory
>> >> >> +Return a string containing @value{GDBN}'s data directory.
>> >> >
>> >> > Should we mention that this string is in UTF-8 (I think) encoding?
>> >>
>> >> Strings don't have an encoding per se, they're sequences of unicode code points.
>> >
>> > ??? Are you saying the data directory is returned as a wchar_t array?
>>
>> Unicode strings have an internal and an external representation.
>> Internally, they are represented using "code points".
>> It is only when strings are represented in an external representation
>> (e.g. written to a file) that the encoding comes into play.
>
> I'm not sure I understand (or agree). But in this case, all I care
> about is the POV of the GDB user who writes a Guile script to be used
> with GDB. Does such a user need to know anything about the
> representation and/or encoding of the data-directory string to be able
> to use it correctly, display it, etc.?
I would apply the same view for data-directory as for all Guile functions that
return strings. The encoding is not needed when calling things like
string-append.
When the encoding is needed it is the responsibility of *that*
function to provide
a means to specify the encoding, and those functions don't say what encoding
the provided string is in, they specify the encoding to emit the
provided string as.
Guile strings have no encoding (internally, Guile could store strings as utf8,
or a hybrid of narrow and wide (which is what it does today)), but to the Scheme
user a string is a sequence of unicode code points, there is no
inherent encoding.
>> >> >> +A Scheme boolean is converted to @var{type} if provided, otherwise
>> >> >
>> >> > You already described how "type" is handled, no need to repeat that
>> >> > (here and elsewhere in this part).
>> >>
>> >> If a type is not provided I need to say what happens and it's
>> >> different for each kind of value.
>> >> It's not clear to me how to distinguish the two cases in prose without
>> >> having something like the text that is there now.
>> >> Suggestions?
>> >
>> > Which two cases? (I've read the original way too long ago to
>> > remember.)
>>
>> case 1: the type is not provided and a default must be chosen
>>
>> case 2: the type is provided
>
> Case 2 was already explained before this text:
>
> +@defun make-value value @r{[}#:type type@r{]}
> +Many Scheme values can be converted directly to a @code{<gdb:value>} via
> +with this procedure. If @var{type} is specified, the result is a value
> +of this type, and if @var{value} can't be represented with this type
> +an exception is thrown. Otherwise the type of the result is determined from
> +@var{value} as described below.
>
> So all is left is to describe Case 1. Therefore, I suggest to replace
>
> +The following Scheme objects are accepted for @var{value}:
>
> with
>
> Here's how Scheme values are converted when @var{type} argument to
> @code{make-value} is not specified:
>
> and then rephrase the information about the specific types like this:
>
> @table @asis
> @item Scheme boolean
> A Scheme boolean is converted to the boolean type of the current
> language.
>
> @item Scheme integer
> A Scheme integer is converted to the first of a C @code{int}, ...
>
> etc., you get the idea.
Done.
>> >> >> +@findex TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +@item TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +A function internal to @value{GDBN}. This is the type used to represent
>> >> >> +convenience functions.
>> >> >
>> >> > A cross-reference to where convenience functions are described would
>> >> > be nice here.
>> >>
>> >> Righto. But that needs to wait until support for convenience
>> >> functions is implemented.
>> >
>> > I thought we already had them in GDB.
>>
>> GDB does, but there's no access to them yet from Guile.
>> When that is provided the cross-reference should point there.
>
> I meant a cross-reference to where GDB convenience functions are
> described, in case the reader isn't familiar with the concept, or
> wants to refresh her memory for some reason.
Done.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 17:34 ` Eli Zaretskii
@ 2014-01-19 17:53 ` Doug Evans
2014-01-19 18:10 ` Eli Zaretskii
0 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-19 17:53 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Ludovic Courtès, gdb-patches
On Sun, Jan 19, 2014 at 9:34 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Sun, 19 Jan 2014 09:19:45 -0800
>> From: Doug Evans <xdje42@gmail.com>
>> Cc: Ludovic Courtès <ludo@gnu.org>,
>> "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>>
>> For C-like languages, a value is a string if it is a pointer to or an
>> array of characters or ints of type @code{wchar_t}, @code{char16_t},
>> or @code{char32_t}. The string is assumed to be terminated
>> by a zero of the appropriate width. However if the optional length
>> argument is given, the string will be converted to that given length,
>> and will include any embedded zeros that the string may contain.
>
> The only problem with this text is that it seems to cover _only_
> C-like languages. It says nothing about the other languages.
>
> How about this:
>
> For C-like languages, a value is a string if it is a pointer to or an
> array of characters or ints of type @code{wchar_t}, @code{char16_t},
> or @code{char32_t}. For other languages ... [say here how string
> values are distinguished in other languages]. If the string is
> terminated by a zero of the appropriate width, it will be converted up
> to that zero. For strings that are not zero-terminated (which
> includes strings in non C-like languages), you must specify the length
> for conversion.
Even in C-like languages the user may wish to specify a length.
E.g., C++ strings have a length, but it's up to the library to specify how it's
recorded. Plus C++ programs can have multiple string implementations
(not just std::string). Not always ideal, but an app may have a specific
performance issue for a specific part of it and thus provides its own
string implementation for that part. Thus in this (important) case there
is no text I can provide here to answer the question you are asking.
Plus there's a maintenance issue of describing how each language
defines a string. We don't want to have to update this part for each
new language.
There's a functionality that GDB provides to the extension language:
zero-terminated or provide your own length. That's all Guile (or Python)
can provide because for now that's all GDB let's them.
Please can I keep the current text?
We can certainly revise it later.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 17:53 ` Doug Evans
@ 2014-01-19 18:10 ` Eli Zaretskii
2014-01-19 21:19 ` Doug Evans
0 siblings, 1 reply; 35+ messages in thread
From: Eli Zaretskii @ 2014-01-19 18:10 UTC (permalink / raw)
To: Doug Evans; +Cc: ludo, gdb-patches
> Date: Sun, 19 Jan 2014 09:53:21 -0800
> From: Doug Evans <xdje42@gmail.com>
> Cc: Ludovic Courtès <ludo@gnu.org>,
> "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>
> > For C-like languages, a value is a string if it is a pointer to or an
> > array of characters or ints of type @code{wchar_t}, @code{char16_t},
> > or @code{char32_t}. For other languages ... [say here how string
> > values are distinguished in other languages]. If the string is
> > terminated by a zero of the appropriate width, it will be converted up
> > to that zero. For strings that are not zero-terminated (which
> > includes strings in non C-like languages), you must specify the length
> > for conversion.
>
> Even in C-like languages the user may wish to specify a length.
>
> E.g., C++ strings have a length, but it's up to the library to specify how it's
> recorded. Plus C++ programs can have multiple string implementations
> (not just std::string). Not always ideal, but an app may have a specific
> performance issue for a specific part of it and thus provides its own
> string implementation for that part. Thus in this (important) case there
> is no text I can provide here to answer the question you are asking.
>
> Plus there's a maintenance issue of describing how each language
> defines a string. We don't want to have to update this part for each
> new language.
Fair enough. How about the following variant, which is entirely
agnostic to the language?
Values are interpreted as strings according to the rules of the
current language. If the optional length argument is given, the
string will be converted to that length. Otherwise, for languages
where the string is zero-terminated, the entire string will be
converted.
If you want to say something about C-like languages, we can have a
"for example" sentence after the 1st one. Something like
For example, in C-like languages, a value is a string if it is a
pointer to, or an array of, characters or ints of type ...
> Please can I keep the current text?
If you think it is better than what I suggested above.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 16:57 ` Eli Zaretskii
2014-01-19 17:42 ` Doug Evans
@ 2014-01-19 21:01 ` Doug Evans
1 sibling, 0 replies; 35+ messages in thread
From: Doug Evans @ 2014-01-19 21:01 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
On Sun, Jan 19, 2014 at 8:57 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Sat, 18 Jan 2014 12:53:11 -0800
>> From: Doug Evans <xdje42@gmail.com>
>> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>>
>> On Sat, Jan 18, 2014 at 12:24 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> >> Date: Sat, 18 Jan 2014 12:06:46 -0800
>> >> From: Doug Evans <xdje42@gmail.com>
>> >> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>> >>
>> >> >> +@value{GDBN} is not thread-safe. If your Guile program uses multiple
>> >> >> +threads, you must be careful to only call @value{GDBN}-specific
>> >> >> +functions in the main @value{GDBN} thread.
>> >> >
>> >> > What is "the main GDB thread" here?
>> >>
>> >> I think the current wording is sufficient.
>> >
>> > My pointy was that GDB, AFAIK, is single threaded. So talking about
>> > "the main GDB thread" creates an illusion that there are other "GDB
>> > threads", which I think don't exist.
>>
>> I could say "the main thread" since that's where GDB "lives".
>
> How about "the GDB thread"?
Done.
>> >> >> +A Scheme boolean is converted to @var{type} if provided, otherwise
>> >> >
>> >> > You already described how "type" is handled, no need to repeat that
>> >> > (here and elsewhere in this part).
>> >>
>> >> If a type is not provided I need to say what happens and it's
>> >> different for each kind of value.
>> >> It's not clear to me how to distinguish the two cases in prose without
>> >> having something like the text that is there now.
>> >> Suggestions?
>> >
>> > Which two cases? (I've read the original way too long ago to
>> > remember.)
>>
>> case 1: the type is not provided and a default must be chosen
>>
>> case 2: the type is provided
>
> Case 2 was already explained before this text:
>
> +@defun make-value value @r{[}#:type type@r{]}
> +Many Scheme values can be converted directly to a @code{<gdb:value>} via
> +with this procedure. If @var{type} is specified, the result is a value
> +of this type, and if @var{value} can't be represented with this type
> +an exception is thrown. Otherwise the type of the result is determined from
> +@var{value} as described below.
>
> So all is left is to describe Case 1. Therefore, I suggest to replace
>
> +The following Scheme objects are accepted for @var{value}:
>
> with
>
> Here's how Scheme values are converted when @var{type} argument to
> @code{make-value} is not specified:
>
> and then rephrase the information about the specific types like this:
>
> @table @asis
> @item Scheme boolean
> A Scheme boolean is converted to the boolean type of the current
> language.
>
> @item Scheme integer
> A Scheme integer is converted to the first of a C @code{int}, ...
>
> etc., you get the idea.
Done.
>> >> >> +@findex TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +@item TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +A function internal to @value{GDBN}. This is the type used to represent
>> >> >> +convenience functions.
>> >> >
>> >> > A cross-reference to where convenience functions are described would
>> >> > be nice here.
>> >>
>> >> Righto. But that needs to wait until support for convenience
>> >> functions is implemented.
>> >
>> > I thought we already had them in GDB.
>>
>> GDB does, but there's no access to them yet from Guile.
>> When that is provided the cross-reference should point there.
>
> I meant a cross-reference to where GDB convenience functions are
> described, in case the reader isn't familiar with the concept, or
> wants to refresh her memory for some reason.
Done.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 18:10 ` Eli Zaretskii
@ 2014-01-19 21:19 ` Doug Evans
0 siblings, 0 replies; 35+ messages in thread
From: Doug Evans @ 2014-01-19 21:19 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Ludovic Courtès, gdb-patches
On Sun, Jan 19, 2014 at 10:10 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Sun, 19 Jan 2014 09:53:21 -0800
>> From: Doug Evans <xdje42@gmail.com>
>> Cc: Ludovic Courtès <ludo@gnu.org>,
>> "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>>
>> > For C-like languages, a value is a string if it is a pointer to or an
>> > array of characters or ints of type @code{wchar_t}, @code{char16_t},
>> > or @code{char32_t}. For other languages ... [say here how string
>> > values are distinguished in other languages]. If the string is
>> > terminated by a zero of the appropriate width, it will be converted up
>> > to that zero. For strings that are not zero-terminated (which
>> > includes strings in non C-like languages), you must specify the length
>> > for conversion.
>>
>> Even in C-like languages the user may wish to specify a length.
>>
>> E.g., C++ strings have a length, but it's up to the library to specify how it's
>> recorded. Plus C++ programs can have multiple string implementations
>> (not just std::string). Not always ideal, but an app may have a specific
>> performance issue for a specific part of it and thus provides its own
>> string implementation for that part. Thus in this (important) case there
>> is no text I can provide here to answer the question you are asking.
>>
>> Plus there's a maintenance issue of describing how each language
>> defines a string. We don't want to have to update this part for each
>> new language.
>
> Fair enough. How about the following variant, which is entirely
> agnostic to the language?
>
> Values are interpreted as strings according to the rules of the
> current language. If the optional length argument is given, the
> string will be converted to that length. Otherwise, for languages
> where the string is zero-terminated, the entire string will be
> converted.
>
> If you want to say something about C-like languages, we can have a
> "for example" sentence after the 1st one. Something like
>
> For example, in C-like languages, a value is a string if it is a
> pointer to, or an array of, characters or ints of type ...
>
>> Please can I keep the current text?
>
> If you think it is better than what I suggested above.
I tweaked it a bit because I wanted to make clear specifying the
length will include any embedded zeroes.
Values are interpreted as strings according to the rules of the
current language. If the optional length argument is given, the
string will be converted to that length, and will include any embedded
zeroes that the string may contain. Otherwise, for languages
where the string is zero-terminated, the entire string will be
converted.
For example, in C-like languages, a value is a string if it is a pointer
to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
or @code{char32_t}.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 14:46 ` Ludovic Courtès
@ 2014-01-19 21:37 ` Doug Evans
2014-01-19 22:50 ` Ludovic Courtès
0 siblings, 1 reply; 35+ messages in thread
From: Doug Evans @ 2014-01-19 21:37 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: Eli Zaretskii, gdb-patches
On Sun, Jan 19, 2014 at 6:46 AM, Ludovic Courtès <ludo@gnu.org> wrote:
> Doug Evans <xdje42@gmail.com> skribis:
>
>> On Sat, Jan 18, 2014 at 12:42 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>> Doug Evans <xdje42@gmail.com> skribis:
>>>
>>>> On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>>>>> +The optional @var{errors} argument is either @code{"strict"}
>>>>>>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>>>>>>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>>>>>>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>>>>>>
>>>>>> Suggest a cross-reference to Guile documentation here.
>>>>>
>>>>> Agreed. Also, Guile talks of “conversion strategy” and “conversion
>>>>> error handler”, with values ‘error’, ‘substitute’, and ‘escape’ (at the
>>>>> Scheme level), and I’d recommend sticking to those names and terminology.
>>>>
>>>> The values chosen were to be consistent with the python support.
>>>> OTOH I *do* like being more consistent with the particular extension
>>>> language at hand.
>>>> I've tentatively changes things to use "error" and "substitute".
>>>> Question: How about exporting the SCM_FAILED_CONVERSION_* constants
>>>> and using those instead?
>>>>
>>>> E.g, (value->string foo #:errors SCM_FAILED_CONVERSION_ERROR) ?
>>>
>>> I’d rather use a symbol:
>>
>> Yeah, I thought of that, but the encoding is a string,
>> so it'd be "#:encoding string #:errors symbol".
>
> Right. Looks good to me.
>
>> I don't have a strong preference, but using a symbol here while
>> feeling Schemey feels too weird.
>> It's not a strong preference though.
>
> Using a symbol for #:errors? It would be natural and consistent with
> the rest of Guile’s API (notably and ‘string->bytevector’,
> ‘set-port-conversion-strategy!’.)
"works for me"
Though I see %default-port-conversion-strategy is used by more than
just ports, so it seems reasonable for gdb to use that as the default
too (obtainable by calling scm_port_conversion_strategy (SCM_BOOL_F)).
>>> (value->string foo #:conversion-strategy 'error)
>>>
>>> So that has to be converted in C but I think that’s OK.
>>
>> #:conversion-strategy is more to type than #:errors but I'm happy to
>> change it if you want.
>> Though this is a case where I would not want to support both
>> #:conversion-strategy and #:errors so whatever we pick is it.
>
> Right. Or ‘value->string’ could have this signature:
>
> value->string VAL [ENCODING [ERRORS]]
>
> The precedent being ‘string->pointer’ and ‘string->bytevector’.
I'd like to stick with the current signature.
>> We can create a 'error symbol at start up and just use scm_eq so the
>> comparison is easy enough.
>
> Exactly, that’s what I would suggest.
Righto.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v1 02/36] Guile extension language: doc additions
2014-01-19 21:37 ` Doug Evans
@ 2014-01-19 22:50 ` Ludovic Courtès
0 siblings, 0 replies; 35+ messages in thread
From: Ludovic Courtès @ 2014-01-19 22:50 UTC (permalink / raw)
To: Doug Evans; +Cc: Eli Zaretskii, gdb-patches
Doug Evans <xdje42@gmail.com> skribis:
> On Sun, Jan 19, 2014 at 6:46 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Doug Evans <xdje42@gmail.com> skribis:
>>
>>> On Sat, Jan 18, 2014 at 12:42 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>> Doug Evans <xdje42@gmail.com> skribis:
>>>>
>>>>> On Fri, Jan 3, 2014 at 1:30 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>>>>>> +The optional @var{errors} argument is either @code{"strict"}
>>>>>>>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>>>>>>>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>>>>>>>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>>>>>>>
>>>>>>> Suggest a cross-reference to Guile documentation here.
>>>>>>
>>>>>> Agreed. Also, Guile talks of “conversion strategy” and “conversion
>>>>>> error handler”, with values ‘error’, ‘substitute’, and ‘escape’ (at the
>>>>>> Scheme level), and I’d recommend sticking to those names and terminology.
>>>>>
>>>>> The values chosen were to be consistent with the python support.
>>>>> OTOH I *do* like being more consistent with the particular extension
>>>>> language at hand.
>>>>> I've tentatively changes things to use "error" and "substitute".
>>>>> Question: How about exporting the SCM_FAILED_CONVERSION_* constants
>>>>> and using those instead?
>>>>>
>>>>> E.g, (value->string foo #:errors SCM_FAILED_CONVERSION_ERROR) ?
>>>>
>>>> I’d rather use a symbol:
>>>
>>> Yeah, I thought of that, but the encoding is a string,
>>> so it'd be "#:encoding string #:errors symbol".
>>
>> Right. Looks good to me.
>>
>>> I don't have a strong preference, but using a symbol here while
>>> feeling Schemey feels too weird.
>>> It's not a strong preference though.
>>
>> Using a symbol for #:errors? It would be natural and consistent with
>> the rest of Guile’s API (notably and ‘string->bytevector’,
>> ‘set-port-conversion-strategy!’.)
>
> "works for me"
>
> Though I see %default-port-conversion-strategy is used by more than
> just ports, so it seems reasonable for gdb to use that as the default
> too (obtainable by calling scm_port_conversion_strategy (SCM_BOOL_F)).
Sounds good.
>>>> (value->string foo #:conversion-strategy 'error)
>>>>
>>>> So that has to be converted in C but I think that’s OK.
>>>
>>> #:conversion-strategy is more to type than #:errors but I'm happy to
>>> change it if you want.
>>> Though this is a case where I would not want to support both
>>> #:conversion-strategy and #:errors so whatever we pick is it.
>>
>> Right. Or ‘value->string’ could have this signature:
>>
>> value->string VAL [ENCODING [ERRORS]]
>>
>> The precedent being ‘string->pointer’ and ‘string->bytevector’.
>
> I'd like to stick with the current signature.
OK, fine with me, it’s really no big deal.
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 35+ messages in thread
end of thread, other threads:[~2014-01-19 22:50 UTC | newest]
Thread overview: 35+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-12-24 19:03 [PATCH v1 02/36] Guile extension language: doc additions Doug Evans
2013-12-25 19:27 ` Eli Zaretskii
2014-01-03 21:31 ` Ludovic Courtès
2014-01-04 7:12 ` Eli Zaretskii
2014-01-04 11:57 ` Ludovic Courtès
2014-01-04 14:41 ` Eli Zaretskii
2014-01-04 17:42 ` Ludovic Courtès
2014-01-04 20:00 ` Eli Zaretskii
2014-01-16 4:20 ` Doug Evans
2014-01-18 20:36 ` Doug Evans
2014-01-18 20:52 ` Ludovic Courtès
2014-01-18 20:55 ` Doug Evans
2014-01-19 16:58 ` Eli Zaretskii
2014-01-19 17:19 ` Doug Evans
2014-01-19 17:34 ` Eli Zaretskii
2014-01-19 17:53 ` Doug Evans
2014-01-19 18:10 ` Eli Zaretskii
2014-01-19 21:19 ` Doug Evans
2014-01-18 20:16 ` Doug Evans
2014-01-18 20:42 ` Ludovic Courtès
2014-01-18 21:57 ` Doug Evans
2014-01-19 14:46 ` Ludovic Courtès
2014-01-19 21:37 ` Doug Evans
2014-01-19 22:50 ` Ludovic Courtès
2014-01-18 22:32 ` Doug Evans
2014-01-19 14:47 ` Ludovic Courtès
2014-01-19 15:56 ` Eli Zaretskii
2014-01-19 16:13 ` Ludovic Courtès
2014-01-19 17:05 ` Doug Evans
2014-01-18 20:06 ` Doug Evans
2014-01-18 20:24 ` Eli Zaretskii
2014-01-18 20:53 ` Doug Evans
2014-01-19 16:57 ` Eli Zaretskii
2014-01-19 17:42 ` Doug Evans
2014-01-19 21:01 ` Doug Evans
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).