8. Command-line Interface

mappyfile includes two command line applications, format and validate. A command line interface (CLI), allows mappyfile to be easily integrated into Continuous Integration (CI) platforms such as Travis and Appveyor, and to automate validation and formatting of Mapfiles.

8.1. format

The format command can be used to apply consistent formatting and whitespace to a Mapfile, and to remove comments. It has the same parameters as the save function.

To format valid.map to a new valid_formatted.map file using the default formatting settings use the following syntax:

mappyfile format valid.map valid_formatted.map

Other examples are included in the help documentation for the command, shown below. To display this at the command line run the following:

mappyfile format --help

  Format a the input-mapfile and save as output-mapfile. Note output-mapfile
  will be  overwritten if it already exists.

  Example of formatting a single Mapfile:

      mappyfile format C:/Temp/valid.map C:/Temp/valid_formatted.map

  Example of formatting a single Mapfile with single quotes and tabs for

      mappyfile format C:/Temp/valid.map C:/Temp/valid_formatted.map
      --quote=\' --indent=1 --spacer=

  Example of formatting a single Mapfile without expanding includes, but
  including comments:

      mappyfile format C:/Temp/valid.map C:/Temp/valid_formatted.map --no-
      expand --comments

  --indent INTEGER            The number of spacer characters to indent
                              structures in the Mapfile  [default: 4]
  --spacer TEXT               The character to use for indenting structures in
                              the Mapfile
  --quote TEXT                The quote character to use in the Mapfile
                              (double or single quotes). Ensure these are
                              escaped e.g. \" or \' [default: \"]
  --newlinechar TEXT          The character used to insert newlines in the
                              Mapfile [default: \n]
  --expand / --no-expand      Expand any INCLUDE directives found in the
                              Mapfile  [default: True]
  --comments / --no-comments  Keep Mapfile comments in the output
                              (experimental)  [default: False]
  --help                      Show this message and exit.

8.2. validate

The validate command can be used to check values used in a Mapfile are valid, by comparing its contents to the Mapfile schema. It has the same parameters as the validate function.

The mappyfile development roadmap includes plans to allow validation against different versions of MapServer, for example validating Mapfiles for MapServer 7.0, or for 7.2. It is unlikely versions before version 7.0 will be considered.


When using wildcards to search for Mapfiles the Python glob module is used on Windows. This only searches subfolders that are one level-deep. On Linux wildcards are typically expanded in the shell, so Mapfiles in subfolders of any depth can be validated.

If validation errors are encountered in the Mapfile they will be displayed in the console output similar to below:

C:/Temp/map1.map validated successfully
C:/Temp/map2.map validated successfully
C:/Temp/map3.map (Line: 16 Column: 3) ERROR: Invalid value in TYPE - u'polyline' is not one of [u'chart', u'circle', u'line', u'point', u'polygon', u'raster', u'query', u'annotation']
3 file(s) validated (2 successfully)

8.2.1. Example 1

To validate all Mapfiles in the ms-ogc-workshop folder and all subfolders:

mappyfile validate D:\ms-ogc-workshop\ms4w\apps\ms-ogc-workshop\**\*.map

8.2.2. Example 2

To validate a single Mapfile, without expanding any INCLUDE directives:

mappyfile validate /world.map --no-expand

To display the command’s help text run the following:

mappyfile validate --help
Usage: mappyfile validate [OPTIONS] [MAPFILES]...

  Validate Mapfile(s) against the Mapfile schema

  The MAPFILES argument is a list of paths, either to individual Mapfiles,
  or a folders containing Mapfiles.  Wildcards are supported (natively on
  Linux, and up to one level deep on Windows). Validation errors are
  reported to the console. The program returns the error count - this will
  be 0 if no validation errors are encountered.

  Example of validating a single Mapfile:

      mappyfile validate C:/Temp/valid.map

  Example of validating two folders containing Mapfiles, without expanding

      mappyfile validate C:/Temp/*.map
      D:/GitHub/mappyfile/tests/mapfiles/*.map --no-expand

  --expand / --no-expand  Expand any INCLUDE directives found in the Mapfile
                          [default: True]
  --help                  Show this message and exit.