Re: [boost] [soc] Boost.Reflection project - example

From: Janek Kozicki (janek_listy_at_[hidden])
Date: 2007-06-08 19:11:49

Jeremy Pack said:     (by the date of Thu, 7 Jun 2007 14:14:49 -0700)

> 1 - Call functions when you know the exact identifier (whatever type
> you decided the identifier should be ...), parameters, and return
> value.
> 2 - Call functions when you just put a whole bunch of possible
> parameters into a map, and then the call succeeds if it can find the
> values it needs, for instance:

I'm thinking about the most obvious usage scenario (for me) - if you
ever used AutoCAD you'll understand instantly, if not, then I'll try
to explain with an example:

Command: ci

// user invokes a command "ci" because he wants to draw a circle on the screen.
// A search in the reflection database is performed.
// "ci" is an alias to "circle". 
// (alias matching can be done outside Reflection library)
//
// Method circle has four(!) signatures:
//
// [1] accept a 2D point and a radius
//    Shape* Circle(point2d p, double radius);
//
// [2] accept three 2D points - circle is inscribed on them
//    Shape* Circle(point2d p1, point2d p2, point2d p3);
//
// [3] accept two 2D points, which also define the circle's diameter
//    Shape* Circle(point2d p1, point2d p2);
//
// [4] accept two pointers to Shape* to which circle must be tangent, and a radius
//    Shape* Circle(Shape* s1, Shape2* s2, double radius);
//
// User can give arguments to create a circle using any of them. He has
// just written a command "ci" - he has not decided yet which function he is
// going to use.
//
// Therefore the default (first) function has a lengthy description like this one:
// description_1:
//   std::string("CIRCLE Specify center point for circle or [3P/2P/Ttr (tan tan radius)]:")
//
// It means that user can do two things:
//
// 1. give a 2D point argument (by clicking) on screen which means that he agreed
//    to use the first function signature, and has just given the first
//    argument for it: a 2D point.
// 2. or write "3P"/"3" or "2P"/"2" or "Ttr"/"T"/"t" which means that he
//    has decided to use another function signature.
//
// for now, let's just lick on the screen, which will produce the coordinates:

CIRCLE Specify center point for circle or [3P/2P/Ttr (tan tan radius)]: 10,20

// the description for the second argument is a bit lenghty too, the reflection
// library needs to know a radius:
// description_2:
//   std::string("Specify radius of circle:")
// again, clicking on a screen produces a number in the command line:

Specify radius of circle or: 15
Command:

// And the circle is drawn.

The full command sequence looks like this:

Command: ci
CIRCLE Specify center point for circle or [3P/2P/Ttr (tan tan radius)]: 10,20
Specify radius of circle or [Diameter]: 15      // (**)
Command:

/////////////

Note that the function description_1 describes:
  1. the default method to draw a circle,
  2. its first argument type,
  3. a way to call different than default method  - the Reflaction library
     must recognize the signatures for that to work, and identify them.
     This can be done by giving them longer names, like:
     [1] is "circle"
     [2] is "circle 3p"
     [3] is "circle 2p"
     [4] is "circle ttr"
     The 'extra' name after space allows to distinguish them, and to
     call the correct one, when user types eg.: "t".
     Perhaps the code for handling that "t" is not inside the Reflection
     library itself, but the Reflection library certainly must provide
     a way to implement that by me, when I'm using it.

The second description_2 describes just the second argument. 

Important thing to note: AutoCAD is not aware what types of arguments
those functions expect. It's the user's job to provide the right ones.
A very simple mouse-click-feedback mechanism simply sends the
mouse-click results to the command line. They can be coordinates (if
an empty space is clicked), or Shape* (if another circle or line is
clicked). If given wrong arguments the method called by reflection
library will simply bail out with an error.

(**) The "[Diameter]" allows user to specify circle diameter instead
of radius. But diving into that detail will unnecessarily complicate
the (rather simple) example.

I hope that my explanation was clear?

I can give you much more examples like that. I've been using AutoCAD
almost as long as I'm coding in C++ ;-) And I wouldn't mind if I
wrote a replacement for AutoCAD in my free time.

Heh, what was a free time, again?

apparently something I seem to have now, as I'm posting like crazy to
boost mailing list today ;)

-- 
Janek Kozicki                                                         |