1.1   Pseudocode

All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a statement. For object attributes and methods we use the dot, '.', operator. Creation and deletion of objects will be indicated by 'new' and 'del' keywords. Other than that, the pseudocode looks a lot like Python.

3.1   New instances

The mapfile path argument to the mapObj constructor is now optional.

empty_map = new mapscript.mapObj

generates a default mapObj with no layers. A mapObj is initialized from a mapfile on disk in the usual manner:

test_map = new mapscript.mapObj('tests/test.map')

3.2   Cloning

An independent copy, less result and label caches, of a mapObj can be produced by the new mapObj.clone() method:

clone_map = test_map.clone()

3.3   Saving

A mapObj can be saved to disk using the save method:

clone_map.save('clone.map')

Frankly, the msSaveMap() function which is the foundation for mapObj::save is incomplete. Your mileage may vary.

4.1   Referencing a Child

References to Layer, Class, and Style children are obtained by "getChild"-like methods of their parent:

layer_i   = test_map.getLayer(i)
class_ij  =  layer_i.getClass(j)
style_ijk = class_ij.getStyle(k)

These references are for convenience only. Mapscript doesn't have any reference counting, and you are certain to run into trouble if you try to use these references after the parent mapObj has been deleted and freed from memory.

4.2   Cloning a Child

A completely independent Layer, Class, or Style can be created using the clone method of layerObj, classObj, and styleObj:

clone_layer = layer_i.clone()

This instance has no parent, and is self-owned.

4.3   New Children

Uninitialized instances of layerObj, classObj, or styleObj can be created with the new constructors:

new_layer = new mapscript.layerObj
new_class = new mapscript.classObj
new_style = new mapscript.styleObj

and are added to a parent object using "insertChild"-like methods of the parent which returns the index at which the child was inserted:

li = test_map.insertLayer(new_layer)
ci = test_map.getLayer(li).insertClass(new_class)
si = test_map.getLayer(li).getClass(ci).insertStyle(new_style)

The insert* methods create a completely new copy of the object and store it in the parent with all ownership taken on by the parent.

see the API reference for more details.

4.4   Backwards Compatibility

The old style child object constructors with the parent object as a single argument:

new_layer = new mapscript.layerObj(test_map)
new_class = new mapscript.classObj(new_layer)
new_style = new mapscript.styleObj(new_class)

remain in MapServer 4.4.

4.5   Removing Children

Child objects can be removed with "removeChild"-like methods of parents, which return independent copies of the removed object:

# following from the insertion example ...
# remove the inserted style, returns a copy of the original new_style
removed_style = test_map.getLayer(li).getClass(ci).removeStyle(si)
removed_class = test_map.getLayer(li).removeClass(ci)
removed_layer = test_map.removeLayer(li)

5.1   New API

In MapServer 4.4, the metadata attributes of mapObj.web, layerObj, and classObj are instances of hashTableObj, a class which functions like a limited dictionary:

layer.metadata.set('wms_name', 'foo')
name = layer.metadata.get('wms_name')   # returns 'foo'

You can iterate over all keys in a hashTableObj like:

key = NULL
while (1):
    key = layer.metadata.nextKey(key)
    if key == NULL:
        break
    value = layer.metadata.get(key)
    ...

See the API Reference (mapscript.txt) for more details.

5.2   Backwards Compatibility for Metadata

The old getMetaData and setMetaData methods of mapObj, layerObj, and classObj remain for use by older programs.