doc/new-docstrings.texi

   1
   2 @c module (guile)
   3
   4 @deffn primitive environment? obj
   5 Return @code{#t} if @var{obj} is an environment, or @code{#f}
   6 otherwise.
   7 @end deffn
   8
   9 @deffn primitive environment-bound? env sym
  10 Return @code{#t} if @var{sym} is bound in @var{env}, or
  11 @code{#f} otherwise.
  12 @end deffn
  13
  14 @deffn primitive environment-ref env sym
  15 Return the value of the location bound to @var{sym} in
  16 @var{env}. If @var{sym} is unbound in @var{env}, signal an
  17 @code{environment:unbound} error.
  18 @end deffn
  19
  20 @deffn primitive environment-fold env proc init
  21 Iterate over all the bindings in @var{env}, accumulating some
  22 value.
  23 For each binding in @var{env}, apply @var{proc} to the symbol
  24 bound, its value, and the result from the previous application
  25 of @var{proc}.
  26 Use @var{init} as @var{proc}'s third argument the first time
  27 @var{proc} is applied.
  28 If @var{env} contains no bindings, this function simply returns
  29 @var{init}.
  30 If @var{env} binds the symbol sym1 to the value val1, sym2 to
  31 val2, and so on, then this procedure computes:
  32 @example
  33   (proc sym1 val1
  34         (proc sym2 val2
  35               ...
  36               (proc symn valn
  37                     init)))
  38 @end example
  39 Each binding in @var{env} will be processed exactly once.
  40 @code{environment-fold} makes no guarantees about the order in
  41 which the bindings are processed.
  42 Here is a function which, given an environment, constructs an
  43 association list representing that environment's bindings,
  44 using environment-fold:
  45 @example
  46   (define (environment->alist env)
  47     (environment-fold env
  48                       (lambda (sym val tail)
  49                         (cons (cons sym val) tail))
  50                       '()))
  51 @end example
  52 @end deffn
  53
  54 @deffn primitive environment-define env sym val
  55 Bind @var{sym} to a new location containing @var{val} in
  56 @var{env}. If @var{sym} is already bound to another location
  57 in @var{env} and the binding is mutable, that binding is
  58 replaced.  The new binding and location are both mutable. The
  59 return value is unspecified.
  60 If @var{sym} is already bound in @var{env}, and the binding is
  61 immutable, signal an @code{environment:immutable-binding} error.
  62 @end deffn
  63
  64 @deffn primitive environment-undefine env sym
  65 Remove any binding for @var{sym} from @var{env}. If @var{sym}
  66 is unbound in @var{env}, do nothing.  The return value is
  67 unspecified.
  68 If @var{sym} is already bound in @var{env}, and the binding is
  69 immutable, signal an @code{environment:immutable-binding} error.
  70 @end deffn
  71
  72 @deffn primitive environment-set! env sym val
  73 If @var{env} binds @var{sym} to some location, change that
  74 location's value to @var{val}.  The return value is
  75 unspecified.
  76 If @var{sym} is not bound in @var{env}, signal an
  77 @code{environment:unbound} error.  If @var{env} binds @var{sym}
  78 to an immutable location, signal an
  79 @code{environment:immutable-location} error.
  80 @end deffn
  81
  82 @deffn primitive environment-cell env sym for_write
  83 Return the value cell which @var{env} binds to @var{sym}, or
  84 @code{#f} if the binding does not live in a value cell.
  85 The argument @var{for-write} indicates whether the caller
  86 intends to modify the variable's value by mutating the value
  87 cell.  If the variable is immutable, then
  88 @code{environment-cell} signals an
  89 @code{environment:immutable-location} error.
  90 If @var{sym} is unbound in @var{env}, signal an
  91 @code{environment:unbound} error.
  92 If you use this function, you should consider using
  93 @code{environment-observe}, to be notified when @var{sym} gets
  94 re-bound to a new value cell, or becomes undefined.
  95 @end deffn
  96
  97 @deffn primitive environment-observe env proc
  98 Whenever @var{env}'s bindings change, apply @var{proc} to
  99 @var{env}.
 100 This function returns an object, token, which you can pass to
 101 @code{environment-unobserve} to remove @var{proc} from the set
 102 of procedures observing @var{env}.  The type and value of
 103 token is unspecified.
 104 @end deffn
 105
 106 @deffn primitive environment-observe-weak env proc
 107 This function is the same as environment-observe, except that
 108 the reference @var{env} retains to @var{proc} is a weak
 109 reference. This means that, if there are no other live,
 110 non-weak references to @var{proc}, it will be
 111 garbage-collected, and dropped from @var{env}'s
 112 list of observing procedures.
 113 @end deffn
 114
 115 @deffn primitive environment-unobserve token
 116 Cancel the observation request which returned the value
 117 @var{token}.  The return value is unspecified.
 118 If a call @code{(environment-observe env proc)} returns
 119 @var{token}, then the call @code{(environment-unobserve token)}
 120 will cause @var{proc} to no longer be called when @var{env}'s
 121 bindings change.
 122 @end deffn
 123
 124 @deffn primitive make-leaf-environment
 125 Create a new leaf environment, containing no bindings.
 126 All bindings and locations created in the new environment
 127 will be mutable.
 128 @end deffn
 129
 130 @deffn primitive leaf-environment? object
 131 Return @code{#t} if object is a leaf environment, or @code{#f}
 132 otherwise.
 133 @end deffn
 134
 135 @deffn primitive make-eval-environment local imported
 136 Return a new environment object eval whose bindings are the
 137 union of the bindings in the environments @var{local} and
 138 @var{imported}, with bindings from @var{local} taking
 139 precedence. Definitions made in eval are placed in @var{local}.
 140 Applying @code{environment-define} or
 141 @code{environment-undefine} to eval has the same effect as
 142 applying the procedure to @var{local}.
 143 Note that eval incorporates @var{local} and @var{imported} by
 144 reference:
 145 If, after creating eval, the program changes the bindings of
 146 @var{local} or @var{imported}, those changes will be visible
 147 in eval.
 148 Since most Scheme evaluation takes place in eval environments,
 149 they transparently cache the bindings received from @var{local}
 150 and @var{imported}. Thus, the first time the program looks up
 151 a symbol in eval, eval may make calls to @var{local} or
 152 @var{imported} to find their bindings, but subsequent
 153 references to that symbol will be as fast as references to
 154 bindings in finite environments.
 155 In typical use, @var{local} will be a finite environment, and
 156 @var{imported} will be an import environment
 157 @end deffn
 158
 159 @deffn primitive eval-environment? object
 160 Return @code{#t} if object is an eval environment, or @code{#f}
 161 otherwise.
 162 @end deffn
 163
 164 @deffn primitive eval-environment-local env
 165 Return the local environment of eval environment @var{env}.
 166 @end deffn
 167
 168 @deffn primitive eval-environment-set-local! env local
 169 Change @var{env}'s local environment to @var{local}.
 170 @end deffn
 171
 172 @deffn primitive eval-environment-imported env
 173 Return the imported environment of eval environment @var{env}.
 174 @end deffn
 175
 176 @deffn primitive eval-environment-set-imported! env imported
 177 Change @var{env}'s imported environment to @var{imported}.
 178 @end deffn
 179
 180 @deffn primitive make-import-environment imports conflict_proc
 181 Return a new environment @var{imp} whose bindings are the union
 182 of the bindings from the environments in @var{imports};
 183 @var{imports} must be a list of environments. That is,
 184 @var{imp} binds a symbol to a location when some element of
 185 @var{imports} does.
 186 If two different elements of @var{imports} have a binding for
 187 the same symbol, the @var{conflict-proc} is called with the
 188 following parameters:  the import environment, the symbol and
 189 the list of the imported environments that bind the symbol.
 190 If the @var{conflict-proc} returns an environment @var{env},
 191 the conflict is considered as resolved and the binding from
 192 @var{env} is used.  If the @var{conflict-proc} returns some
 193 non-environment object, the conflict is considered unresolved
 194 and the symbol is treated as unspecified in the import
 195 environment.
 196 The checking for conflicts may be performed lazily, i. e. at
 197 the moment when a value or binding for a certain symbol is
 198 requested instead of the moment when the environment is
 199 created or the bindings of the imports change.
 200 All bindings in @var{imp} are immutable. If you apply
 201 @code{environment-define} or @code{environment-undefine} to
 202 @var{imp}, Guile will signal an
 203  @code{environment:immutable-binding} error. However,
 204 notice that the set of bindings in @var{imp} may still change,
 205 if one of its imported environments changes.
 206 @end deffn
 207
 208 @deffn primitive import-environment? object
 209 Return @code{#t} if object is an import environment, or
 210 @code{#f} otherwise.
 211 @end deffn
 212
 213 @deffn primitive import-environment-imports env
 214 Return the list of environments imported by the import
 215 environment @var{env}.
 216 @end deffn
 217
 218 @deffn primitive import-environment-set-imports! env imports
 219 Change @var{env}'s list of imported environments to
 220 @var{imports}, and check for conflicts.
 221 @end deffn
 222
 223 @deffn primitive make-export-environment private signature
 224 Return a new environment @var{exp} containing only those
 225 bindings in private whose symbols are present in
 226 @var{signature}. The @var{private} argument must be an
 227 environment.
 228
 229 The environment @var{exp} binds symbol to location when
 230 @var{env} does, and symbol is exported by @var{signature}.
 231
 232 @var{signature} is a list specifying which of the bindings in
 233 @var{private} should be visible in @var{exp}. Each element of
 234 @var{signature} should be a list of the form:
 235   (symbol attribute ...)
 236 where each attribute is one of the following:
 237 @table @asis
 238 @item the symbol @code{mutable-location}
 239   @var{exp} should treat the
 240   location bound to symbol as mutable. That is, @var{exp}
 241   will pass calls to @code{environment-set!} or
 242   @code{environment-cell} directly through to private.
 243 @item the symbol @code{immutable-location}
 244   @var{exp} should treat
 245   the location bound to symbol as immutable. If the program
 246   applies @code{environment-set!} to @var{exp} and symbol, or
 247   calls @code{environment-cell} to obtain a writable value
 248   cell, @code{environment-set!} will signal an
 249   @code{environment:immutable-location} error. Note that, even
 250   if an export environment treats a location as immutable, the
 251   underlying environment may treat it as mutable, so its
 252   value may change.
 253 @end table
 254 It is an error for an element of signature to specify both
 255 @code{mutable-location} and @code{immutable-location}. If
 256 neither is specified, @code{immutable-location} is assumed.
 257
 258 As a special case, if an element of signature is a lone
 259 symbol @var{sym}, it is equivalent to an element of the form
 260 @code{(sym)}.
 261
 262 All bindings in @var{exp} are immutable. If you apply
 263 @code{environment-define} or @code{environment-undefine} to
 264 @var{exp}, Guile will signal an
 265 @code{environment:immutable-binding} error. However,
 266 notice that the set of bindings in @var{exp} may still change,
 267 if the bindings in private change.
 268 @end deffn
 269
 270 @deffn primitive export-environment? object
 271 Return @code{#t} if object is an export environment, or
 272 @code{#f} otherwise.
 273 @end deffn
 274
 275 @deffn primitive export-environment-private env
 276 Return the private environment of export environment @var{env}.
 277 @end deffn
 278
 279 @deffn primitive export-environment-set-private! env private
 280 Change the private environment of export environment @var{env}.
 281 @end deffn
 282
 283 @deffn primitive export-environment-signature env
 284 Return the signature of export environment @var{env}.
 285 @end deffn
 286
 287 @deffn primitive export-environment-set-signature! env signature
 288 Change the signature of export environment @var{env}.
 289 @end deffn
 290
 291 @deffn primitive %compute-slots class
 292 Return a list consisting of the names of all slots belonging to
 293 class @var{class}, i. e. the slots of @var{class} and of all of
 294 its superclasses.
 295 @end deffn
 296
 297 @deffn primitive get-keyword key l default_value
 298 Determine an associated value for the keyword @var{key} from
 299 the list @var{l}.  The list @var{l} has to consist of an even
 300 number of elements, where, starting with the first, every
 301 second element is a keyword, followed by its associated value.
 302 If @var{l} does not hold a value for @var{key}, the value
 303 @var{default_value} is returned.
 304 @end deffn
 305
 306 @deffn primitive slot-ref-using-class class obj slot_name
 307 @end deffn
 308
 309 @deffn primitive slot-set-using-class! class obj slot_name value
 310 @end deffn
 311
 312 @deffn primitive class-of x
 313 Return the class of @var{x}.
 314 @end deffn
 315
 316 @deffn primitive %goops-loaded
 317 Announce that GOOPS is loaded and perform initialization
 318 on the C level which depends on the loaded GOOPS modules.
 319 @end deffn
 320
 321 @deffn primitive %method-more-specific? m1 m2 targs
 322 @end deffn
 323
 324 @deffn primitive find-method . l
 325 @end deffn
 326
 327 @deffn primitive primitive-generic-generic subr
 328 @end deffn
 329
 330 @deffn primitive enable-primitive-generic! . subrs
 331 @end deffn
 332
 333 @deffn primitive generic-capability? proc
 334 @end deffn
 335
 336 @deffn primitive %invalidate-method-cache! gf
 337 @end deffn
 338
 339 @deffn primitive %invalidate-class class
 340 @end deffn
 341
 342 @deffn primitive %modify-class old new
 343 @end deffn
 344
 345 @deffn primitive %modify-instance old new
 346 @end deffn
 347
 348 @deffn primitive %set-object-setter! obj setter
 349 @end deffn
 350
 351 @deffn primitive %allocate-instance class initargs
 352 Create a new instance of class @var{class} and initialize it
 353 from the arguments @var{initargs}.
 354 @end deffn
 355
 356 @deffn primitive slot-exists? obj slot_name
 357 Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
 358 @end deffn
 359
 360 @deffn primitive slot-bound? obj slot_name
 361 Return @code{#t} if the slot named @var{slot_name} of @var{obj}
 362 is bound.
 363 @end deffn
 364
 365 @deffn primitive slot-set! obj slot_name value
 366 Set the slot named @var{slot_name} of @var{obj} to @var{value}.
 367 @end deffn
 368
 369 @deffn primitive slot-exists-using-class? class obj slot_name
 370 @end deffn
 371
 372 @deffn primitive slot-bound-using-class? class obj slot_name
 373 @end deffn
 374
 375 @deffn primitive %fast-slot-set! obj index value
 376 Set the slot with index @var{index} in @var{obj} to
 377 @var{value}.
 378 @end deffn
 379
 380 @deffn primitive %fast-slot-ref obj index
 381 Return the slot value with index @var{index} from @var{obj}.
 382 @end deffn
 383
 384 @deffn primitive @@assert-bound-ref obj index
 385 Like @code{assert-bound}, but use @var{index} for accessing
 386 the value from @var{obj}.
 387 @end deffn
 388
 389 @deffn primitive assert-bound value obj
 390 Return @var{value} if it is bound, and invoke the
 391 @var{slot-unbound} method of @var{obj} if it is not.
 392 @end deffn
 393
 394 @deffn primitive unbound? obj
 395 Return @code{#t} if @var{obj} is unbound.
 396 @end deffn
 397
 398 @deffn primitive make-unbound
 399 Return the unbound value.
 400 @end deffn
 401
 402 @deffn primitive accessor-method-slot-definition obj
 403 Return the slot definition of the accessor @var{obj}.
 404 @end deffn
 405
 406 @deffn primitive method-procedure obj
 407 Return the procedure of the method @var{obj}.
 408 @end deffn
 409
 410 @deffn primitive method-specializers obj
 411 Return specializers of the method @var{obj}.
 412 @end deffn
 413
 414 @deffn primitive method-generic-function obj
 415 Return the generic function fot the method @var{obj}.
 416 @end deffn
 417
 418 @deffn primitive generic-function-methods obj
 419 Return the methods of the generic function @var{obj}.
 420 @end deffn
 421
 422 @deffn primitive generic-function-name obj
 423 Return the name of the generic function @var{obj}.
 424 @end deffn
 425
 426 @deffn primitive class-environment obj
 427 Return the environment of the class @var{obj}.
 428 @end deffn
 429
 430 @deffn primitive class-slots obj
 431 Return the slot list of the class @var{obj}.
 432 @end deffn
 433
 434 @deffn primitive class-precedence-list obj
 435 Return the class precedence list of the class @var{obj}.
 436 @end deffn
 437
 438 @deffn primitive class-direct-methods obj
 439 Return the direct methods of the class @var{obj}
 440 @end deffn
 441
 442 @deffn primitive class-direct-subclasses obj
 443 Return the direct subclasses of the class @var{obj}.
 444 @end deffn
 445
 446 @deffn primitive class-direct-slots obj
 447 Return the direct slots of the class @var{obj}.
 448 @end deffn
 449
 450 @deffn primitive class-direct-supers obj
 451 Return the direct superclasses of the class @var{obj}.
 452 @end deffn
 453
 454 @deffn primitive class-name obj
 455 Return the class name of @var{obj}.
 456 @end deffn
 457
 458 @deffn primitive instance? obj
 459 Return @code{#t} if @var{obj} is an instance.
 460 @end deffn
 461
 462 @deffn primitive %inherit-magic! class dsupers
 463 @end deffn
 464
 465 @deffn primitive %prep-layout! class
 466 @end deffn
 467
 468 @deffn primitive %initialize-object obj initargs
 469 Initialize the object @var{obj} with the given arguments
 470 @var{initargs}.
 471 @end deffn
 472
 473 @deffn primitive make . args
 474 Make a new object.  @var{args} must contain the class and
 475 all necessary initialization information.
 476 @end deffn
 477
 478 @deffn primitive slot-ref obj slot_name
 479 Return the value from @var{obj}'s slot with the name
 480 @var{slot_name}.
 481 @end deffn
 482
 483 @deffn primitive builtin-bindings
 484 Create and return a copy of the global symbol table, removing all
 485 unbound symbols.
 486 @end deffn
 487
 488 @deffn primitive object->string obj [printer]
 489 Return a Scheme string obtained by printing @var{obj}.
 490 Printing function can be specified by the optional second
 491 argument @var{printer} (default: @code{write}).
 492 @end deffn
 493
 494 @deffn primitive gethostname
 495 Return the host name of the current processor.
 496 @end deffn
 497
 498 @deffn primitive sethostname name
 499 Set the host name of the current processor to @var{name}. May
 500 only be used by the superuser.  The return value is not
 501 specified.
 502 @end deffn
 503
 504 @deffn primitive flock file operation
 505 Apply or remove an advisory lock on an open file.
 506 @var{operation} specifies the action to be done:
 507 @table @code
 508 @item LOCK_SH
 509 Shared lock.  More than one process may hold a shared lock
 510 for a given file at a given time.
 511 @item LOCK_EX
 512 Exclusive lock.  Only one process may hold an exclusive lock
 513 for a given file at a given time.
 514 @item LOCK_UN
 515 Unlock the file.
 516 @item LOCK_NB
 517 Don't block when locking.  May be specified by bitwise OR'ing
 518 it to one of the other operations.
 519 @end table
 520 The return value is not specified. @var{file} may be an open
 521 file descriptor or an open file descriptior port.
 522 @end deffn
 523
 524 @deffn primitive getpass prompt
 525 Display @var{prompt} to the standard error output and read
 526 a password from @file{/dev/tty}.  If this file is not
 527 accessible, it reads from standard input.  The password may be
 528 up to 127 characters in length.  Additional characters and the
 529 terminating newline character are discarded.  While reading
 530 the password, echoing and the generation of signals by special
 531 characters is disabled.
 532 @end deffn
 533
 534 @deffn primitive setpriority which who prio
 535 Set the scheduling priority of the process, process group
 536 or user, as indicated by @var{which} and @var{who}. @var{which}
 537 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
 538 or @code{PRIO_USER}, and @var{who} is interpreted relative to
 539 @var{which} (a process identifier for @code{PRIO_PROCESS},
 540 process group identifier for @code{PRIO_PGRP}, and a user
 541 identifier for @code{PRIO_USER}.  A zero value of @var{who}
 542 denotes the current process, process group, or user.
 543 @var{prio} is a value in the range -20 and 20, the default
 544 priority is 0; lower priorities cause more favorable
 545 scheduling.  Sets the priority of all of the specified
 546 processes.  Only the super-user may lower priorities.
 547 The return value is not specified.
 548 @end deffn
 549
 550 @deffn primitive getpriority which who
 551 Return the scheduling priority of the process, process group
 552 or user, as indicated by @var{which} and @var{who}. @var{which}
 553 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
 554 or @code{PRIO_USER}, and @var{who} is interpreted relative to
 555 @var{which} (a process identifier for @code{PRIO_PROCESS},
 556 process group identifier for @code{PRIO_PGRP}, and a user
 557 identifier for @code{PRIO_USER}.  A zero value of @var{who}
 558 denotes the current process, process group, or user.  Return
 559 the highest priority (lowest numerical value) of any of the
 560 specified processes.
 561 @end deffn
 562
 563 @deffn primitive cuserid
 564 Return a string containing a user name associated with the
 565 effective user id of the process.  Return @code{#f} if this
 566 information cannot be obtained.
 567 @end deffn
 568
 569 @deffn primitive getlogin
 570 Return a string containing the name of the user logged in on
 571 the controlling terminal of the process, or @code{#f} if this
 572 information cannot be obtained.
 573 @end deffn
 574
 575 @deffn primitive chroot path
 576 Change the root directory to that specified in @var{path}.
 577 This directory will be used for path names beginning with
 578 @file{/}.  The root directory is inherited by all children
 579 of the current process.  Only the superuser may change the
 580 root directory.
 581 @end deffn
 582
 583 @deffn primitive crypt key salt
 584 Encrypt @var{key} using @var{salt} as the salt value to the
 585 crypt(3) library call
 586 @end deffn
 587
 588 @deffn primitive mkstemp! tmpl
 589 mkstemp creates a new unique file in the file system and
 590 returns a new buffered port open for reading and writing to
 591 the file.  @var{tmpl} is a string specifying where the
 592 file should be created: it must end with @code{XXXXXX}
 593 and will be changed in place to return the name of the
 594 temporary file.
 595 @end deffn
 596
 597 @deffn primitive %tag-body body
 598 Internal GOOPS magic---don't use this function!
 599 @end deffn