Update:

MOtivation:

def logHello(a, b, c):
    a.open(b.getName(c.getPath())).log("hello world!")

The single line of code in this method involves four messsages, However, only the first – a.open() – may be expressed in Skilltree as proper Need at present. The other messages hide inside, silently supplying the arguments and disposing of the result.

Problem:

In an ideal world (or in Assembly Language or COBOL), each Skilltree Need would map to a single line of code, and each line of  proceduralcode would map to a single Skilltree Need. In reality, however, the lack of support for composite Need compromises the mapping of a Skilltree specification to useful code.

• An issue with automatic reverse-engineering (a feature under construction): Reversing a single-Need Skilltree from the code sample above would loose 75% of the original logic.
• An issue with code generation: In order to generate the full code from the (essentially-partial) Skilltree, the designer must resort to either of the following two Skilltree styles, both insufficient:
  1. To specify only the main Need (and loose the rest). One then must finish the code manually.

     SOFTWARE COMPONENT Default
     CAPABILITY to log hello
         INPUT (1, formal) logger,
         - (2, formal) configurator, (3, formal) the system
         SIGNATURE logHello(:Logger, :Configurator, :System)
     ENTITY Logger
         CAPABILITY to open Log File
             INPUT (FORMAL) full name
             OUTPUT (FORMAL) Log File
             SIGNATURE open(:String):LogFile
     ENTITY Log File
         CAPABILITY to log message
             INPUT (FORMAL) string
             SIGNATURE log(:string)
     ENTITY Configurator
         CAPABILITY to get File Name
             INPUT (Formal) path
             OUTPUT (Formal) full name
             SIGNATURE getName(:string) :string
     ENTITY System
         CAPABILITY to get path name
             OUTPUT (Formal) current path
             SIGNATURE getPath(:string)
     BREAKDOEN OF CAPABILITY to log hello
         USE CASE Logging example
         Need to open Log File

     …generates…

     def logHello(aLogger, aConfigurator, theSystem):
         '''to log hello
         - Input: (1, formal) logger,
           (2, formal) configurator, (3, formal) the system'''
         // Message: to open Log File
         aLogger.open()

     Note that one cannot rely upon hints in the “Input” and “Output” rules to guide the implementer, because (1) these belong to the capability (rather the Need) and will go with it wherever else needed, and (2) because skill documentation is not copied under messages. The only option is insert this comment in the documentation of the enclosing capability (“to log hello”), which is far-fetched. 

  2. To arrange all Needs in sequence. One then must edit the code starter manually, to get the desired nested form. (Note that the messages are ordered by time-sequence, i.e. actual order of execution.)

     BREAKDOEN OF CAPABILITY to log hello
         USE CASE Logging example
         Need to get path name
         Need to get File Name
         Need to open Log File
         Need to log message

     …generates…

     def logHello(aLogger, aConfigurator, theSystem):
         '''to log hello
         - Input: (1, formal) logger,
           (2, formal) configurator, (3, formal) the system'''
         // Message: to get path name
         theSystem.getPath()
         // Message: to get File Name
         aConfigurator.getName()
         // Message: to open Log File
         aLogger.open()
         // Message: to log message
         aLogFile.log("hello world!")

The challenge:

To extend Skilltree syntax to allow Composite Needs – i.e. Needs that generate lines of code, many-to-one (many needs to one line of code), instead of one-to-one (one need to one line of code) - as of now).
Minor challenges:

• To adjust generated code documentation.
• To adjust use case minispec graphics.

Solution:

• The USING and GIVING Need attributes shall reference a familiar capability.
  • In this case, they generate an Composite Need, bound to the respective argument slot.
  • Otherwise, they continue to generate a variable name.
• In addition, the USING and GIVING Need attributes may form a recursive structure (i.e. an inner need tree).
• Note a semantic difference: “Using” substitutes the formal output of the apability with the value to be used. “Giving” specifies the receiver object of the result of the capability to be used. In the first case, the capability is on the left; in the second case, the capability is on the right!

The Skilltree:

BREAKDOWN OF CAPABILITY to log hello
    // Input: (1, formal) logger,
    // - (2, formal) configurator, (3, formal) the system
    Need to open Log File
        // Input: (Formal) full name
        // Output: (Formal) Log File
        USING to get File Name
            // Input: (Formal) path
            // Output: (Formal) full name
            USING to get path name
                // Output: (Formal) current path
        GIVING to log message

Design decisions:

• USING values are bound to INPUT (FORMAL) rules, position dependent.
  • In order to skip unused parameters (ie, that are not bound to ready values), it should be possible to indicate the exact binding, using anew syntax: (FOR [PARAMETER]).
• GIVING values are bound to the first formal OUTPUT rule, for now. (This should be extended in the future, to allow multiple return values that need be assigned, as in Python).
• Here is the fully-qualified example:

  BREAKDOEN OF CAPABILITY to log hello
      // Input: (1, formal) logger,
      // - (2, formal) configurator, (3, formal) the system
      Need to open Log File
          // input: full name
          // Output: (Formal) Log File
          USING to get File Name (FOR full name)
              // Input: (Formal) path
              // Output: (Formal) full name
              USING to get path name (FOR path)
                  // Output: (Formal) current path
      GIVING to log message (FOR Log File)

The code:

A “composite” (ie, tree-like) documentation style is, of-course, out of the question, since code documentation is strictly line-oriented. The documentation is oredered by time sequence. Nested messages are adorned as either “in argument” or “to the result”.

def logHello(aLogger, aConfigurator, theSystem):
    '''to log hello
    - Input: (1, formal) logger,
      (2, formal) configurator, (3, formal) the system'''
    // Message, in argument: to get path name
    // Message, in argument: to get File Name
    // Message: to open Log File
    // Message, to the result: to log message
    aLogger.open(aConfigurator.getName(theSystem.getPath())).log("hello world!")

Note that the comments are not qualified (by message path). This would be overkill! A reverse engineering engine can do the matching by analysis of the order of execution in the composite statement below.

Sequence diagram:

This medium follows, by defintion, a strict ordering: time sequence. Consequently, the mesages are ordered accordingly (as in the code documentation). The nesting is hinted by faint arrows marked “arg” and “res” respectively, pointing down. Some adustment is made to the start position of message text (to allow for the hint arrows).

Pseudocode:

This is one point where the tree chart deviates from the original Skilitree source. The prospect of an alternate flow that goes up would distort the general call tree order – down and right. The only ordering left is the simple time sequence, as in the sequence diagram.

Wire chart:

This medium is already displaying coupling in the right margin. Compound Need is a case of data coupling, so there is no need for radical adjustments.

Short form:

• INPUT/OUTPUT rules that correspond to USING/GIVING Need attributes are automatically elevated to FORMAL (and created to begin with) if missing (position dependent).
• USING/GIVING rules do not generate capabilities by default. Unknown capabilities (i.e. text starting with “to”) result in error.

Issues:

The following rare or complicated cases will not be supported (at least not in the first release):

• Inner capability trees. There is no technical problem in parsing such Skilltree, but this style seems to invites trouble, at least in theory. (So, this decision may change in the future.) Rationale: The “composite” structure in composite need applies only to input and output and is related to need (use of capabilities) rather than the capabilities themselves. Therefore, this looks (at least in theory) like an improper place to specify functional breakdown. Capabilities that are used for the first time within a composite need must still be specified in a separate use case (or where needed simply). 
  • As ususal, the need under the USING/GIVING, that is detailed in another use case, will be hyperlinked.
• Composite Need by assignment, (where the assignment operator represents a significant capability).
• Control constructs (selection and iteration) within USING/GIVING. Some languages enable such practices, e.g.
  • Selection is possible, in C and Python, using ternary if to specify the argument.
  • Iteration is possible, in Python, using list comprehension.