/// This struct describes in almost-C++ the json data structure as expected by the
/// project plugin.
/// The json file has to be named ".kateproject".
struct
{
   /// name of the project
   string name;

   /// The "directory" is optional.
   /// It is probably only useful for the kate-project-generator in cmake (>= 3.0.0).
   /// If set, the directory given here is used as the base directory for the project.
   /// Otherwise, the directory in which the project file is located as the base directory.
   string directory;
   
   /// "exclude_patterns" is a list of regex patterns than can be used to exclude folders and files from the project tree
   vector< string > exclude_patterns;

   /// The "files" struct describes which files belong to the project.
   /// There are five miutually exclusive methods to do this.
   struct files
   {
      /// "directory" is the files directory. If it is empty, the project base directory
      /// will be used. If it is a relative path, it is appended to the project
      /// base directory. Absolute paths work too.
      string directory;

      /// If "git" is set to "1", the list of files is retrieved by running git in the files directory.
      bool git;

      /// If "hg" is set to "1", the list of files is retrieved by running hg (mercurial) in the files directory.
      bool hg;

      /// If "svn" is set to "1", the list of files is retrieved by running svn (subversion) in the files directory.
      bool svn;

      /// If "fossil" is set to "1", the list of files is retrieved by running fossil in the files directory.
      bool fossil;

      /// "list" can be set to a list of files.
      vector< string > list;

      /// If nothing of the above has been set, "filters" can be set to a list of globbing expressions, which
      /// will be executed in the files directory.
      vector< string > filters;

      /// If "recursive" is set to 1, the globbing expressions in filters are executed recursively in the directory tree.
      bool recursive;

      /// If "hidden" is set to 1, hidden files will be retrieved. Only affects directories not managed by version control.
      bool hidden;
   };

   /// The "build" structure is optional.
   /// If set, its contents are used by the build plugin in kate.
   /// "targets", "default_target" and "clean_target" are supported starting with kate 4.13.
   /// The "build", "clean" and "quick" fields are only used if "targets" is empty.
   /// They servce for backward compatibility with the build plugin < 4.13, or they can
   /// be used as a quicker way to set up projects with up to 3 targets.
   struct build
   {
      /// The build directory
      string directory;

      /// "targets" contains a vector of targets (as in a makefile). Each target has a name
      /// a build command and a run command. The commands are executed in the build directory.
      vector< {string name, string build_cmd, string run_cmd} > targets;

      /// "default_target" must be set to one of the target names in "targets". This is the target
      /// which will be built by the "Build default target" action of the build plugin.
      string default_target;

      /// "clean_target" must be set to one of the target names in "targets". This is the target
      /// which will be built by the "Build clean target" action of the build plugin.
      string clean_target;

      /// Creates a target names "build" with the given command.
      string build;

      /// Creates a target names "clean" with the given command.
      string clean;

      /// Creates a target names "quick" with the given command.
      string quick;

   };

   /// The "ctags" structure is optional.
   /// If set, it may contain extra options for ctags command used to populate the auto completion popup in Kate.
   struct ctags
   {
      /// If "enable" is set to "1", a ctags index file is generated.
      /// If not present, generation of index depends on project plugin setting.
      bool enable;

      /// "options" can be set to a list of ctags options. You may need to escape character "\".
      vector< string > options;

      /// "index_file" can be set to path of ctags file to generate.
      /// A relative path is wrt to the project base directory.
      string index_file;
   }

};



Simple example, get files via globbing recursively in doc/, no build plugin:

{
   "name": "MyProject",
   "files": [ {
             "directory": "doc",
             "filters": ["*.tex", "Makefile"],
             "recursive": 1
       } ]
}


A project for a custom language named Swine whose source files have a suffix .swn:

{
   "name": "Custom",
   "files": [ {
         "directory": ".",
         "filters": ["*.swn"],
         "recursive": 1
      } ],
   "exclude_patterns": [ "build" ],
   "ctags": {
      "options": [
         "--langdef=swine",
         "--langmap=swine:.swn",
         "--regex-swine=/^def[ \t]*([a-zA-Z0-9_]+)/\\1/d,definition/"
      ]
   }
}


A more advanced project file, get the files from svn, set up three commands for the build plugin:

{
   "name": "Foo",
   "files": [ { "svn" : 1  } ],

   "build": {
      "directory": "build",
      "build": "make all -j4",
      "clean": "make clean",
      "quick": "make install"
  }
}


An out-of-source project file as generated by cmake: it points to the actual project directory,
it retrieves the file list from git, and a long list of targets for the build plugin:


{
   "name": "CMake@build",
   "directory": "/home/neundorf/src/CMake/cmake",
   "files": [ { "git": 1 } ],
   "build": {
       "directory": "/home/neundorf/src/CMake/build",
       "default_target": "all",
       "clean_target": "clean",
       "targets":[
           { "name":"all", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build -j8 all" },
           { "name":"clean", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build -j8 clean" },
           { "name":"cmLocalGenerator.cxx.o", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmLocalGenerator.cxx.o" },
           { "name":"cmLocalGenerator.cxx.i", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmLocalGenerator.cxx.i" },
...
           { "name":"cmLocalGenerator.cxx.s", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmLocalGenerator.cxx.s" },
           { "name":"cmMakefile.cxx.o", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmMakefile.cxx.o" },
           { "name":"cmMakefile.cxx.i", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmMakefile.cxx.i" },
           { "name":"cmMakefile.cxx.s", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmMakefile.cxx.s" }
       ] }
}
