Validation is a special tool, developed by Sytyi, GSoC 2011 participant.
This is a special page to answer validation-specified questions, since using of it is not so obvious.
General questions about validation
- When is validation done? - Validation is done while config fle is parsing. Parser calls validator when opens|closes tag or reads a key.
- Can I create my own validation, based on special idea? - Yes. Parser calls methods of an Abstract Base Class, so you can write your own realization and override methods. If you are interested - ValidationDesign can be useful for you. Good luck!
- What realizations are already written? - At this moment schema validation only.
General questions about schema validation
- What is the main idea of schema validation? - There is a special schema, describing allowed WML. At this moment of time next information is stored: Name of the tag, his minimal required and maximum allowed number of occasions (in context of his parent); List of keys allowed to use in this tag, each key has its name, type and default value (or is mandatory key); List of allowed child tags.
- What are the possible errors? - You can receive next errors:
- This tag|key is not allowed here.
- Required M tags, found X < M tags.
- Allowed N tags, found X > N tags.
- Missing mandatory key.
- Key has wrong value.
- Where can I read an error? - There are two modes of validation: default and strict. While default, errors arre printed in validation log. While strict (wgich can be enabled with --strict-validation) every validation error is treated as fatal, and creates a WML exception which stops reading of the file and prints error message either to console or on the screen (depends on file. I.e. GUI WML errors stop loading wesnoth and are printed to console).
I'm a WML contibutor
- How can I know that my WML was validated - Preparing of validation needs a lot of time. At this moment of time only one toplevel tag [gui] can be validated. Only C++ developer can enable validation and he needs schema file.
I'm a WML contibutor and I want to help in creating schema
- Can you tell some about schema in general? - Schema file is build from schema markup using schema_generator tool. Schema markup can be used both in different .cpp files and .schema files. Schema markup from different files is merged. Schema is stored in .cfg file as WML with toplevel [wml_schema]
- Where can I read detail info about schema markup format? - WML_Annotation_Format.
- How can I use schema_generator tool? - Run Cmake, Enable option "Enable tools", and run make. Two specific schema tools will be build: schema_generator and schema_validator. You can read about usage of the schema_generator on WML_Annotation_Format#Usage_of_the_tool Please, specify the input directory and the output file.
- How can I test my schema file? - Either read next article in this FAQ, or use schema_validator.
./schema_validator -i <input_file> -s <schema_file> Then you will see a lot of error messages.
I'm a C++ developer and I want to enable validation in my contributions to engine
If you are interested how that works, ValidationDesign can be useful for you.
- How can I do that? - First, you need to have initial schema file. Second, find all occasions of reading config file and using one of the read functions.
Create your validator object , catch exception (bad schema, or file not read), and send validator as a parameter to read(). You can specify whether you need strict validation or not. Id strict validation was not enabled errors will be put in "validation" log.
Future of validation
If you are interesting in future of validation, please read (here will be links to the forum, to the non-written yet threads about new schema markup format and putting schema info inside file to be validated)
Put your own questions here, please.
With best wishes - Sytyi (firstname.lastname@example.org)