1. Parsing

Please note this page is currently a draft and subject to further updates.

mappyfile uses lark as the parsing engine.

1.1. Keywords

1.2. MapFiles

Details on the structure of the Mapfile can be found at: http://mapserver.org/mapfile/#notes

  • The Mapfile is NOT case-sensitive
  • Strings containing non-alphanumeric characters or a MapServer keyword MUST be quoted. It is recommended to put ALL strings in double-quotes.
  • The Mapfile has a hierarchical structure, with the MAP object being the root All other objects fall under this one.
  • Comments are designated with a #.
  • C-style comments have recently been added: https://github.com/mapserver/mapserver/pull/5362 - Both single line (e.g. /* foo */) and multi-line comments work.

1.3. Hierarchy

A summary of all the main Mapfile components is shown below. These are directives that are of the form TYPE..END.

_images/map_classes.png

The LAYER type has been split out into its own diagram due to its more complex nature:

_images/layer_classes.png

Other hierarchies and relationships can be seen on the http://www.mapserver.org/mapscript/mapscript.html#mapscript-classes page.

1.4. Mapfile Notes

This section details the various types of declaration found in a Mapfile.

  • Quoted strings. Used for quoted property values e.g.

    NAME "Layer1"
    DATA "lakes.shp"
    
  • Non-quoted lists. E.g. a POINTS block can be defined as follows:

    POINTS
        0 100
        100 200
        40 90
    END
    
  • Quoted lists. Used for property lists that should be quoted. E.g. the PROJECTION block can be defined as follows:

    PROJECTION
        'proj=utm'
        'ellps=GRS80'
        'datum=NAD83'
        'zone=15'
        'units=m'
        'north'
        'no_defs'
    END
    
  • Key-value lists.

    PROCESSING "BANDS=1"
    PROCESSING "CONTOUR_ITEM=elevation"
    PROCESSING "CONTOUR_INTERVAL=20"
    
  • Key-double-value lists. As above but there are two strings for each directive.

    CONFIG MS_ERRORFILE "stderr"
    CONFIG "PROJ_DEBUG" "OFF"
    CONFIG "ON_MISSING_DATA" "IGNORE"
    
  • Composite types- container declarations which finish with the keyword END. Examples:

    MAP ... END
    LAYER ... END
    CLASS ... END
    STYLE ... END
    

1.5. Including Files

The parser allows for files (containing further Mapfile declarations) referenced in the Mapfile to be loaded and parsed. Notes on the INCLUDE directive can be found at http://mapserver.org/mapfile/include.html:

  • Includes may be nested, up to 5 deep.
  • File location can be given as a full path to the file, or as a path relative to the Mapfile
  • If a string is provided to the parse method, then an optional root_folder parameter can be used to work with relative paths
MAP
    NAME "include_mapfile"
    EXTENT 0 0 500 500
    SIZE 250 250

    INCLUDE "test_include_symbols.map"
    INCLUDE "C:\Includes\test_include_layer.map"
END