|
Programming styles can be controversial, no doubt about it.
And so...
"Once more unto the breach, dear friends, once more...." - Shakespeare; Henry V, Act III
Styles
- Namespace references
-
All features of Toe, and all Toe-recognized objects, are supported in or under the root namespace of ::toe.
However, Toe was designed such that almost no explicit reference to a particular namespace, other than ::toe,
is needed in application source code.
Object command names are formed with a leading "::" but may or may not identify a namespace
other than the global namespace. The association of namespaces with commands is managed internally.
All commands that are supported by Toe may be expressed with a notation of
"toe subcommand ...," or, for object commands stored in a variable, say, obj, a notation of
"$obj method-name ...."
In order to work constructively within an object-oriented paradigm,
users should avoid unsupported references to a child namespace of ::toe.
- Capitalization
-
Tcl-style capitalization encourages using a lower-case letter to start the name of a command or proc
that is exported or intended for external use.
Mixed case within the name is encouraged where run-on words might be hard to distinguish otherwise.
A leading upper-case letter should be used for internal procs that are not meant for external use.
Java-style capitalization encourages class names
to start with an upper-case letter,
and method names to start with a lower-case letter.
[1]
As with Tcl, internal names should start with an upper-case letter.
Class names in Toe should start with a capital letter, for three reasons:
- Disambiguation with Tcl commands, especially in a milieu of many classes.
- Avoiding name conflicts between Tcl commands and common object command names for Toe common objects.
- Consistency with Java.
For parity, the names of interfaces and mixins should also start with an upper-case letter.
Method names in Toe should follow the Tcl style, which is consistent with Java-style method naming.
In brief, names should start with a lower-case letter, except for the names of
classes, interfaces, mixins, and internal words.
Mixed case should be used as needed,
especially to avoid the use of an underscore (_), or other separating punctuation.
For many development projects, it is customary to preface the class names
with one or a few upper-case letters, in order to distinguish the project or the (enterprise) owner of
the class.
For example, a class simply named "Foo" that was developed at the XYZ Widget Factory
might be coded as "XYZFoo." Toe is agnostic about capitalization, but adopts
a naming convention for itself where generic class names start with "T" (for "Tcl"),
interface names start with "I," and mixin names start with "M."
- Global scope
-
Tcl style encourages that "a package should not contain any global variables or global procedures."
[2] In support of this style, Toe ships with the single command
"toe" in the global namespace, and creates objects and object commands such that no new names are
created in the global namespace. To illustrate how this works, one creates a null class, C,
by entering either "toe::class C {}" or "toe class C {}."
The corresponding common object command is "::toe::C."
To create the first instance of the null class, one enters either "toe::new C" or "toe new C."
The corresponding instance command is"::toe::C#1."
However, programming in Java and C++ relies heavily on "class" and "new" as keywords in the global namespace.
Emulating these and other keywords, such as "delete" and "interface," in Tcl
would add not only several new commands in the global namespace,
but also particular command names that might be desired or claimed in other OO systems.
Nevertheless, some users may want to program in Tcl with a syntax and usage that bears a strong
resemblance to to Java or C++.
To do so, such users may wish to employ the Tcl feature,
interp alias {} srcCmd {} targetCmd ?args ...?, with the full understanding
that by doing so they may be sacrificing compatibility with other OO systems that are supported by Tcl.
- Punctuation
-
Toe uses no special punctuation, other than "#" as part of command names for dynamic commands.
In keeping with Tcl's limited use of punctuation as operators,
Toe provides literate subcommands for similar functionality.
In particular, Toe uses the literate operator/subcommand "variable" rather than
the "." structure member operator in Java and C/C++ in order to get or set
the value of an object's public variable.
- Command naming
-
Object commands in Toe are assigned internally.
Common object names are the same as class names, possibly prefixed with "::toe."
Dynamic object names are the same as common object names, with a "#" and a counting number appended.
Command names are formed following the model of tokens created by Tcl's "after" command.
The object command names are assigned internally, and cannot be prescribed by the user.
Command names are managed separately from Tcl namespace names; any association between
the two is an artifact of implementation.
Users who parse Toe command names for an algorithmic purpose do so at some risk.
Policies
The Toe package provides a set of policies with default values as follows:
% array set policy [toe policy]; parray policy
policy(debug) = 0
policy(novars) = 0
policy(preventGarbage) = 1
policy(replaceClass) = 1
policy(replaceInterface) = 1
policy(replaceMixin) = 1
policy(revise) = 1
policy(scoped) = 1
policy(seize) = 0
policy(strict) = 0
- debug
-
debug enabled yields more information in the ::errorInfo variable when an error occurs.
Normally disabled.
- novars
-
novars enabled prevents class variables from being included by default
within the scope of methods, as if the "-novars" option were always provided.
This is applied when a class is defined, not when an object is instantiated.
Normally disabled.
- preventGarbage
-
preventGarbage enabled causes the Toe runtime to delete an owned object when
its owner is deleted. This may be disabled for more manual control over object lifetime.
Normally enabled.
- replaceClass
-
replaceClass enabled allows a class to be redefined. For a more rigid environment,
in which a class can only be defined once, this policy may be disabled. Normally enabled.
- replaceInterface
-
replaceInterface enabled allows an interface to be redefined. For a more rigid environment,
in which an interface can only be defined once, this policy may be disabled. Normally enabled.
- replaceMixin
-
replaceMixin enabled allows a mixin to be redefined. For a more rigid environment,
in which a mixin can only be defined once, this policy may be disabled. Normally enabled.
- revise
-
revise enabled allows fine-grained changes to methods, filters, and class relationships after
they have already been defined. It also allows the contents of methods in existing objects
to be revised. For a more stable environment while the code is running, this policy may
be disabled. Normally enabled.
- scoped
-
scoped enabled causes object command names to be defined under the ::toe namespace,
consistent with Tcl-style naming.
scoped disabled causes object command names for unnested classes to be defined
in the global namespace; especially without the leading namespace delimiter, unscoped naming
resembles Java- or C++-style code.
In particular, for an unnested class, the class name itself becomes the command name
for the class' common object.
For an example of the effect on object command names, refer to the tables below.
Normally enabled.
toe class A {
toe class B {
toe class C {
}
}
} |
| toe policy scoped 1 (enabled) |
|---|
| Object | Nested level |
|---|
| |
(outer) |
nested |
doubly nested |
| common |
::toe::A |
::toe::A::B |
::toe::A::B::C |
| dynamic |
::toe::A#1 |
::toe::A::B#1 |
::toe::A::B::C#1 |
|
| toe policy scoped 0 (disabled) |
|---|
| Object | Nested level |
|---|
| |
(outer) |
nested |
doubly nested |
| common |
::A |
::A::B |
::A::B::C |
| dynamic |
::A#1 |
::A::B#1 |
::A::B::C#1 |
|
| |
- seize
-
seize enabled allows an object to take ownership of another object, regardless of the
ownership status of the object being seized. Normally disabled.
- strict
-
strict enabled invokes more rigorous validation, particularly as a class is being defined.
It exists to provide a trade-off between rigor and performance, particularly during development.
Normally disabled.
|
