find-all-instances-by-nameInstance Retrievalfind-instancesfind-instance-by-nameGoTo Top

find-instance-by-name   instance-name &optional unit-class-specifier errorp => unit-instance[Function]

Retrieve a unit instance by its instance name.

Package   :gbbopen

Module   :gbbopen-core

Arguments and values

instance-name     The instance name for the retrieval
unit-class-specifier     An extended unit-class specification (see below; default is t)
errorp     A generalized boolean (default is nil)
unit-instance     A unit instance or nil

The first unit instance found of the specified class(es) that has the specified instance-name if one exists; nil otherwise.

If errorp is true, an error is signaled if no unit instance is found.

Detailed syntax

unit-class-specifier ::= atomic-unit-class | (atomic-unit-class subclassing-specifier) | t

atomic-unit-class ::= unit-class | unit-class-name
subclassing-specifier ::= :plus-subclasses | :no-subclasses | + | =

The shorthand + subclasses specifier is equivalent to :plus-subclasses and = to :no-subclasses.

The :instance-name-comparison-test function (eq, eql, equal, or equalp) specified in define-unit-class is used to match instance-name with the unit-instance's instance name. When strings are used as the names of unit instances, equal (case sensitive) or equalp (case insensitive) should be specified as the comparison function in the unit classes of those unit instances.

See also

Find the hyp unit instance 419:

  > (find-instance-by-name 419 'hyp)
  #<hyp 419 (1835 4791) 0.85 [5..35]>
  > (find-instance-by-name 0 'hyp)
  > (find-instance-by-name 0 'hyp 't)
  No unit instance named 0 of class hyp was found.

Find-instance-by-name can be invoked using the REPL command:

  :fi instance-name [unit-classes-specifier [errorp]]
which sets = to the found unit instance.

The GBBopen Project

find-all-instances-by-nameInstance Retrievalfind-instancesfind-instance-by-nameGoTo Top