=-- This distribution rendered properly... -=
=---- http://www.prairienet.org/~yamada ----=
=---- mailto:yamada@acm.org (haiku) --------=
=-- when these lines have equal length. ----=
-----StartFileNoSpaceBelow
Subject: SourceVision 0.3.1
Purpose: Describe a software development environment API.
Status: Draft.
Delta: CodePalette 0.1 September 11-14, 1997
SourceVision 0.2 September 18, 1997
SourceVision 0.3 September 23, 1997
SourceVision 0.3.1 December 24, 1999
Dimensions: 912 lines, 34,699 bytes
Style: 7-bit ASCII (fixed pitch)
Soft tabs at 4 characters
Line width 68 characters
Maintain with included makefile
To do: Concurrency
Versioning
Test/production domain support
Amendments: yamada@acm.org
Legalese: _***_ Copyright 1997 by William Paul Fiefer. All
rights reserved. SourceVision, SourceVision
Corporation, "Custom APIs," "Platform-neutral
systems development," and "CodePalette" are trademarks by first use
of William Paul Fiefer belonging to William Paul Fiefer. _***_
SourceVision is a product and an activity. Use of this product is
restricted to educational purposes. Commercial or military use of
this product is prohibited. _***_ Use of this product as a component
of, or in the production of, a physical or electronic document,
product, or artifact obligates the user to make the resulting
derived document, product or artifact available to anyone on request
at no cost for purposes identical to those described here. Users can
charge for their product; no one is obligated to pay to receive or
possess that product; possessors of the user's product may
distribute it subject to the restrictions described here. Derivative
work produced from this product or from work derived from this
product is subject to terms identical to those applying to the
direct use of this product. _***_ You are free to distribute this
material in electronic format provided that the file remains
unmodified and this copyright notice remains attached. This
copyright prohibits HTMLizing this file. If you wish to publish
abstracts or portions of this file, contact William Paul Fiefer
for permission.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
S o u r c e V i s i o n 0. 3. 1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=[1.0]=> Contents.
==================
=[1.0]=> Contents.
=[2.0]=> SourceVision.
=[0.0]=> SourceVision components.
_(1.0)_ Mini-editors.
_(2.0)_ Splines.
_(3.0)_ Browsers.
_(4.0)_ Controls.
=[0.0]=> SourceVision software architecture.
_(1.0)_ SourceVision software layers.
_(0.0)_ Host platform interface.
_(0.0)_ System modes.
_(0.0)_ Development modes.
_(0.0)_ Display modes.
=[0.0]=> SourceVision software API.
_(1.0)_ API syntax.
_(2.0)_ Virtual Machine.
_(3.0)_ Browser.
_(0.0)_ Tools.
=[0.0]=> Appendices.
_(1.0)_ Suggested development technique.
_(0.0)_ Notes.
(i.m.e) Inheritance mechanism.
(n.c.o) Naming conventions.
(o.b.j) Objects.
_(0.0)_ Makefile.
======================
=[2.0]=> SourceVision.
======================
SourceVision is a software development environment that provides the
programmer with depictions of two-dimensional and three-dimensional
workspaces. This is a dramatic enhancement to the linear development
spaces depicted by traditional text editor-based development tools.
SourceVision is, conceptually, a dynamically configurable software
block schematic with an attached incremental compiler. Programmers
construct code by distributing and connecting code fragments
(primarily data structures and module implementations) within this
workspace. The units in which code elements are moved over the
working surface are called `mini-editors'. The working surface is
called the `browser'.
Related elements of code and data can be connected by `splines',
which are lines indicating the attributes of the relationship among
the connected mini-editors. Splines remain attached to
programmer-designated editors when they are moved over the browser.
Graph relationships of the spline-connected design remain stable
until explicitly changed.
The evolving, interlocking design first depicts, then functions as,
the software system under development. Analysis, design, and
programming interleave smoothly under SourceVision.
Programmers can also physically disassemble and reverse engineer
existing code within the workspace, distributing and connecting code
elements in a manner best representing the system under analysis.
=================================
=[0.0]=> SourceVision components.
=================================
_(1)_ Mini-editors.
-------------------
SourceVision permits the use of many simple text editors,
called `mini-editors,' each consisting of an editing screen
within a border (to save space and simplify the interface).
Each mini-editor has a copy/paste feature for transferring
text inline and to other mini-editors on screen.
Mini-editors can contain:
(1) Data structures
(2) Logic
(3) Data structures and related logic
(4) Program function call outline
Highlighting text within an editing screen and dragging
the text to the browser generates a new mini-editor
containing the extracted, highlighted text. Dragging a
mini-editor to the upper or lower border of another
mini-editor merges the mini-editors into one and
concatenates their text. These actions are valid on
operations and data structures.
A group of mini-editors or the icons representing them may be
selected by dragging the pointer over them or clicking the
pointer directly on them. The group is called a `cluster
group.'
A group of mini-editors and their related data, or the icons
representing them, may be selected by dragging the pointer over
them or clicking the pointer directly on them. The group is
called an `object cluster group.' The objects selected for
iconization may, at the programmer's determination, be
syntax-checked for their validity as an object.
Iconizing a mini-editor reduces it to an icon depicting the
mini-editor contents.
(1) Data structures
===
A <== data structure symbol
===
(2) Logic
-
{ 1 } <== function symbol
-
(3) Data structures and related logic
<== object symbol
(4) Program function call outline
<== call outline symbol
Iconizing a cluster group reduces it to an icon depicting the
cluster group contents.
(1) Cluster group
<== module hierarchy symbol
(2) Object cluster group
<== object symbol
The mini-editors can configured with detailed menus and
toolbars for display and use. The mini-editors access an
incremental compiler able to compile and syntax check their
contents individually. Syntax editing text within a
mini-editor determines whether data referenced by any source
instruction in the mini-editor is also present in the
mini-editor. If not, the mini-editor flags the code as
representing an incomplete object.
Each mini-editor contains one or more data structures, one
or more module implementations, a unit of scope or namespace,
or other, programmer-determined contents.
----------------
_(2.0)_ Splines.
----------------
The splines store the attributes of the connections between
data structures and functions.
-----------------
_(3.0)_ Browsers.
-----------------
The mini-editors rest on a browser consisting of and
extending beyond the entire screen surface. Browser space is
blank except for the positions occupied by the mini-editors
and the splines connecting them. Cursor-key or pointer
motion pulls offscreen portions of the browser into the
display.
Properties of the browser surface area are programmer
determined. The entire browser surface may exhibit a single
property or be divided into territories, each exhibiting a
separate property. Two properties predominate: `design,' the
phase where system elements are connected by splines and
displayed in multiple mini-editors; and `build,' the phase
where the contents of mini-editors are concatenated into
executable code. The build space is also known as the
`construction bay.' A third phase, `port,' is used to
generate source code for a target platform.
The properties of mini-editors, primarily the ability to
concatenate them, change depending on whether they rest on
design or build space.
Browsers are swappable into memory and a programmer may have
several browsers active at a given time. Swappable browsers
are stored and recovered in two, non-exclusive methods.
First, browsers may be stacked in the manner of windows, and
rotated under programmer control to the forefront; second,
browsers may be recovered using icons represent each of
them.
A programmer may designate separate territories of a single
browser for design and build, or a programmer may elect to
designate one swapped-out browser as a design space, and
another as the build space.
The browser supports the dynamic graphics that allow the
programmer to connect the mini-editors with splines to build
a data-flow-type diagram or structure chart. The browser can
be configured with mouse- and keyboard-responsive menus and
toolbars.
-----------------
_(4.0)_ Controls.
-----------------
============================================
=[0.0]=> SourceVision software architecture.
============================================
_(1.0)_ SourceVision software layers.
-------------------------------------
SourceVision is constructed from three layers of code draped over
the operating system. These layers are:
(1) The SourceVision virtual machine (VM).
The SourceVision VM runs directly on top of the host
operating system. The API boundary attaching the host
operating system and the VM software layer is called the
`host platform interface.'
(2) The browser.
The browser runs in the SourceVision VM. The API boundary
attaching the SourceVision VM and any enhancement, including
the browser, is called the `VM interface.'
(3) The tools.
The API boundary attaching the browser and any enhancement,
including the tools, is called the `browser interface.'
Further, the API boundary attaching the tools and any tool
enhancement is called the `tools interface.')
(A) VM controls
(a) Mode controls
(b) Property controls
(B) Browser controls
(a) Mode control
(b) Display controls
(c) Development controls
(i) Object mode controls
(ii) Procedural mode controls
(d) Property controls
(C) Mini-editors
Mini-editors run using services provided by browser.
(D) Splines
Splines run using services provided by the browser.
=------------------------------------------------------------------=
- - - - - - - - - - - <== Tools interface \
| Tools | |
- - - - - - - - - - - <== Browser interface |
| Browser | |
- - - - - - - - - - - <== VM interface | < SourceVision
| SourceVision | |
| Virtual Machine | |
- - - - - - - - - - - <== Host platform /
Host operating system interface
---------------------
Section 0.0, figure one: SourceVision software layers.
=------------------------------------------------------------------=
--------------------------------
_(0.0)_ Host platform interface.
--------------------------------
The SourceVision VM runs in two modes:
(1) Host suppression mode.
hostSuppress()
The VM is a full operating environment, effectively
serving both as host to the SourceVision application
and as the operating system.
hostActivate()
The host operating system runs the SourceVision
application and acts without restriction as the
operating system.
(2) VM mode.
vmActivate()
SourceVision runs as an application within its own
window, under full control of the SourceVision VM,
requesting operating system services from the VM.
vmSuppress()
SourceVision runs as an application within its own
window, under full control of the host operating system.
---------------------
_(0.0)_ System modes.
---------------------
(1) modeSingleUser()
(2) modeMultiUser()
--------------------------
_(0.0)_ Development modes.
--------------------------
(1) Design mode.
modeDesign()
checkDesignSyntaxOn()
checkDesignSyntaxOff()
(2) Build mode.
modeBuild()
checkCodeSyntaxOn()
checkCodeSyntaxOff()
(3) Port mode.
modePort()
instructionSet390()
instructionSetX86()
instructionSetSparc()
----------------------
_(0.0)_ Display modes.
----------------------
(1) Screen lock.
screenLock()
The SourceVision browser workspace is restricted to the
display dimensions of the monitor.
(2) Screen scroll.
screenScroll()
The SourceVision browser workspace extends in all
directions beyond the display dimensions of the monitor.
The programmer can switch between screen scroll and screen lock by
altering a system control setting. No data is lost in the switch.
=======================================
=[0.0]=> The SourceVision software API.
=======================================
Placeholders, not a real API...
-------------------
_(1.0)_ API syntax.
-------------------
The code fragments in this document are represented as follows:
(1) Object name alone.
Example 1, simple
-----------------
FooA{} <== capitalized name; braces (`{}')
FooB{}
--------------------
Example 2, intricate
--------------------
FooC:FooB{} <== FooC inherits from FooB;
one `:' indicates object from
an object
(2) Object data or function component name alone.
Example 1, simple
-----------------
char a <== character data component
bar1() <== function component name;
parentheses (`()')
--------------------
Example 2, intricate
--------------------
FooA::a; <== character data component a is
inherited from object FooA;
two `::'s indicate component
from an object
FooA::bar1(); <== function component bar1() is
inherited from object FooA;
two `::'s indicate component
from an object
(3) Object function component signature.
Example 1, simple
-----------------
int bar2(float*) <== function component name,
argument type, and return type
--------------------
Example 2, intricate
--------------------
void FooA::bar1(int); <== function component returning
void bar2 is inherited from
object FooA; two `::'s indicate
component from an object
(4) Object interface (the object and its components).
Example 1, simple
-----------------
FooA
{ char a; <== data components
int x; <==
void bar1(int); <== function components
int bar2(float*); <==
return();
}
--------------------
Example 2, intricate
--------------------
FooC:FooB <== FooC inherits from FooB
{ char b;
int y;
bar3(float) <== nested function component
{ bar4()
};
void FooA::bar1(int); <== bar1 is inherited from FooA
return();
}
------------------------
_(2.0)_ Virtual Machine.
------------------------
VMController
{ platformModeController()
{ platformSuppress()
platformActivate()
}
}
----------------
_(3.0)_ Browser.
----------------
BrowserController
{ browserConstructor()
{ newBrowser()
copyBrowser()
}
browserDisplayControl()
{ refreshBrowser()
refreshAllBrowsers()
shuffleBrowsers()
}
browserRuntimeGovernor()
{ startBrowser()
stopBrowser()
}
browserCodeParser()
{ checkCodeSyntaxOn()
checkCodeSyntaxOff()
}
browserDesignParser()
{ checkDesignSyntaxOn()
checkDesignSyntaxOff()
}
browserDestructor()
{ archiveDeleteBrowser()
noArchiveDeleteBrowser()
}
}
--------------
_(0.0)_ Tools.
--------------
Mini-editors
Splines
Controls
VirtualMachineControls
BrowserControls
Mini-editorControls
SplineControls
Cluster group
====================
=[0.0]=> Appendices.
====================
_(1.0)_ Suggested development technique.
--------------------------------------
The environment promotes a specific technique characterized by two
features: (1) Development moves from dataflow diagram to code
without passing through a structure chart phase; (2) Development
organizes code into a collection of objects that can be used in
procedural or object-oriented code.
The technique is characterized by the following steps:
USE, DON'T OVERUSE, INHERITANCE
(0) Inheritance is currently system-specific and in draft
format. The details are in note (i.m.e) and they are not
required to understand the remainder of this section.
DEVELOP THE DATA STRUCTURES
(See note (n.c.o) for naming conventions)
(1) Specify the data structures in the system. Represent
each implemented data structure using two parallel lines as
in a Yourdon-DeMarco dataflow diagram. Assign each set of
lines a descriptive name. Distribute the data structures
over the surface of a work area to reflect their
relationships and ease the task of working with them.
=------------------------------------------------------------------=
===
A
===
===
B
===
===
C
=== ===
D
===
===
E
===
Section 0.0, figure one: Arrange the data structures.
=------------------------------------------------------------------=
(2) Notate the relationships among the data structures using
lines as in a dataflow or entity-relationship (ER) diagram.
Assign each line a descriptive name. For simplicity, skip
the one-many notation.
=------------------------------------------------------------------=
===
A
/===\
/ `````````\
/ ===
/ B
/ /`===
=== /
C /
===````````===/
D
===
/
/
===/
E
===
Section 0.0, figure two: Spline the data structures.
=------------------------------------------------------------------=
ENCAPSULATE BY MERGING DATA STRUCTURES WITH FUNCTIONS
(3) Specify the lowest-level functions acting on these data
structures or using the data structures as switches, flags,
and counters. Represent these functions as individually
numbered bubbles and place these bubbles near the data
structures they use. Assign each bubble a descriptive name.
Rearrange the data structures to make the layout and
function-data structure relationships clear. Connect the
bubbles to the data structures with arrows as in a dataflow.
=------------------------------------------------------------------=
- ===
{ 1 } A
- /===\
/ \-------\
/ ===
/ B
/ /`===
=== /
C /
===--------===/
D
- === -
{ 2 } / { 3 }
- / -
===/
E
===
Section 0.0, figure three: Arrange the functions.
=------------------------------------------------------------------=
- ===
{ 1 }<--> A
- /===\
^ / \-------\
| / ===
| / B
v / /`===
=== / ^
C / |
===--------===/ |
/-----> D |
v----/ === v
- / -
{ 2 } / { 3 }
- ===/ ^ -
E |
=== <---------/
Section 0.0, figure four: Spline the functions.
=------------------------------------------------------------------=
BUILD OBJECTS -- STEP 1, IDENTIFY
(See note (o.b.j) on objects)
(4) Divide this work area into territories, enclosing functions
(bubbles) and related data (parallel lines) that together
constitute conceptually linked entities that may or may not
share scope or namespace. Assign each entity a descriptive
name.
=------------------------------------------------------------------=
Items Components Names
----- ---------- -----
object1 = 1AC = buildFoo
object2 = 2D = testFoo
object3 = 3BE = archiveFoo
Section 0.0, figure five: Build and name objects.
=------------------------------------------------------------------=
USE, DON'T OVERUSE, POLYMORPHISM
(5) If many similar functions act against the same data, group
them within a single territory and restrict access to each
member of this demarcated function set through a test
specified in a CASE (COBOL EVALUATE) statement. When calling
functions that share names but reside in separate
containers, prefix the name of the function with its
container name. Using this protocol, identical function
names residing within separate function groups will not
clash.
BUILD OBJECTS -- STEP 2, TEST
(6) Review the boundaries over this work area, making sure they
enclose bubbles and related data that together constitute
autonomous entities.
(7) Specify higher-level functions that use these low-level
functions as constituents (in the manner of constructing
modules using these low-level elements as callable
functions).
(8) Create the inline code from this plan.
=------------------------------------------------------------------=
Sample function:
----------------
doFoo()
{
dataStructureA;
dataStructureC;
buildFoo();
testFoo();
archiveFoo();
return();
}
Section 0.0, figure six: Build code using the objects.
=------------------------------------------------------------------=
--------------
_(0.0)_ Notes.
--------------
(i.m.e) Inheritance mechanism.
..............................
Inheritance as implemented is system-specific and in draft
form. As you review this note, bear in mind that during
compilation the named functions insert code that controls
subsequent execution.
First, as background, all SourceVision objects are
implemented by the compiler as individually named
executables that take their internal functions as arguments
(an example is coming up).
These objects contain executable instructions and data
structures in an internal directory structure. These objects
may also contain PATH statements that point to executables
and data in the system external to the object. In essence,
an object is a compiled, searchable directory structure
containing files.
The following command-line arguments might reinforce this
idea:
==> objA add
and
==> objB add
Objects A and B implement `add' differently, one
perhaps adding decimal and the other octal. Each is
invoked with one of its functions supplied as an
argument.
Second, and last, as background, the `parent' is the object
containing code we want to inherit. The `child' is the
object requesting code for inheritance. The terms are
relative. A parent can be the child of a parent higher in a
hierarchy of inheritance. When we speak of data and
functions within a particular object, we refer to it as
`self'. Under conditions of multiple inheritance, self can
have more than one parent or children.
We are ready to move on. SourceVision inheritance is
implemented through six functions, all of which use services
specific to the pertinent operating system:
setParent(location1, location2, ...)
Points to the system locations housing parent
objects containing desired functions.
excludeParent(location1, location2, ...)
Points to the system locations housing parent
objects containing functions that must not be used.
setSelf(functionName1, functionName2, ...)
Specifies that the named functions in the current
object must be used in preference to identically
named functions in objects elsewhere in the system.
excludeSelf(functionName1, functionName2, ...)
Specifies that the named functions in the current
object must not be used.
setChild(object1 [global], object2 [global], ...)
Specifies that the named objects must use the named
functions of the current object. A GLOBAL argument
makes the named functions available system-wide.
excludeChild(object1 [all], object2 [all], ...)
Specifies that the named objects must not use the
named functions of the current object. An ALL
argument makes all functions of the current object
unavailable system-wide.
At this point we do not have truth tables delineating the
conditional relationships between these functions.
The rules governing this inheritance model are:
(1) If the function requested from the parent and the
function contained in the self are identical,
nothing changes.
(2) If the function requested from the parent is not
present in the self, it is implemented unchanged in
the self.
(3) If the function requested from the parent differs
from an identically named function in the self,
three things happen: (1) new, novel parent code is
added to existing self code; (2) new parent code
that upgrades code already in the self overrides
self code; and (3) self code not matched in the
parent is retained. (The parsing routine for this
_will _be _hairy.)
(4) If a pointed-to parent object points to yet another
object, the search for code and data ascends the
inheritance tree until an executable function label
with the requested name is located. Self inherits
that code.
(5) If a pointed-to parent is a directory, the search
scans the directory for the function named in the
search. Directories may contain pointers to other
directories or objects.
Rules (4) and (5) govern polymorphic action, which allows
the programmer to tailor a named function's behavior
specifically for the objects containing that function.
...........................
(n.c.o) Naming conventions.
...........................
Design an API, then build your application as a layer of
code over it.
Assign descriptives names using the vocabulary of the
problem (application) domain. For example, a function pair
adding and removing customers to and from a ticket-sales
line is better named AddTicketCustomer() and
RemoveTicketCustomer() rather than PushTickCustStack() and
PopTickCustStack(). The actions of each function pair are
identical. But as you incorporate lower-level modules into
higher-level routines, you will abstract, analyze, and
design using the vocabulary of the problem domain, not the
computer system domain.
................
(o.b.j) Objects.
................
Objects are clusters of data and the functions manipulating
that data. The criteria you use to select which functions to
pack into an object depend on the problem you are solving,
and your particular style of development.
When you build code from objects, you make global changes in
your code by modifying data structures or functions at a
single point -- the object. The change then propagates
through your code along the inheritance paths you construct.
-----------------
_(0.0)_ Makefile.
-----------------
#***begin_makefile**************************************************
# SourceVision makefile.
# Input, ALL optional segments, and de-slacked output files.
MAINDOC = vision3.txt
ALL = zero.txt five.txt ten.txt
SEDOUT = vision3x.txt
# If MAINDOC is segmented, these are the working files.
SEC-00 = section1.txt
SEC-05 = section2.txt
SEC-10 = section3.txt
# Zip and backed-z1p files.
# ZIPMAKE1 and ZIPMAKE2 are not currently used.
ZIPMAIN1 = vis3b-tx.zip
ZIPMAIN2 = vis3b-tx.z1p
ZIPMAKE1 = vis3b-mk.zip
ZIPMAKE2 = vis3b-mk.z1p
# Recipes.
# Main course.
# PICK ONE.
#-------
# make-1
#-------
# Segmented MAINDOC? Build a zip set, call make again.
#$(ZIPMAKE1):
# zip -k9 $(ZIPMAKE1) *.*
# make $(MAINDOC)
#-------
# make-2
#-------
# MAINDOC is working doc?
# COMMENT OUT `clean-1' below and use `clean-2'.
# De-slack, build twin zips for auto-archiving.
zip:
sed 's/ *$$//' $(MAINDOC) > $(SEDOUT)
rm $(MAINDOC)
mv $(SEDOUT) $(MAINDOC)
zip -k9 $(ZIPMAIN1) $(MAINDOC)
cp $(ZIPMAIN1) $(ZIPMAIN2)
# Called from make-1.
# De-slack and build a primary file, zip two copies.
$(MAINDOC): $(ALL)
cat $(ALL) > $(MAINDOC)
sed 's/ *$$//' $(MAINDOC) > $(SEDOUT)
rm $(MAINDOC)
mv $(SEDOUT) $(MAINDOC)
zip -k9 $(ZIPMAIN1) $(MAINDOC)
# Define the intermediate files.
zero.txt: $(SEC-00)
cat $(SEC-00) > zero.txt
five.txt: $(SEC-05)
cat $(SEC-05) > five.txt
ten.txt: $(SEC-10)
cat $(SEC-10) > ten.txt
# Ala carte.
# Delete primary, intermediate, and zip files.
# PICK ONE.
#--------
# clean-1
#--------
# Dangerous. Use ONLY if MAINDOC is segmented.
#clean:
# rm $(ALL) $(MAINDOC) $(ZIPMAIN1) $(ZIPMAKE1)
#--------
# clean-2
#--------
# Use ONLY if MAINDOC is working doc.
clean:
rm $(ZIPMAIN1) $(ZIPMAIN2)
# Utility
#---------------------
# Display longest line
#---------------------
# Build `ll' or use K&R C2 for source.
ll:
ll < $(MAINDOC)
#***end_makefile****************************************************
-----EndFileOneSpaceAbove
=----endDocument
|
