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
Usage: mappyfile format [OPTIONS] INPUT_MAPFILE OUTPUT_MAPFILE
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
indentation:
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
Options:
--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.
mappyfile also allows validation against different versions of MapServer, for example validating Mapfiles for MapServer 7.0, or for 7.6.
Note
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
8.2.3. Example 3¶
To validate a Mapfile for version 7.6 of MapServer:
mappyfile validate /world.map --version=7.6
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
INCLUDES:
mappyfile validate C:/Temp/*.map
D:/GitHub/mappyfile/tests/mapfiles/*.map --no-expand
Options:
--expand / --no-expand Expand any INCLUDE directives found in the Mapfile
[default: True]
--help Show this message and exit.
8.3. schema¶
Save the Mapfile schema to a file. Set the version parameter to output a specific version.
mappyfile schema --help
Usage: mappyfile format [OPTIONS] INPUT_MAPFILE OUTPUT_MAPFILE
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
indentation:
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
Options:
--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.
