src/FlightCrew/Validators/Opf/ReachabilityAnalysis.h

   1 /************************************************************************\r
   2 **\r
   3 **  Copyright (C) 2010  Strahinja Markovic\r
   4 **\r
   5 **  This file is part of FlightCrew.\r
   6 **\r
   7 **  FlightCrew is free software: you can redistribute it and/or modify\r
   8 **  it under the terms of the GNU Lesser General Public License as published\r
   9 **  by the Free Software Foundation, either version 3 of the License, or\r
  10 **  (at your option) any later version.\r
  11 **\r
  12 **  FlightCrew is distributed in the hope that it will be useful,\r
  13 **  but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  14 **  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  15 **  GNU Lesser General Public License for more details.\r
  16 **\r
  17 **  You should have received a copy of the GNU Lesser General Public License\r
  18 **  along with FlightCrew.  If not, see <http://www.gnu.org/licenses/>.\r
  19 **\r
  20 *************************************************************************/\r
  21 \r
  22 #pragma once\r
  23 #ifndef REACHABILITYANALYSIS_H\r
  24 #define REACHABILITYANALYSIS_H\r
  25 \r
  26 #include "../XmlValidator.h"\r
  27 #include <boost/unordered/unordered_map_fwd.hpp>\r
  28 #include <boost/unordered/unordered_set_fwd.hpp>\r
  29 \r
  30 namespace FlightCrew\r
  31 {\r
  32 \r
  33 /**\r
  34  * Reports errors with files that are unmanifested or unused and OPS\r
  35  * docs not in the OPF <spine>.\r
  36  */\r
  37 class ReachabilityAnalysis : public XmlValidator\r
  38 {\r
  39 public:\r
  40     \r
  41     // inherited\r
  42     virtual std::vector< Result > ValidateXml( \r
  43         const xc::DOMDocument &document,\r
  44         const fs::path &filepath = fs::path() );\r
  45 \r
  46 private:\r
  47 \r
  48     /**\r
  49      * Returns validation results for problems with OPS docs not present in the OPF spine.\r
  50      *\r
  51      * @param document The OPF document.\r
  52      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
  53      *                       values are full paths to those files.\r
  54      * @param reachable_resources A set of full paths to all the reachable files.\r
  55      * @return The validation results.\r
  56      */\r
  57     std::vector< Result > ResultsForOpsDocsNotInSpine( \r
  58         const xc::DOMDocument &document,\r
  59         const boost::unordered_map< std::string, fs::path > &manifest_items,\r
  60         const boost::unordered_set< fs::path > &reachable_resources );\r
  61 \r
  62     /**\r
  63      * Returns validation results for problems with resources not present in the OPF manifest.\r
  64      *\r
  65      * @param document The OPF document.\r
  66      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
  67      *                       values are full paths to those files.\r
  68      * @param reachable_resources A set of full paths to all the reachable files.\r
  69      * @return The validation results.\r
  70      */\r
  71     std::vector< Result > ResultsForResourcesNotInManifest( \r
  72         const boost::unordered_map< std::string, fs::path > &manifest_items,\r
  73         const boost::unordered_set< fs::path > &reachable_resources );\r
  74 \r
  75     /**\r
  76      * Returns validation results for problems with resources that are unused but present\r
  77      * in the OPF manifest.\r
  78      *\r
  79      * @param document The OPF document.\r
  80      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
  81      *                       values are full paths to those files.\r
  82      * @param reachable_resources A set of full paths to all the reachable files.\r
  83      * @return The validation results.\r
  84      */\r
  85     std::vector< Result > ResultsForUnusedResources(\r
  86         const boost::unordered_map< std::string, fs::path > &manifest_items,\r
  87         const boost::unordered_set< fs::path > &reachable_resources );\r
  88 \r
  89     /**\r
  90      * Determines if the specified file is allowed to be unreachable.\r
  91      * \r
  92      * @param filepath The file to analyze.\r
  93      * @return \c true if the file is allowed to be unreachable.\r
  94      */\r
  95     bool AllowedToBeNotReachable( const fs::path &filepath );\r
  96 \r
  97     /**\r
  98      * Returns an ID->fullpath mapping of the manifest items in the OPF document. \r
  99      *\r
 100      * @param document The OPF document.\r
 101      * @param opf_folder_path The path to the folder in which the OPF file resides.\r
 102      * @return The manifest items.\r
 103      */\r
 104     boost::unordered_map< std::string, fs::path > GetManifestItems( \r
 105         const xc::DOMDocument &document,\r
 106         const fs::path &opf_folder_path );\r
 107 \r
 108     /**\r
 109      * Returns a set of paths to the starting OPS documents. The starting docs are\r
 110      * the ones that are explicitly listed in the OPF or NCX in some way.\r
 111      *\r
 112      * @param document The OPF document.\r
 113      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
 114      *                       values are full paths to those files.\r
 115      * @param opf_folder_path The path to the folder in which the OPF file resides.\r
 116      * @return The starting OPS paths.\r
 117      */\r
 118     boost::unordered_set< fs::path > StartingSetOpsPaths( \r
 119         const xc::DOMDocument &document,\r
 120         const boost::unordered_map< std::string, fs::path > &manifest_items,\r
 121         const fs::path &opf_folder_path );\r
 122 \r
 123     /**\r
 124      * Returns a set of paths listed in the OPF <spine>.\r
 125      *\r
 126      * @param document The OPF document.\r
 127      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
 128      *                       values are full paths to those files.\r
 129      * @return The spine paths.\r
 130      */\r
 131     boost::unordered_set< fs::path > SpinePaths( \r
 132         const xc::DOMDocument &document,\r
 133         const boost::unordered_map< std::string, fs::path > &manifest_items );\r
 134 \r
 135     /**\r
 136      * Returns a set of paths listed in the OPF <guide>.\r
 137      *\r
 138      * @param document The OPF document.\r
 139      * @param opf_folder_path The path to the folder in which the OPF file resides.\r
 140      * @return The guide paths.\r
 141      */\r
 142     boost::unordered_set< fs::path > GuidePaths( \r
 143         const xc::DOMDocument &document,\r
 144         const fs::path &opf_folder_path );\r
 145 \r
 146     /**\r
 147      * Returns a set of paths listed in the OPF <tours>.\r
 148      *\r
 149      * @param document The OPF document.\r
 150      * @param opf_folder_path The path to the folder in which the OPF file resides.\r
 151      * @return The tours paths.\r
 152      */\r
 153     boost::unordered_set< fs::path > ToursPaths( \r
 154         const xc::DOMDocument &document,\r
 155         const fs::path &opf_folder_path );\r
 156 \r
 157     /**\r
 158      * Returns a path to the NCX file.\r
 159      *\r
 160      * @param document The OPF document.\r
 161      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
 162      *                       values are full paths to those files.\r
 163      * @return The path to the NCX.\r
 164      */\r
 165     fs::path GetPathToNcx( \r
 166         const xc::DOMDocument &document, \r
 167         const boost::unordered_map< std::string, fs::path > &manifest_items );\r
 168 \r
 169     /**\r
 170      * Returns a set of paths listed in the NCX.\r
 171      *\r
 172      * @param document The OPF document.\r
 173      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
 174      *                       values are full paths to those files.\r
 175      * @return The NCX paths.\r
 176      */\r
 177     boost::unordered_set< fs::path > NcxPaths( \r
 178         const xc::DOMDocument &document,\r
 179         const boost::unordered_map< std::string, fs::path > &manifest_items );\r
 180 \r
 181     /**\r
 182      * Returns a set of full paths to all the reachable resources.\r
 183      * \r
 184      * @param starting_ops_paths The paths to the starting OPS documents.\r
 185      * @return All the reachable resources.\r
 186      */\r
 187     boost::unordered_set< fs::path > DetermineReachableResources( \r
 188         const boost::unordered_set< fs::path > &starting_ops_paths );\r
 189 \r
 190     /**\r
 191      * Returns a list of all the resources that are directly reachable\r
 192      * (i.e. "one step away") from the provided resources.\r
 193      * \r
 194      * @param resources The resources from which reachability of new resources \r
 195      *                  will be determined.\r
 196      * @return The directly reachable resources.\r
 197      */\r
 198     boost::unordered_set< fs::path > GetDirectlyReachableResources( \r
 199         const boost::unordered_set< fs::path > &resources );\r
 200 \r
 201     /**\r
 202      * From the set of provided resources, returns only the OPS ones.\r
 203      * \r
 204      * @param resources The resource set.\r
 205      * @return The OPS resources.\r
 206      */\r
 207     boost::unordered_set< fs::path > GetOnlyOpsDocs( \r
 208         const boost::unordered_set< fs::path > &resources );\r
 209 \r
 210     /**\r
 211      * From the set of provided resources, returns only the CSS ones.\r
 212      * \r
 213      * @param resources The resource set.\r
 214      * @return The CSS resources.\r
 215      */\r
 216     boost::unordered_set< fs::path > GetOnlyCssDocs( \r
 217         const boost::unordered_set< fs::path > &resources );\r
 218 \r
 219     /**\r
 220      * For all the provided OPS docs, returns a set of all reachable resources.\r
 221      * \r
 222      * @param resources The OPS path set.\r
 223      * @return The reachable resources.\r
 224      */\r
 225     boost::unordered_set< fs::path > GetLinkedResourcesFromAllOps( \r
 226         const boost::unordered_set< fs::path > &ops_docs );\r
 227 \r
 228     /**\r
 229      * For all the provided CSS docs, returns a set of all reachable resources.\r
 230      * \r
 231      * @param resources The OPS path set.\r
 232      * @return The reachable resources.\r
 233      */\r
 234     boost::unordered_set< fs::path > GetLinkedResourcesFromAllCss( \r
 235         const boost::unordered_set< fs::path > &css_docs );\r
 236 \r
 237     /**\r
 238      * For the provided OPS doc, returns a set of all reachable resources.\r
 239      * \r
 240      * @param resources The OPS path.\r
 241      * @return The reachable resources.\r
 242      */\r
 243     boost::unordered_set< fs::path > GetLinkedResourcesFromOps(\r
 244         const fs::path &ops_document );   \r
 245 \r
 246     /**\r
 247      * For the provided CSS doc, returns a set of all reachable resources.\r
 248      * \r
 249      * @param resources The CSS path.\r
 250      * @return The reachable resources.\r
 251      */\r
 252     boost::unordered_set< fs::path > GetLinkedResourcesFromCss(\r
 253         const fs::path &css_document );\r
 254 \r
 255     /**\r
 256      * Extracts the paths from map into a set.\r
 257      * \r
 258      * @param manifest_items A map of manifest items. The keys are the IDs, the\r
 259      *                       values are full paths to those files.\r
 260      * @return A set of all the paths.\r
 261      */\r
 262     boost::unordered_set< fs::path > GetPathsFromItems( \r
 263         const boost::unordered_map< std::string, fs::path > &manifest_items );\r
 264 \r
 265     /**\r
 266      * Examines if the provided path points to a file on the filesystem.\r
 267      * (as opposed to a file on the Internet).\r
 268      *\r
 269      * @param path The path to inspect.\r
 270      * @return \c true if the path is a filesystem path.\r
 271      */\r
 272     bool IsFilesystemPath( const fs::path &path );\r
 273 };\r
 274 \r
 275 } // namespace FlightCrew\r
 276 \r
 277 #endif // REACHABILITYANALYSIS_H\r
 278 \r