This page will walk you through the set of features supported by Quarrel and the syntax used for each. It is intended to have more depth than the examples, but the models sketched will only be complicated enough to demonstrate each feature independently.
When using Quarrel, a UML diagram is generated from a block of specially formatted text using a specific vocabulary. This is similar to the idea behind the Almost Plain Text notation used by Maven 2 and other tools. The vocabulary is based on the UML spec, but uses less formal terminology. For example, "extends" is used in place of "specializes", "implements" instead of "realizes". This is done for the sake of terseness and the informal nature of the UML as Sketch practice.
Elements, such as interfaces, classes or use cases, are represented by adjacent lines of text. A blank line indicates the beginning of a new element. Elements declarations will always begin in the first column of the line and include a literal identifying the type of the element (interface, class, etc)
An element is broken down into sections which identify the different features for that element, such as operations, attributes or relationships. The start of a section will be indented at least one space. The text of a start section line must be one of the supported feature types (operations, attributes, etc).
The contents of a feature will be indented at least one character from the start section line. Each indented line inside the feature section will be handled as an instance of that feature type.
A section will end when the indent decreases or a blank line is encountered.
A generic example of how the structure works:
[element type] one
[feature type]
blah blah blah
yada yada yada
[feature type]
yeah yeah yeah
[element type] two
[feature type]
etc etc etc
where the text in [brackets] are place holders for supported literals in the vocabulary.
A more concrete example:
interface Serializable
class Throwable
implements
Serializable
attributes
-detailedMessage : String
-cause : Throwable
operations
+getMessage() : String
+getCause() : Throwable
+printStackTrace()
class Error
extends Throwable
class Exception
extends Throwable
produces
The depth of the indent is not important. The only real rule is that indents must be consistent with a section. For example, all methods defined in an operations section must have the same indent. If not, the parser routine would try to interpret the line with a different indent as a new section.
The contents of the individual lines inside a section are not considered by the parser; they are treated as generic data. This allows the user the ability specify any depth of information. For example, if you want to just specify the name of a method or attribute, that is fine. If you want to specify the visibility (public, private, etc), you may. Literally, anything goes.
Quarrel is independent of the target implementation language, just as UML is. Most of the examples will use the context of Java, but that is only because that's the langauge the tool is implemented it. There is no reason that Quarrel can't be used to produce models that will be implemented in other languages.
At some point it may be desirable to add rules based on the target language for implementation. For example, UML supports notation for multiple inheiritance. But the Java language specification does not. It might be nice to have Quarrel check for this condition and warn the user. This is not a feature that would be developed any time soon unless users requested it.
The following elements types will be supported in the 1.0 release.
Others will follow.
These are all the feature types, but they may not be supported by all element types.
Interfaces may use the generalization (extends), operations, and attributes sections.
The following UAS text would create a diagram for the java.lang.Runnable interface.
interface Runnable
operations
+run()
One interface may extend another. For example, the following text
interface List
extends
Collection
operations
+boolean add(Object o)
+void clear()
+Object get(int index)
+boolean isEmpty()
produces a diagram which demonstrates inheritance between interfaces.
Notice that the Collections interface is represented in the diagram even though it was never formally defined in the document.
Classes may use the operations, attributes, extends and implements sections.
The java.lang.Throwable class in Quarrel UAS notation:
class Throwable
attributes
-detailedMessage : String
-cause : Throwable
operations
+getMessage() : String
+getCause() : Throwable
+printStackTrace()
would yield the following diagram:
The set of supported relationships types includes the "realizes" (implements) and "specializes" (extends), as described above. Quarrel will also add support for the dependency and association relationships, but these still need to be implemented.