[Mapserver-dev] Next Generation MapScript API

[Frank Warmerdam]

Sean,

I have been thinking a bit about your "next generation" MapScript API and names
and what the implications might be for backward compatibility.  For the record,
let me say that I am a huge fan of backward compatibility ... to a fault no
doubt.

I would like to discuss what we can do to progress some of the naming
conventions towards a "next generation" without undue breaking of backward
compatibility.

First I will try to summarize the changes I think you are proposing in the
next generation API.

1) Change names of classes to not include the Obj suffix.  Basically use
    the MapScript aliases Map, Layer, Class, Style, Image, Point, Line, Shape,
    OutputFormat, Symbol, Color, Rect, Projection, Shapefile, SymbolSet and
    FontSet for the C level names map_obj, layer_obj, styleObj, imageObj,
    pointObj, lineObj, shapeObj, outputFormatObj, symbolObj, colorObj,
    rectObj, projectionObj, shapefileObj, symbolSetObj and fontSetObj.  The
    primary effect of this is in constructors which now would look like
    "x = mapscript.Map('adsf')" instead of "x = mapscript.map_obj('adsf')".

2) Change the getShape() method to return the shapeObj (instead of updating
    a shapeObj in place), and to place the tileindex after the shapeindex in
    the call list so the tileindex can be left defaulted.

3) Changed several methods on the geometry classes to be more specific:
     lineObj: get -> getPoint
              add -> addPoint
              set -> setPoint
     shapeObj: get -> getLine
               add -> addLine


4) Changed the copy() method on shapeObj to return a new reference instead of
    updating an existing one in place.

Does this summarize the proposed changes?  Assuming so, I would like to
propose some options to allow the update while not generally breaking
backward compatibility.

1) Can we create some sort of stubs under the old constructor names that
    would allow old code to still make the objects the same way they used to?
    Even to creating a dummy class for each of the old names with only a
    a constructor that returns a new style object name?  Or conversely, leave
    the actual class names with the old values, but create mini constructors
    with the new names to give nice creation semantics even if the objects
    thereafter go by their old names?

2) This is a hard one.  I hate to change this because I presume getshape()
    is used alot so the change will cause lots of breakage.  But I can see
    valid names for the new conventions and it isn't obvious what other name
    could be used that would make sense.  Though unfortunate, perhaps we could
    call the new generation form getShapeByIndex()?  This leaves us open to a
    getShapeNext() iterator at some point.

3) I can't see any reason we can't just have both sets of the get/add/set
    methods.

4) I think the old copy() semantics sort of suck and I like the new form.  But
    to avoid conflicts could we call it clone() instead?  The copy() copies a
    shapes information into another shape.  The clone() makes a whole new clean
    instance.

In each of the above cases I would suggest that the MapScript documentation only
document the new style names and methods.  What do you think?  I would *like*
this to be resolved before the 4.2 release if possible so we can issue it with
new style mapscript documentation and that as the default but without breaking
old MapScript applications.

Best regards,
-- 
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up   | Frank Warmerdam, warmerdam at pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush    | Geospatial Programmer for Rent