Re: Yes, even more heatbug/Swarm programming style questions...

[Ken Cline]

Adding a little more to what Ted wrote:

As Ted said M(foo) is a macro that turns a method name, foo, 
into a selector.  Selectors are what are actually invoked to
"call" a method and method names are sort of short-hand
for the entire method specification (eg method name,
parameter types, return type, etc.) as I understand it. I
don't feel I could adequately explain the selector concept
so you would be better off to take a look at an Objective-C
text.  (BTW, there have been previous posts to the support
list that suggest good Objective-C to use, in case you were
wondering.)

And to remove all the mystery...

   defobj/defobj.h:#define M( messageName ) @selector( messageName )

That is M(foo) is equivalent to @selector(foo).

As far as the "forEach" method is concerned, this is a
rather straight forward function that simply loops thru a
collection (eg List, Map, Array) and calls the specified
method for each member.  Here's the code for one version of 
the "forEach" method:

   - (void) forEach: (SEL)aSelector
   {
      id       index, member;
 
      index = [(id)self begin: scratchZone];
      while ( (member = [index next]) ) {
         [member perform: aSelector];
      }
      [index drop];
   }

There are several "forEach" methods, the only difference is
the number of arguments they accept.  That is, if you want
each list member to execute a method that requires no
arguments then you would use the "forEach" method above.
For example, [myList forEach: M(print)], where print is
given by:
      -(void) print {
         printf("I am agent %s! \n", name);
      }

Of course, the "setBugColor" method you were asking about
requires 1 argument, namely the color.

Getting back to the "forEach" code above, the only action
within the loop is to call the "perform" method.  The
"perform" method is defined for the "Object" class, ie the
superclass of all classes, so any class can call this
method.  Note, however, that the "DefObject" class actually
redefines this method (and many other of methods in
"Object") and hence most Swarm classes actually inherit this
other version of "perform".

The "perform" method performs a method call on an object
using a selector and any required arguments.  That is the
following 2 method calls are equivalent:

   [ aBug perform: @selector(setBugColor:) with: red ];

and

   [ aBug setBugColor: red ];

(where we could have "(void *) red = (void *)64").

The advantage of the "perform" method is that it allows the
programmer to write very flexible code.  For example the
following pseudo-code could be easily written in
Objective-C:

   -prompt user for a color
   -check the validity of the user's entry
   -convert the the user's entry from a character string
       to a selector
   -set the bug's color to requested color

A less trivial example would be allow the user to select
which "brain" the agent will use during a particular phase
of the simulation.  There are other ways to give the user a
menu of choices, but the menu must be determined statically,
in other words before the code is compiled.

This is, btw, one of the reasons Objective-C was choosen as
the language to implement Swarm with.  Without this
flexiblity providing Swarm probing mechanism (amoung other
things) would much more complex.

My apologies if I'm repeating alot that you already know.

And one final comment about the "forEach" method... The
"forEach" method is mainly there for convience; it gives the
coder a short way to set something for an entire list and, I
think, makes the code very readable.

One drawback, though, is that it can't return values, so
often you still have to write your own loop.  This isn't
really a surprise since what value would you return?  It
would be possible to have a "forEach" method that returned a
list values, ie the results of each of the method calls, but
then you would have to loop thru that list (back to square
one).  One specialized case for which it might be worthwhile
to have "forEach" return a value would be if it was only
used to call boolean methods (ie methods with a boolean
return value).  Then you might have a "forEach" method
that "and-ed" or "or-ed" the results.  I'm not sure if
there's really much call for such a method, though.

Finally, as for the naming convention(s):

> As to the previous posts, is this right?
> (Cap letter)(Lower)(Cap)(Lower)...
> (ie. HeatbugObserverSwarm) would be a type? (or class?)
>
> (Lower)(Cap)(Lower)...
> (ie. heatbugObserverSwarm) would be an instance/object/swarm/agent?
> 
> (Lower)...
> (ie. colormap) would be a object that came with ObjectiveC?
>
> (Lower)(Cap)(Lower)...(and its a action)
> (ie. addLast:) would be a method?
>
> (Lower)...(and its a action)
> (ie. create: ) Would be an method defined in the Objective
> C libraries?

The naming conventions I follow are:

   If name of class/object or defined type
      then first letter is upper case.

   If name of variable or method
      then first letter is lower case..

   All interior words in a name start with an upper case.

   Single character variable names:
      if it is a class or instance variable
         then upper case.
      if it is a local variable
         then lower case.
      (this is the rule I break most often)

   Constant or defines are all caps.

So,

   Name of class: "Heatbug", "HeatbugObserverSwarm", etc.
      ("Heatbug" is considered one word)

   Name of defined type: "HeatValue", etc.

   Name of variable:
      "heatbug" is an instance of the "Heatbug" class
      "heatbugObserverSwarm" is an instance of the
         "HeatbugObserverSwarm" class
      etc.

   Name of method: "addLast:", "setX: Y:" etc.

I think this is a fairly typical naming convention.


> And what about Methods like: SetX: x Y: y  Is the method
> SetX: and Y: the same method or two different ones?  Or
> is Y: a label?

Are you asking about the Objective-C syntax?  That is, in
Objective-C methods are defined by the following convention:

  <symbol> (<type1>) <name1><keyword>: (<type2>) <name2>
                            <keyword>: (<type3>) <name3> ...

where

   <symbol>  := either "+" or "-", "+" indicates a factory
                method, "-" indicates an instance method

   <type1>   := method return type

   <name1>   := method name

   <keyword> := helps identify the argument that follows

   <type2>   := first argument's type

   <name2>   := first argument's (local) name

   <type3>   := second argument's type

   <name3>   := second argument's (local) name

   ...

So, 
      -(void) setX: (int) x Y: (int) y

is equivalent to, in most other languages (eg C++, Java),

      -(void) setXY( int x, int y )

And when calling a method you don't include the types,
therefore

   [ myObject setX: 3 Y: 5 ];

or

   myObject.setXY( 3, 5 );


> If Y is a label, isn't that unfair to Y, to make it a
> label to SetX:.....[grin]

What's modelling without a little labelling, eh?


Well I hope I didn't bore you to death with a lot of stuff
you already knew.

Ken.



_________________________________________________________
Ken Cline                             address@hidden
SAIC                                 VOICE (410) 571-0413
Annapolis, MD                          FAX (301) 261-8427



                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.
                  ==================================