xemacs-21.4 / man / br-design.texi

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
\input texinfo  @c -*-texinfo-*-

@c %**start of header (This is for running Texinfo on a region.)
@setfilename br-design.info
@settitle The OO-Browser Design
@c %**end of header (This is for running Texinfo on a region.)
@synindex vr fn

@iftex
@finalout
@end iftex

@titlepage
@sp 4
@center @titlefont{Design Issues in the OO-Browser}
@sp 5
@center Bob Weiner
@center Motorola Inc.

@sp 2
@center March 1991 and January 1993

@end titlepage
@page

@node Top, Design Issues, (dir), (dir)
@unnumbered Abstract

The OO-Browser is an efficient object-oriented class browser.  It has a
completely direct-manipulation interface with multiple modalities.  It
may be used for both system exploration and for browsing purposes as
part of a professional software development tool chest.  It quickly
displays and provides views of complicated inheritance trees, making
it an important tool for understanding object-oriented systems.  It is
integrated with a powerful editing environment that can be customized
to meet personal work styles.

The OO-Browser is the first such tool to work with a multiplicity of
object-oriented languages.  It currently supports five object-oriented
languages (Eiffel, C++, Objective-C, CLOS (Lisp), and Smalltalk) and
one documentation language (GNU Info).  Adding a new language is fairly
straightforward and can be done in one to five days.

This paper has three main parts.  The first discusses issues in the design
of the OO-Browser, emphasizing its unique aspects.  Issues pertinent to
all class browsers are touched upon and an explanation is given for how
the OO-Browser approaches each of them.

The second part examines the actual implementation.  It concentrates on
the user interface aspects and how they empower the user.  Novel
concepts introduced by the browser are discussed.  They include: a
merged help/command menu construct, dynamic method location, Environment
class groupings, and browsing based on source code only.

The third part suggests directions for future work.

@menu
* Design Issues::               
* Design Specifics::            
* Further Work::                
* Conclusion::                  

 --- The Detailed Node Listing ---

Interactivity

* Build Speed::                 
* Query Response Time::         

Textual User Interface

* Environments::                

Direct Manipulation

* In C++::                      
* In Eiffel::                   

Alternate Interfaces

* Environments::                

Environments

* Env Create::                  
* Env Build::                   
* Env Load::                    
* Env Save::                    
* Env Update::                  

Expand Query Types

* Dynamic Object Browsing::     
* Tool Integration::            
* Graphical Interface::         
* Version Control::             
@end menu

@node Design Issues, Design Specifics, Top, Top
@chapter Design Issues in the OO-Browser

@section Background

The OO-Browser was initially conceived for utilitarian reasons.  A
simple, fast class browser was needed for a development project based
in the object-oriented language, Eiffel.  The browsers available for
Eiffel were deemed weak and of not much value.

Since I had built tools in the past on top of the GNU Emacs
environment, I knew that this could be a rapid process, even when a
high-level interface was needed.  GNU Emacs was also the preferred local
editor, so close integration with it was considered a benefit.

A simple prototype of the browser was completed in two days from
conception to implementation.  Its user interface was based in part on
the Smalltalk-80 class browser under the assumption that this interface
had been developed over a long period of time to maximize developer
productivity.

The prototype showed promise as a tool that would be useful for other
languages besides Eiffel.  I identified C++ and Objective-C as the
languages most needy of such a tool.  A separate prototype version for
each of these languages was done in a single day as a dramatic
demonstration of the generality of the concept.

The road from prototype to a professional tool required a good amount
of work over an extended period as an independent project.  Browser
performance, structure and features were improved throughout this
period.  A number of new languages were also added and all of these were
integrated via a single common kernel.  A complete user manual was
written.  The shared kernel browser was dubbed the OO-Browser.

The architecture layered on top of GNU Emacs turned out to be a great
success for a number of reasons.

@itemize @bullet

@item
Both computational and interaction speed of the browser exceeded
most people's expectations.

@item
Integration with Emacs meant that when interacting with the browser,
people could reuse the editing skills they had acquired from other
tasks.

@item
The flexibility of Lisp provided a direct means for implementing
the common browser kernel.
@end itemize

@menu
* Design Goals::
* Interactivity::
@end menu

@node Design Goals, Interactivity, Design Issues, Design Issues
@section Design Goals

The OO-Browser was initially designed in response to the lack of easy to
use class browsers in the many emerging object-oriented language
environments of today.  In fact, many environments still consist of
nothing more than a compiler and a debugger.  Even those environments
that contain browsers, often offer weak ones with barely usable interfaces.
The well-known Smalltalk environments [@cite{Goldberg 83}] are the only
notable exceptions.  Some excellent C++ support environments are now
just emerging (Saber-C++, ObjectWorks for C++, Field, ET++).

The OO-Browser was meant to be small, fast, and easy to use.  So far it
has met all of those goals.  There are three main uses that I see for a
class browser:

@table @strong
@item Design Tool
A browser should allow for the location of classes
that meet a specified set of criteria.  It should be just as easy to
determine that no such class exists.  A more difficult task is to
determine similar classes that might be of interest to the user.

@item Exploration Tool
The browser should allow one to explore libraries of classes as well as
full programs.  It should be especially useful when one is unfamiliar
with the set of components that one is browsing.

@item Engine Interface
The browser engine should be usable without the user interface, so that
one can use the browser features while editing and so that programs may
use the browser capabilities with their own user interfaces.
@end table


The quality with which a browser provides the above services can be surveyed by
examining a number of issues:

@table @strong
@item Interactivity
The browser should preprocess source files quickly.
It should also answer queries with minimal delay so that the user
maintains a sense of interactivity.

@item Usability
It should be easy to invoke and just as easy to put
away, so that it does not distract from other tasks in which the
developer is involved.

@item Consistency
A user of the browser should be able to learn a small
set of interaction techniques and thereby access a broad set of
functions.  He should also be able to build on these fundamental
concepts to achieve higher levels of proficiency with the tool.

@item Scalability
It should scale up well and maintain its speediness
with libraries of thousands of classes.

@item Integration
It should integrate well with a program editing
environment, providing language specific features to speed the
development process.

@item Extensibility
The browser should be extensible by a competent programmer.
@end table

@noindent
Let us discuss separately each of these issues to see how the OO-Browser
addresses them.


@node Interactivity,  , Design Goals, Design Issues
@section Interactivity

There are two interactivity concerns associated with most class
browsers, speed of database construction and query response time.

@menu
* Build Speed::                 
* Query Response Time::         
@end menu

@node Build Speed, Query Response Time, Interactivity, Interactivity
@subsection Build Speed

The first concern involves the speed with which the browser can
extract any information it needs in building a cache or database of
information from the code.  If this is a long, involved process, users
will want it performed in a batch fashion so that it does not delay
their workflow.  The rebuilding of databases at night or on idle
processors is a common solution.  The drawback to this is that it
likely precludes the use of the browser for immediate exploration of
newly discovered or procured class libraries.  If on the other hand,
this building process is rapid, the user will be much more likely to
experiment with the tool and to use it for exploring new class sets.

The OO-Browser takes the latter approach.  It builds a minimal lookup
structure derived directly from class source.  It assumes that the
classes it scans are syntactically correct and therefore needs parse
only a small fraction of the code scanned.  This scanner can
distinguish between declarations and definitions.  It recognizes
commented passages and so ignores valid definitions embedded within
them.

The result is that even though this scanning code has not yet been
optimized, it can scan hundreds of classes a minute on a single
processor machine.  This speed is fast enough that when users come
upon an unfamiliar class library, they simply ask the browser to scan
it and wait for its initial display of the class list found from the
scan.

Still, on some platforms, the lookup structures for very large class
libraries may be better built in a batch fashion.  The OO-Browser
includes a mechanism for doing so via a simple command line invocation
which can be scheduled with the UNIX 'cron' utility.

@node Query Response Time,  , Build Speed, Interactivity
@subsection Query Response Time

Most browsing operations represent some form of query.  Show the
ancestors for this class.  List all classes that contain the string,
'window'.  How many classes are in this library?

Query responses must therefore be fast enough to give the user a sense
of close knit interaction.  This is the reason much effort is often
put into the database back ends of program support environments.

The OO-Browser instead uses basic caching techniques to optimize the
most common queries.  These techniques work surprisingly well, even
for environments containing thousands of classes.

One of the most common queries given to the OO-Browser is to show
descendency or ancestry graphs for a set of classes.  On a
workstation, a graph involving about 500 classes can be computed and
displayed in three to four seconds.  Smaller queries receive
instantaneous replies.


@section Usability

With the emergence of multi-windowed graphical interfaces in recent
years, man-machine interaction has become much more complex.  Many
environments have been converted to these interfaces in the name of
ease of use, but often the user is left with less control than he had
before.

A common example is the window pile problem that results when many
applications share a display space and each creates a new window every
time a simple action, like setting a parameter value, must be
performed.  A user often is left to use simple push and pop funtions
to wade through the window layers to find one he may want.

This sort of behavior was considered unacceptable for the OO-Browser.
To avoid those situations, the browser performs its own window
management.  The browser is invoked by a key press or menu selection.
It then displays all of its windows.  Another key can be used to put
the browser away, essentially to hide it from view.  All of its
windows then disappear.  Since the user has not actually quit from the
browser, when he invokes it again, his entire context is restored,
both visually and computationally.  With such an interface, browsing
becomes a basic reflex.  Invoke browser.  Locate desired class for
editing.  Hide browser, leaving selected class visible.  Continue work.


@section Consistency

Consistency and usability go hand in hand.  Techniques of good design
dictate that a designer should play upon the skills that his user base
brings with them.  New interface metaphors should be carefully thought
out.  Their benefits should be weighed against the cognitive strain
that new users will necessarily endure.

Editing skills, for example, become almost hard-wired into skilled
computer users psyches so that little conscious action is needed to
perform common tasks.  Yet often, each new application offers a
different editing model without adding any new editing benefits for the
user.  This sort of design is especially egregious in a tool-based
environment where the designer knows that his users will likely need a
variety of tools to do their work.

The OO-Browser avoids this sin by integrating with the popular GNU
Emacs editor.  Since Emacs provides a modeless editing environment in
which any command may be executed at any time, all normal Emacs
editing funtions are available while the user is within the browser's
Emacs interface.  So, for example, if one already knows how to search
an edit buffer for a particular string, one simply does the same thing
within the browser.

Browser key bindings are carefully selected to be both mnemonic and
consistent with standard Emacs key usage.  In mouse-based
environments, direct manipulation techniques are supported, so the
user can select the entity he wants to operate on and the command he
wants to apply without the need to memorize any key names.


@section Scalability

The term educational programming environment is too often used to
describe tools too weak to be used for real development projects.
This is a common syndrome associated with highly interactive tools.
They simply don't scale up for use in large, distributed projects.

@noindent
The symptoms of this syndrome in browsing tools include:
@enumerate
@item
the ability to browse code from only one root directory at a time;

@item
support for only one browsing environment under which all classes must
be lumped;

@item
slow performance with large class sets;

@item
ability to operate on only one class/category at a time;

@item
no portability of the interface or tool itself.
@end enumerate

The OO-Browser has so far seemed to scale well.  It uses the concept
of Environments to address symptoms (1) and (2).  For each instance of
the OO-Browser, the user selects a current Environment which he wants
to browse.  (Environments are discussed later in this paper.)  Each
Environment may include source from any number of directories,
distributed across machines using file sharing systems like NFS or
Apollo's Domain system.  Each Environment contains classes written in
a single language.  The user may select another Environment at any
time and thereby switch languages.

Symptom (3) has been addressed in the previous section on @strong{Query
Response Time}.

Symptom (4) does not exist in the OO-Browser.  Virtually all commands
that can be applied to a single class may also be applied to any class
list returned by a browser query.

Symptom (5) is not a problem either.  The OO-Browser is extremely
portable.  The browser runs on any UNIX system on which GNU Emacs
runs, which is virtually every one.  Therefore, a user can run the
browser on platforms from any vendor.  The graphical interface to the
OO-Browser runs under the portable X Window System.  It currently uses
a Motif-based interface, but may in the future be converted to an even
more portable interface toolkit.


@section Integration

A browsing tool is but one piece of the development environment.  It
must therefore not only do its job but also support the style of
program development followed at a site.

The OO-Browser supports object-oriented development.  Object-oriented
development is necessarily incremental and component-based.  The browser
allows one to edit a class and then incrementally update the browsing
environment with any changes.  It lets developers think in terms of
classes, the building blocks of object-oriented languages, without
regard to where the classes are located.

Each browser language mode is tailored to the specifics of the
language.  For Eiffel, it supports the location of method definitions
that have been repeatedly renamed throughout the inheritance
graph.  For C++, support for method overloading and multiple
inheritance is included.

Editor integration is critical in a browser, as this is the mainstay
tool for program development.  Surprisingly, this is not universally
understood.  Stepstone Corporation's Objective-C browser still does
not allow one to edit classes that it displays.  Only the newest
versions of Interactive Software Engineering's Eiffel browsers allow
one to edit classes; one still cannot simply select a class name
returned as a result of a query in order to edit it.

Besides the Emacs interface, the current OO-Browser version allows the
use of alternate editors, so that a user need not become familiar with
the Emacs editing model if he is not already.  It still uses the Emacs
lisp engine as a back end to process browser requests, but allows the
user to edit classes with whatever program he likes.  The graphical
interface also supports the use of any desired editor.  For non-Emacs
users, it is a simple matter to produce a turnkey command that allows
use of the browser without any prior knowledge.


@section Extensibility

The whole open systems phenomenon arose after corporate users tired of
relying on vendors to provide proprietary solutions to simple
problems.  The choice of an open system allows one to seek software
solutions and system support from a larger pool of organizations than
with closed systems.

Similar needs are now arising in the programming support arena.
Closed systems seldom meet all of the needs of the user base.  Without
a back end customization language, users are left to the whims of the
developer to decide whether a feature is important enough to include.
Macro language provisions are too weak to allow all the changes that may be
desired, so a full programming language interface is needed for
advanced user customization.

Simple customizations are performed by setting values of attributes
included as user variables in the OO-Browser.  More advanced
customizations, like the addition of a new query type are performed in
GNU Emacs Lisp.  Most of the OO-Browser is written in the Lisp dialect.
It is a fully interpreted language and so is natural to use as a
customization language since each change may be immediately tested.

As noted earlier, an entire language interface can be built in a
matter of days, demonstrating both the flexibility of Lisp and of the
language interface provided by the OO-Browser.


@node Design Specifics, Further Work, Design Issues, Top
@chapter OO-Browser Design Specifics

@menu
* Textual User Interface::      
* Graphical Tree Display::      
* Direct Manipulation::         
* Alternate Interfaces::        
* Environments::                
@end menu

@node Textual User Interface, Graphical Tree Display, Design Specifics, Design Specifics
@section Textual User Interface

The screen shot on the following page highlights the major components
of the OO-Browser textual user interface.  The windows across the top of the
OO-Browser screen are called @dfn{class listing windows}; they display
@dfn{class listing buffers} with a single class name per line.  The
@dfn{class viewer window}, sometimes simply referred to as the
@dfn{viewer window}, fills the bottom half of the screen.  It is used
to display class source and summary information.  Pictured here in the
viewer window is the command help/menu buffer, summarizing the browser's
command key bindings.

The number of listing windows is limited only by the screen width.  The
width of the windows may be interactively adjusted to permit more or
fewer windows for particular tasks.  CLOS identifiers are typically much
longer than Eiffel identifiers, so one would want to raise the window
width when operating on CLOS classes.

@menu
* Hierarchy Listings::          
@end menu

@node Hierarchy Listings,  , Textual User Interface, Textual User Interface
@subsection Hierarchy Listings

The directed, acyclic graph relations prevalent in languages with
multiple inheritance are translated into textual hierarchies by repeating
elements with multiple parents throughout the tree structure.  So if
class B inherits from C and class C inherits from P1, P2 and P3.  One
view of descendants would show:

@example
	P1
	  C
	    B
	P2
	  C ...
	P3
	  C ...
@end example

The ellipses indicate that C's subtree has been expanded somewhere
above, so it is not repeated.  The resultant structure is easy to
understand and very useful.  This sort of structure allows one to use
the browser on a text-only terminal and still be able to visualize
significant inheritance relations.

@noindent
Queries that may be made under this interface include:
@itemize @bullet
@item
show parents
@item
show children
@item
show ancestors
@item
show descendants
@item
total selected classes
@item
select classes matching regular expression or string.
@end itemize

@noindent
All of these commands may be applied to any grouping of classes,
eliminating the sequential bottleneck found in many other such tools.

All displays that move up the inheritance tree consume a listing window
to the left of the current one.  Descendancy displays do the opposite
and select the window to the right.  At the edges of the display, the
window selected wraps around to the other side.  An exit command
clears the current listing buffer and returns to the last one,
regardless of how the user walks up and down the trees.  Ancestor
listings may be shown with parent down to root (highest level ancestor)
or inverted, with root down to parent, so that children are always
displayed below their parents.

The class matching command is fast and easy to use.


@noindent
Besides queries, a few of the useful commands provided are:
@itemize @bullet
@item
sort classes
@item
view class source
@item
edit class source
@item
save class listing.
@end itemize

The editor is user selectable.  The ability to sort any class listing
simplifies class location.  The @emph{save class listing} command is
useful to record the output of interesting queries for documentation and
reference purposes.

All browser queries and commands work with class source code only.  This
makes the tool useful in exploratory situations where a compiler is not
available.  It also ensures that the browser receives up to date
information from which to work.


@node Graphical Tree Display, Direct Manipulation, Textual User Interface, Design Specifics
@section Graphical Tree Display

The graphical interface to the browser provides a compact tree-based
view of a set of classes or an Info manual.  (A sample enlarged display
is shown on the following page.  It uses the same set of classes as the
prior picture of the textual display, for ease of comparison.)  This
interface supplements the textual interface so that the user can easily
comprehend large inheritance structures.  (Nodes with more than one
incoming pointer (parent) are repeated throughout the tree, but their
subtrees are excised and replaced with the ellipses symbol, ..., just as
in the textual interface.  Subtrees may be collapsed or expanded
interactively.  Scrolling mechanisms are limited to horizontal and
vertical scroll bars, but a panning construct is being considered.

When the user finds a class he is interested in, he simply selects it
with the same mouse button he uses to select classes in the textual
interface.  The node is highlighted and the associated class is
displayed in the text editor.

The graphical interface can be invoked on any portion of the current
browser Environment.  One may for instance, obtain a list of classes
with 'Stack' in their name and then through a mouse click, invoke the
graphical browser on just the descendancy trees of the selected classes.

Any number of graphical browser views may be shown at the same time.
Each view is independent, so each may provide a view of any environment
previously created by the OO-Browser.  All views can communicate with a
single instance of the editor, so that one can maintain onscreen views
of multiple environments, even across languages, and simply select any
node from any view to access the corresponding source.

A new, window-system independent version of the graphical interface
provides double buffered display updates for smooth scrolling, a panner
device for rapid movement throughout a view, and a number of useful tree
display representation alternatives.

The graphical interface is presently somewhat limited, but that is only
because it is so new.  It is a straightforward matter to provide a user
of the graphical interface with the full complement of browser commands
by adding the commands to a set of menus and sending each command to the
browser engine as it is selected.


@node Direct Manipulation, Alternate Interfaces, Graphical Tree Display, Design Specifics
@section Direct Manipulation

To maximize the utility of the displays presented to the user, most
displayed entities may be operated upon through simple mouse clicks.
For example, clicking on a class name displays the associated class
definition.  Clicking to the left of a class displays its ancestors and
to the right its descendants.  Selection of the ellipses after a class
name shifts the display focus to the class' descendants list.

A click in an empty listing buffer may display the browser help text or
a menu of language-specific source files which the user has browsed.
This menu permits random access selection of any class file.

A click on any of the command descriptions in the help display executes
the associated command on the previously selected item.  This is such a
useful, intuitive means of control that it is surprising that one never
sees this capability in application interfaces.



@menu
* In C++::                      
* In Eiffel::                   
@end menu

@node In C++, In Eiffel, Direct Manipulation, Direct Manipulation
@subsection In C++

@cindex C++
Entities in C++ programs may be selected for inspection with the middle
mouse button.  Most importantly, once a class header file is displayed,
one simply clicks on a method declaration to see its corresponding
definition.  Each feature declaration should be given separately to
ensure accurate parsing.  If the method is inherited from another class,
a message at the bottom of the screen describes which class the method
is defined in once the browser displays the method definition.

The browser dynamically handles full function overloading and numerous
other complex mappings between declaration and definition that are
permitted in C++.  A complex set of pattern matching heuristics are used
which work in almost all cases.  This is a novel approach that speeds
the construction of Environments, since no normalization is performed on
function signatures until they are operated upon.  All other browsers
rely on preprocessing techniques which store a normalized form of the
declaration to match against the definition signature.

Parent classes may be browsed in a similar manner by clicking on their
names in an inheritance or declaration clause.  Multiple inheritance is
fully supported.  There is no support as yet for locally scoped classes.

Include files may be browsed by selecting their inclusion declarations
(@strong{#include} ...).



@node In Eiffel,  , In C++, Direct Manipulation
@subsection In Eiffel
@cindex Eiffel
Selection of a feature name in an export clause displays the feature
definition, even if it is renamed several times within ancestors.
Parent classes may be browsed in a similar manner by clicking on their
names in an inheritance or declaration clause.

The following example of locating a renamed feature is taken from an
actual set of Eiffel library classes:

@example
User selects feature @emph{subwindow} of @emph{POPUP_MENU}
   inherited from @emph{WINDOW}
   which renames @emph{child} as @emph{subwindow}
      inherited from @emph{TWO_WAY_TREE}
      which renames @emph{active} as @emph{child}
         inherited from @emph{TWO_WAY_LIST}
            inherited from @emph{LINKED_LIST}
            which defines @emph{active}.
@end example

The browser would display the feature @emph{active} and explain to the
user that feature @emph{subwindow} of class @emph{POPUP_MENU} is
inherited from feature @emph{active} of class @emph{LINKED_LIST}.
Location of this sort of feature definition would be incredibly tedious
without programmatic support.

If a feature reference is selected within a non-deferred (non-abstract)
class, then deferred features are automatically ignored when searching
for the feature definition.  If the reference class is deferred
(abstract), the first matching ancestral feature found is selected,
whether it is deferred or not.

The algorithm used to locate features is dynamic, so if another class
is inserted into the inheritance structure given above, the feature
definition still will be located properly.



@node Alternate Interfaces, Environments, Direct Manipulation, Design Specifics
@section Alternate Interfaces

Earlier we mentioned that the computational back end, the @dfn{engine}
part of the browser should be available for use without its interface.
The interactive nature of Lisp allows the prototyping and delivery of
different interfaces quickly.  For example, the graphical interface to
the browser was originally a standalone tree drawing program.  A
prototype interface to the browser was developed in a matter of two
hours, with most of the time spent examining the unfamiliar code in the
tree drawing program.

@noindent
Other simple but extremely useful interfaces we have provided include:
@itemize @bullet
@item
the ability to perform completion on type identifiers when programming;

@item
support for compiler error parsing when the compiler outputs only the
class name and line number of the error;

@item
a command that prompts for a class name and then edits the class,
with class name completion included.
@end itemize

@noindent
All of these were straightforward to implement based upon the browser
engine functions.

@menu
* Environments::                
@end menu

@node Environments,  , Alternate Interfaces, Design Specifics
@section Environments

@cindex Environment, the
@cindex Library search list
@cindex System search list
Whenever the OO-Browser is in use, an Environment is selected.  An
Environment may be built or simply specified.  An @dfn{Environment
specification} tells the browser what to include in the construction of
an Environment.  (@xref{Env Create, , Creating Envir Specs}, for more
info.)  An OO-Browser @dfn{Environment} includes a set of inter-class
relationships together with a few browser settings.  The phrase,
@dfn{the Environment}, refers to the current OO-Browser Environment.
Many browser commands depend on information in the Environment.  A
summary of the components of the Environment may be displayed any time
during browser use.  See the next page.@refill

The set of classes included in an Environment is specified by two lists
of directories, below which all of the Environment's class source files
are to be found.  (The OO-Browser will automatically search
sub-directories below the directories specified.)  The first list of
directories is called the @dfn{Library search list}; it defines the
locations of stable, typically reusable classes that have been released
for general use.  The second list is called the @dfn{System search
list}; it defines the locations of unreleased classes being developed,
often for a particular system.  All class names within a single
Environment must be unique to ensure proper operation of the browser.
This also implies that the Library and System class sets be disjoint.

The OO-Browser lets one create, update and save Environments.  Once an
Environment file has been created, it may be loaded at any time.  The
browser will then use this Environment for all of its operations until
another one is loaded.

The browser maintains a separate Environment for each programming
language on which it is used.  Thus, if one switches from Eiffel to
C++ browsing and then back to Eiffel browsing, the Eiffel environment
will not need to be reloaded; it will appear immediately and the
screen will appear as if the Eiffel OO-Browser were invoked for the
first time.  Only one Environment per language is kept in memory.

@cindex Environment, default
There is a default Environment file name for each browser-supported
language; these names are unique to each user account on the system:
@file{~/.br-eif-env}, @file{~/.br-c++-env}, @file{~/.br-objc-env}, 
@file{~/.br-clos-env}, @file{~/.br-smt-env}, and @file{~/.br-info-env}.
Environment files are automatically created and loaded by the OO-Browser
so that one need never become familiar with their format.@refill

Environments provide a simple, uniform way of managing numerous class
libraries.  A simple extension to the browser is planned which will
allow one to interactively select Environments as one typically does
with files.  Each Environment stores an indication of what language its
classes are in, so it can dictate which browser version to invoke.


@menu
* Env Create::                  
* Env Build::                   
* Env Load::                    
* Env Save::                    
* Env Update::                  
@end menu

@node Env Create, Env Build, Environments, Environments
@c  node-name,  next,  previous,  up
@subsection Creating Environment Specifications

@cindex Environment specification
Environment specifications are useful when one wants to describe a
number of Environments to the OO-Browser but wants to defer their
construction until later.  Large environments then can be built
overnight.  @xref{Env Build, , Building Environments}, for more
info.@refill

@findex br-env-create
@cindex initialization file
Every Environment must be specified before it can be built or used.
Thus, specifying an Environment is the first step in creating it.
An Environment create command interactively prompts for all information
necessary to specify and to build an Environment.  This command may 
be invoked repeatedly to quickly specify a number of different
Environments.@refill

@noindent
Here are the Environment specification components for which the
OO-Browser prompts:
@table @code
@item System search directories
List of directories below which other System directories containing
class source code and directories of class source files may be found.

@item Library search directories
List of directories below which Library files of class source code
and directories of class source files may be found.

@item Save all Environment lookup tables?
@emph{Yes} means that a complete set of lookup tables should be saved as
a class Environment.  @emph{No} means that some lookup tables should be
built from others when the tables are loaded from an Environment file.
Answering @emph{yes} doubles the size of each Environment file but
slightly speeds the loading of an Environment into the browser.
@emph{No} is the default that works best on most computers.
@end table


@node Env Build, Env Load, Env Create, Environments
@c  node-name,  next,  previous,  up
@subsection Building Environments

@cindex Environment building
An Environment specification tells the OO-Browser what to include in the
Environment, but the Environment still must be built before use.  When
class names or locations have changed or the Environment's inheritance
structure is modified, the Environment must be rebuilt.  For small
Environment changes, one may use the class addition and deletion
features of the browser.  @xref{Env Update, , Updating Environments},
for more info.@refill

@cindex Environment building, batch
@cindex large Environments
Very large Environments may be built overnight by invoking Emacs in
batch mode at a scheduled time.  Note that the Environment specification
file must have been created prior to execution of this command so that
the browser knows what to build.

@node Env Load, Env Save, Env Build, Environments
@c  node-name,  next,  previous,  up
@subsection Loading Environments

@cindex Environment loading
A new Environment may be loaded for use at any time within the
OO-Browser.  One may either select the load Environment command from
the on screen OO-Browser command summary or simply use the
language-specific browser invocation command that was originally used to
start the browser, except in this case, it should be preceded by a
prefix argument.  For example, the @code{(eif-browse)} command, would
prompt for and then load a new Eiffel environment, even when one is
already browsing an Eiffel environment.


@node Env Save, Env Update, Env Load, Environments
@c  node-name,  next,  previous,  up
@subsection Permanently Storing Environments

The OO-Browser automatically builds and saves Environments in most
cases.  Occasionally one may find a need to force the Environment to
be saved to a file, as in the case when one wants to save an Environment
under a different file name.

The Environment save command is used to force an Environment save to
occur.  The command prompts for a file to save to, with the default
as the current Environment file name.
 

@node Env Update,  , Env Save, Environments
@c  node-name,  next,  previous,  up
@subsection Updating Environments

@findex br-add-class-file
@cindex class, adding to Environment
@cindex class, replacing in Environment
@cindex Environment, adding classes
@cindex Environment, replacing classes
@cindex initialization file
A file containing class definitions may be added to the Environment with
the add class file command.  This will prompt for the file name, scan
the file, and then update the Environment.  If a class defined in the
file is already in the Environment, its information will be replaced
with the information gathered from the file; otherwise, the class will
be added to the Environment.

@cindex Environment, adding individual classes
To add a single class from a file containing multiple classes, the file
can be read into an Emacs buffer, the buffer narrowed to the desired
class and then the add command executed.  @xref{Narrowing, , Narrowing,
emacs, The Gnu Emacs Manual}.@refill

This command may also be used outside of the browser user interface when
one is editing a file in Emacs, so that there is no need to jump in and
out of the browser.

@kindex C-c C-d
@findex br-delete
@cindex class, deleting from Environment
@cindex Environment, deleting classes
A class is deleted from the Environment, by pointing to its name in a
class listing buffer and then executing the delete class command.
The class matching command may be used to locate it.  The browser
confirms the deletion by removing the class name from the listing
buffer.


@node Further Work, Conclusion, Design Specifics, Top
@chapter Suggestions of Further Work

@section Expand Query Types

The browser really only works with inheritance and method relations
right now.  There is an undeniable need for the addition of supplier,
client, and category-based browsing.

Suppliers are classes which contain methods invoked by other classes,
the clients.  Computation of these recursive relations is expensive.  A
technique must be developed which preserves the quickness of Environment
construction and supports queries using these relations.

Method breakdowns by visibility (public, private, protected) would also
be useful to add.  This should not require too much work.

Category-based browsing should be the next major addition.  Some other
people have already done work on adding facet-based categories to the
browser.  Facets are traits that classes have.  Classes sharing facets
are grouped into a facet category.  Facet examples might be: fixed sized
container classes, domain-specific classes, or classes that contain a
name field.

@menu
* Dynamic Object Browsing::     
* Tool Integration::            
* Graphical Interface::         
* Version Control::             
@end menu

@node Dynamic Object Browsing, Tool Integration, Further Work, Further Work
@section Support Dynamic Object Browsing

The OO-Browser works with static structures.  It therefore utilizes
class groupings but has no concept of run-time objects.  The techniques
and query relations desired in an object browser are very different from
that of a class browser.  Therefore, a separate tool should be built.
It could, however, utilize the OO-Browser user interfaces.  It would
then act as a back-end engine communicating with the class browser
interface.  This raises the inter-application communication issue of the
next section.


@node Tool Integration, Graphical Interface, Dynamic Object Browsing, Further Work
@section  Provide Mechanism for Integration with Other Tools

Emacs supports subprocess control.  This is how the textual interface
communicates with the graphical interface.  They use a simple
redirection of standard input and standard output.

A much more desirable and flexible strategy is to use a communications
medium like sockets to allow peer-to-peer communication.  On top of this
low-level mechanism, a method like Field's Selective Broadcasting
[@cite{Reiss 88}] or ET++'s Multiple Views [@cite{Weinand 89}] might be used.

@node Graphical Interface, Version Control, Tool Integration, Further Work
@section Extend Graphical Interface

A lot could be done here, none of it particularly difficult.  As
mentioned before, a full suite of browser commands should be added.
A technique that allows dynamic menu entry additions would provide the
requisite flexibility.  This could probably be achieved with a basic
resource file format and a small amount of application code to cache the
entries.

@node Version Control,  , Graphical Interface, Further Work
@section Support Version Control Systems

RCS is the likely candidate system.  One would want to be able to
browse particular releases and to avoid mixing code from one release
with that of another when building Environments.



@node Conclusion,  , Further Work, Top
@unnumbered Conclusion

The OO-Browser is a robust tool for class or generalized hierarchy
browsing.  New subsystems are easy to integrate, so we expect the
available types of queries and means of user interaction to continue
to expand.

The browser demonstrates useful user interface techniques.  It supports
multiple interaction modalities:  keyboard and mouse inputs, graphical
and textual views, menu and direct selection techniques.  This allows
the user to choose a style with which he is comfortable.  The ease of
entry and exit from the browser coupled with its access speed,
encourages a developer to use it often.  It integrates well with the
incremental development cycles often found in object-oriented projects.
It further supports the developer with external interfaces for compiler
error parsing and type name completion.

The browser implementation vividly illustrates that a single, portable
tool and interface can be used for a variety of languages.  Departmental
language needs often change.  So the ability to continue to use the same
tool with a different language lessens developer slow down and actually
provides an immediate comfort zone, so that the change need not be
overwhelming.  Another good example of interface reuse is the ET++
application development framework [@cite{Weinand 89}].  It provides a
means of building highly interactive, window system independent
applications that all share common interface constructs. One would hope
that more developers of programmer support tools will start taking an
approach of this kind.

@sp 2
[@cite{Goldberg 83}]  Goldberg, Adele and David Robson.
@emph{Smalltalk-80:  The Language and its Implementation}.
Addison-Wesley, 1983.


[@cite{Reiss 88}]  Reiss, Steven P.  "Integration Mechanisms in the FIELD
Environment," Brown University Technical Report CS-88-18, October 1988.


[@cite{Stallman 87}]  Stallman, Richard.  @emph{GNU Emacs Manual}.  Free
Software Foundation, Cambridge: MA, March 1987.


[@cite{Weinand 89}] Weinand, Andre, Erich Gamma, and Rudolf Marty.
Design and Implementation of ET++, a Seamless Object-Oriented
Application Framework, @i{Structured Programming}, Springer-Verlag: NY,
NY, Vol. 10, No. 2, 1989.


@contents
@bye
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.