9.14 gauche.interactive - Utilities for interactive session ¶

Module: gauche.interactive ¶

Provides useful utilities for the interactive session.

This module is automatically loaded when you run gosh interactively.

This module also sets autoloads for functions defined in gauche.reload module (see gauche.reload - Reloading modules), so that those functions can be used by default in interactive development.

Macro: apropos pattern :optional module ¶

{gauche.interactive} Show a list of defined variables whose name matches pattern. If you give a module or a module name module, only the variables defined in that module are listed. Without module, the variables "visible" from the current module are listed.

pattern may be a symbol or a regexp object. If it is a symbol, the variables whose name contains the substring that matches the symbol’s name are listed. If it is a regexp object, the variables whose name matches the regexp are listed.

Some examples:

;; List variables that contains "string" in their name
(apropos 'string)

;; Search in srfi.14 module
(apropos 'char 'srfi.14)

Function: d :optional obj ¶

{gauche.interactive} This is defined as an alias of describe (see Describing instance, for the details). The short name is for the convenience, but in REPL you may find use ,d toplevel command more convenient now.

This module also adds some methods to the generic function describe for built-in objects.

Method: describe ¶

When called without arguments, it describes the object bound to *1, the last result of REPL.

Method: describe (s <symbol>) ¶

Customized describe method for symbols. It shows known bindings for the symbol as well (it is looked for in the loaded modules).

gosh$ ,d 'filter
filter is an instance of class <symbol>
Known bindings for variable filter:
  In module `gauche.collection':
    #<generic filter (2)>
  In module `gauche':
    #<closure (filter pred lis)>

Method: describe (c <char>) ¶

Customized describe method for characters. It shows its Unicode codepoint and general category.

gosh$ ,d #\π
#\π is an instance of class <char>
  (U+03c0, Ll)

Method: describe (n <integer>) ¶

Customized describe method for exact integers. Depending on the value range, it shows several informations: A hexadecimal notation, 1024-base approximated value (useful for memory and storage size), character as Unicode codepoint, and time as Unix time.

gosh$ ,d 1234
1234 is an instance of class <integer>
  (#x4d2, ~ 1.2Ki, #\Ӓ as char, 1970-01-01T00:20:34Z as unix-time)
gosh$ ,d 12345678
12345678 is an instance of class <integer>
  (#xbc614e, ~ 11Mi, 1970-05-23T21:21:18Z as unix-time)
gosh$ ,d 12345678901234567890
12345678901234567890 is an instance of class <integer>
  (#xab54a98c_eb1f0ad2, ~ 10Ei)

Method: describe (r <rational>) ¶

Customized describe method for exact rationals. It shows the floating point number as coerced into inexact.

gosh$ ,d 1234/5678
617/2839 is an instance of class <rational>
  inexact: 0.2173300457907714

Method: describe (d <real>) ¶

Customized describe method for inexact reals. It shows binary representation of the flonum, and rational representation as coerced into exact.

gosh$ ,d 3.14159265358979
3.14159265358979 is an instance of class <real>
  mantissa: #x+19_21fb_5444_2d11   exponent: -51    hex: #x4009_21fb_5444_2d11
  exact: 144029661/45846065

Method: describe (c <complex>) ¶

Customized describe method for complex numbers. It shows polar representation as well.

gosh$ ,d (expt -2 1/4)
0.8408964152537146+0.8408964152537146i is an instance of class <complex>
  polar: 1.1892071150027212@0.7853981633974483  (@0.25pi)

Method: describe (p <procedure>) ¶

Method: describe (p <macro>) ¶

Customized describe method for procedures and macros, showing the source location if avaiable. For the procedure, its type signature is shown as well (procedure-type, see Procedure class and applicability).

gosh> ,d display-filled-text
#<closure (display-filled-text text :key (port (current-output-port))
(indent 0) (hanging 0) (width 65) (lead-in #f) (start-column #f))> is
an instance of class <procedure>
Defined at "/usr/share/gauche-0.98/0.9.15-p1/lib/text/fill.scm":111
type: #<^ <top> * -> *>
slots:
  required  : 1
  optional  : #t
  optcount  : 1
  locked    : #f
  currying  : #f
  constant  : #f
  info      : (display-filled-text text :key (port (current-output-port))
  setter    : #f

Method: describe (g <generic>) ¶

Customized describe method for generic functions. It shows the list of known methods, with the specializer list and the source location of definition if known.

gosh$ ,d describe
#<generic describe (11)> is an instance of class <generic>
slots:
  name      : describe
  sealed    : #f
  info      : describe
  methods   : (#<method (describe <macro>)> #<method (describe <procedure>
methods:
  (<macro>)            ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":223
  (<procedure>)        ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":215
  (<method>)           ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":208
  (<generic>)          ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":189
  (<real>)             ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":172
  (<rational>)         ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":160
  (<integer>)          ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":128
  (<char>)             ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":123
  (<symbol>)           ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":118
  ()                   ; "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":116
  (<top>)

Method: describe (m <method>) ¶

Customized describe method for methods. It shows the source code location if available.

gosh$ ,d (car (~ describe'methods))
#<method (describe <macro>)> is an instance of class <method>
Defined at "/usr/share/gauche-0.98/0.9.15-p1/lib/gauche/interactive.scm":223
slots:
  required  : 1
  optional  : #f
  method-locked: #f
  leaf?     : #t
  generic   : #<generic describe (11)>
  specializers: (#<class <macro>>)
  info      : (describe <macro>)

Function: info symbol ¶

{gauche.interactive} Displays an entry of the named function, syntax, module or class from Gauche’s info document. If an environment variable INFOPATH is defined, this function searches for the info file from the directories in it. Otherwise, this function guesses info file location from the gosh’s library directory. If the info file can’t be found, an error is signaled. So this function doesn’t work if you haven’t installed info file.

If no entry exactly matching with symbol is found, the procedure tries to look for similar named entries:

gosh> (info 'stirng)
There is no entry for stirng.
Did you mean:
  string>
  string?
  string=
  string<
  string
  :string

(If you want to search entries using pattern, see info-serach below.)

If the current output port is a tty, the info page is displayed by a paging software. If an environment variable PAGER is defined, it is used as a paging software. Otherwise, this function looks for less and more in this order from the directories in PATH. If none of them is found, or the output port is not a tty, this function just displays the page.

The first invocation of this function in a session takes some time to parse the info file.

NB: When you use less as a pager, make sure you set it to handle utf-8 characters (e.g. setting LESSCHARSET environment variable to UTF-8), or you’ll see some escaped sequences on the screen.

NB: If you invoke gosh within the build tree, using -ftest option, info reads the info files in the build tree if they exist.

Function: info-search regexp ¶

{gauche.interactive} Lists info entries matching regexp. See info above about where the info files are searched.

Function: ed filename-or-procedure :key editor load-after ¶

{gauche.interactive} Invoke an external editor to open the named file, or the file containing the definition of the given procedure (if it can be known). For the latter, it uses source-location procedure to find out the source code location (see Debugging aid).

The name of the editor to invoke is determined as follows:

1. The editor keyword argument.
2. The value of the variable *editor* in the user module, if defined. This is handy that you can set this in your .gaucherc.
3. The value of the environment variable GAUCHE_EDITOR.
4. The value of the environment variable EDITOR.

If none of the above is defined or #f, the procedure prompts the user to type in the name of the editor.

Once the editor name is obtained, it is invoked as a subprocess, with the following format:

EDITOR +lineno filename

The lineno is an integer line number, 1 being the first line. The editor is expected to locate the cursor on the specified line.

Once the editor process exits, the procedure checks if the named file is updated. If so, it may load the file, according to the value of the load-after keyword argument. It may take one of the following values:

#t

Load the file automatically if it’s updated.

#f

Do not load the file.

ask

The symbol ask cause the procedure to prompt the user whether it should load the file. This is the default.