1 //@copyright_begin 2 // ================================================================ 3 // Copyright Notice 4 // Copyright (C) 1998-2004 by Joe Linoff 5 // 6 // Permission is hereby granted, free of charge, to any person obtaining 7 // a copy of this software and associated documentation files (the 8 // "Software"), to deal in the Software without restriction, including 9 // without limitation the rights to use, copy, modify, merge, publish, 10 // distribute, sublicense, and/or sell copies of the Software, and to 11 // permit persons to whom the Software is furnished to do so, subject to 12 // the following conditions: 13 // 14 // The above copyright notice and this permission notice shall be 15 // included in all copies or substantial portions of the Software. 16 // 17 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 18 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 19 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 20 // IN NO EVENT SHALL JOE LINOFF BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 22 // ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 23 // OTHER DEALINGS IN THE SOFTWARE. 24 // 25 // Comments and suggestions are always welcome. 26 // Please report bugs to http://ccdoc.sourceforge.net/ccdoc 27 // ================================================================ 28 //@copyright_end 29 30 // MULTIPLE INCLUSION GUARD 31 #ifndef ccdoc_phase3_html_h 32 #define ccdoc_phase3_html_h 33 34 /** 35 * This variable allows the header version 36 * to be queried at runtime. 37 */ 38 namespace { 39 char ccdoc_phase3_html_h_rcsid[] = "$Id: phase3_html.h,v 1.8 2004/09/30 04:16:07 jlinoff Exp $"; 40 } 41 42 #include "switches.h" 43 #include "database.h" 44 #include "exceptions.h" 45 #include <fstream> 46 #include <set> 47 48 namespace ccdoc { 49 namespace phase3 { 50 /** 51 * Generate the HTML output. 52 * @author Joe Linoff 53 * @version $Id: phase3_html.h,v 1.8 2004/09/30 04:16:07 jlinoff Exp $ 54 */ 55 class html { 56 public: 57 /** 58 * Generate a checksum for a string. 59 * @author Joe Linoff 60 * @version $Id: phase3_html.h,v 1.8 2004/09/30 04:16:07 jlinoff Exp $ 61 */ 62 class checksum { 63 public: 64 /** 65 * Constructor. 66 */ checksum()67 checksum() {clear();} 68 /** 69 * Clear out the check sum. 70 */ 71 void clear(unsigned val = 0xffffffff) {m_checksum = val;} 72 /** 73 * Add a string. 74 */ set(const char * str)75 void set(const char* str) 76 { 77 for(;*str;++str) { 78 unsigned ch = *str; 79 m_checksum ^= ch; 80 ch = m_checksum & 0xff; 81 m_checksum = (m_checksum>>8) ^ m_crc_table[ch]; 82 } 83 m_checksum ^= 0xFFFFFFFF; 84 } 85 /** 86 * Get the checksum. 87 * @returns The checksum. 88 */ get()89 unsigned get() const {return m_checksum;} 90 private: 91 unsigned m_checksum; 92 static unsigned m_crc_table[256]; 93 }; 94 public: 95 /** 96 * Constructor. 97 * @param sw The command line switches. 98 * @param db The database interface. 99 */ 100 html(switches& sw,database& db); 101 /** 102 * Destructor. 103 */ 104 ~html(); 105 public: 106 /** 107 * Was this phase completed correctly? 108 * @returns True if it was or false if it wasn't. 109 */ ok()110 bool ok() const {return m_ok;} 111 public: 112 /** 113 * Run phase 3 processing to generate the HTML output. 114 */ 115 bool run(); 116 public: get_debug()117 bool get_debug() const {return m_debug;} set_debug(bool f)118 void set_debug(bool f) {m_debug=f;} 119 private: 120 void write_indent(ostream& os) const; 121 void write_unindent(ostream& os) const; 122 void write_section_header(ostream& os, 123 const char*, 124 bool, 125 const char* prev=0, 126 const char* next=0); 127 void write_section_header(ostream& os, 128 statement::base*, 129 bool, 130 const char* prev=0, 131 const char* next=0); 132 void write_contents(ostream& os,statement::base*,bool=true); 133 void write_ccdoc_src_info(ostream& os,statement::base*,statement::base*); 134 bool write_ccdoc_src_info(string& path,statement::base*); 135 void write_extends_clause(ostream& os,statement::base*); 136 void write_class_details(ostream& os,statement::base*,bool=true); 137 void write_friends_info(ostream& os,statement::base*); 138 void write_friends_link(ostream& os,statement::base*,statement::base*); 139 void write_code_section(ostream& os,statement::base*); 140 void write_code_subsection_var(ostream& os, 141 statement::base*, 142 statement::base::strs_t&); 143 void write_code_subsection_fct(ostream& os, 144 statement::base*, 145 statement::base::strs_t&); 146 void write_code_subsection_opr(ostream& os, 147 statement::base*, 148 statement::base::strs_t&); 149 void write_code_subsection_enum(ostream& os, 150 statement::base*, 151 statement::base::strs_t&); 152 void write_code_subsection_token(ostream& os, 153 statement::base*, 154 const string&); 155 bool write_code_subsection_token(ostream& os, 156 statement::base::stmts_t&, 157 const string&); 158 void write_code_subsection_token(statement::base::stmts_t& vec, 159 statement::base* stmt, 160 const vector<string>& tokens, 161 size_t idx) const; 162 bool is_cxx_keyword(const string&); 163 const char* format_string_for_html(const char*) const; 164 const char* format_string_for_html(const string&) const; 165 void write_html_formatted_string(ostream& os,const char*) const; 166 void write_html_formatted_string(ostream& os,const string&) const; 167 private: 168 /** 169 * Begin an indented code section. 170 * @param os Output stream. 171 */ 172 void code_begin(ostream& os); 173 /** 174 * End an indented code section. 175 * @param os Output stream. 176 */ 177 void code_end(ostream& os); 178 /** 179 * Load file. 180 * @param fn The file name. 181 * @param contents The string to load the file contents into. 182 */ 183 void load(const string& fn,string& contents); 184 private: 185 /** 186 * Write out the HTML files for the packages. 187 * @throws ccdoc::exceptions::unwriteable_output_file 188 * If the output file cannot be written. 189 */ 190 void write_ccdoc_pkgs_html(); 191 /** 192 * Write out the HTML files for the namespaces. 193 * @throws ccdoc::exceptions::unwriteable_output_file 194 * If the output file cannot be written. 195 */ 196 void write_ccdoc_namespaces_html(); 197 /** 198 * Write out the HTML files for the class, structs and unions. 199 * @throws ccdoc::exceptions::unwriteable_output_file 200 * If the output file cannot be written. 201 */ 202 void write_ccdoc_classes_html(); 203 /** 204 * Write out class summary file. 205 * @throws ccdoc::exceptions::unwriteable_output_file 206 * If the output file cannot be written. 207 */ 208 void write_ccdoc_class_summary_html(); 209 /** 210 * Write out class summary file. 211 * @throws ccdoc::exceptions::unwriteable_output_file 212 * If the output file cannot be written. 213 */ 214 void write_ccdoc_class_summary_html(ostream& os, 215 statement::base::stmts_t&, 216 bool rpthpc=false); 217 /** 218 * Write out class summary file. 219 * @throws ccdoc::exceptions::unwriteable_output_file 220 * If the output file cannot be written. 221 */ 222 void write_summary_tree(ostream& os, 223 statement::base::stmts_t&, 224 bool rpthpc=false, 225 statement::base* start = 0, 226 const char* indent = "", 227 bool sort_flag=true); 228 /** 229 * Write out class summary file. 230 */ 231 void write_summary_tree_entry(ostream& os, 232 statement::base* stmt, 233 const char* indent = 0, 234 bool rpthpc=false); 235 /** 236 * Write out the short description for the contents 237 * and summary. 238 */ 239 void write_short_desc(ostream& os, 240 statement::base* stmt); 241 /** 242 * Write out the HTML files for functions. 243 */ 244 void write_ccdoc_functions_html(); 245 /** 246 * Write out the HTML files for variables. 247 */ 248 void write_ccdoc_variables_html(); 249 /** 250 * Write out the HTML files for enums. 251 */ 252 void write_ccdoc_enums_html(); 253 /** 254 * Write out the HTML files for typedefs. 255 */ 256 void write_ccdoc_typedefs_html(); 257 /** 258 * Write out the HTML files for macros. 259 */ 260 void write_ccdoc_macros_html(); 261 private: 262 /** 263 * Write out the common header information. 264 * @param os Output stream. 265 * @param fn The file name. 266 * @param stmt The statement. 267 */ 268 void write_common_header_info(ostream& os, 269 const string& fn, 270 statement::base* stmt); 271 /** 272 * Write out the common header information. 273 * @param os Output stream. 274 * @param fn The file name. 275 * @param title The title. 276 */ 277 void write_common_header_info(ostream& os, 278 const string& fn, 279 const char* title); 280 private: 281 /** 282 * Write out a link. 283 * @param os Output stream. 284 * @param stmt The statement. 285 * @param name The optional link name. 286 */ 287 void write_link(ostream& os, 288 const statement::base* stmt, 289 const char* name=0); 290 private: 291 /** 292 * Extract and write links. 293 * @param os Output stream. 294 * @param link The name to look up in the database. 295 * @param linkid The link identifier. 296 * @param scope The scope for handling '#' operators in @link directives. 297 * @returns The number of items written. 298 */ 299 unsigned find_and_write_links(ostream&, 300 const char* link, 301 const char* linkid, 302 statement::base* scope); 303 private: 304 /** 305 * Write out multiple links by creating an alternate page (issue 0082). 306 * @param os Output stream. 307 * @param stmt The statement. 308 * @param name The optional link name. 309 */ 310 void write_links(ostream& os, 311 const statement::base::stmts_t& stmt, 312 const char* name); 313 private: 314 /** 315 * Write out the common trailer information. 316 * @param os Output stream. 317 */ 318 void write_common_trailer_info(ostream& os); 319 private: 320 /** 321 * Write out the ccdoc information. 322 * @param os Output stream. 323 * @param stmt The statement. 324 * @param author_required If true, the author field is required. 325 * If the author is required and not specified, the string 326 * "unascribed" is substituted. 327 * @param version_required If true, the version field is required. 328 * If the version is required and not specified, the string 329 * "unknown" is substituted. 330 * @param inherited If true, write out the hier_path of the 331 * parent. This is used when writing class details for a child 332 * that was defined in an inherited class. 333 */ 334 void write_ccdoc_info(ostream& os, 335 statement::base* stmt, 336 bool author_required=false, 337 bool version_required=false, 338 bool inherited=false); 339 private: 340 /** 341 * Write out a ccdoc description. 342 */ 343 void write_ccdoc_desc_info(ostream& os, 344 const statement::base::strs_t& vec, 345 statement::base* scope, 346 statement::base* stmt); 347 private: 348 /** 349 * Write out a ccdoc @param directive. 350 */ 351 void write_ccdoc_param_directive_info(ostream& os, 352 const statement::base::strss_t& vec, 353 statement::base* scope, 354 statement::base* stmt); 355 private: 356 /** 357 * Write out a ccdoc @exception directive. 358 * @param os The output stream. 359 * @param vec The exception data. 360 * @param scope The scope. 361 * @param stmt The statement for error reporting. 362 */ 363 void write_ccdoc_exception_directive_info(ostream& os, 364 const statement::base::strss_t& vec, 365 statement::base* scope, 366 statement::base* stmt); 367 private: 368 /** 369 * Write out a ccdoc @see directive. 370 */ 371 void write_ccdoc_see_directive_info(ostream& os, 372 const statement::base::strss_t& vecvec, 373 statement::base* stmt); 374 private: 375 /** 376 * Write out the Inherited From: clause. 377 */ 378 void write_inherited_from_info(ostream& os, 379 statement::base* stmt); 380 private: 381 /** 382 * Write out a ccdoc directive. 383 */ 384 void write_ccdoc_directive_info(ostream& os, 385 const char* name, 386 const statement::base::strs_t& vec, 387 const char* default_field, 388 statement::base* scope, 389 statement::base* stmt, 390 bool commas); 391 private: 392 /** 393 * Write out a ccdoc directive. 394 */ 395 void write_ccdoc_directive_info(ostream& os, 396 const char* name, 397 const string& val, 398 const char* default_field, 399 statement::base* scope, 400 statement::base* stmt); 401 void write_ccdoc_line_info(ostream& os, 402 statement::base::strs_citr_t& i, 403 statement::base::strs_citr_t e, 404 statement::base* scope, 405 statement::base* stmt); 406 private: 407 void write_meta(ostream& os, 408 const char* name, 409 const char* content); 410 private: 411 void make_class_contents(statement::base*, 412 statement::base::stmts_t&); 413 unsigned load_extend_classes(const string& id, 414 statement::base::stmts_t& out, 415 statement::base*); 416 void load_inheritance_classes(statement::base*, 417 statement::base::stmts_t&); 418 void make_class_contents(statement::base::stmts_t&, 419 statement::base::stmts_t&, 420 statement::base::stmts_t&, 421 set<string>& used_method_ids); 422 void get_fully_scoped_name(string& out_id, 423 const string& in_id, 424 statement::base::stmts_t parents) const; 425 private: 426 void make_contents(statement::base*, 427 statement::base::stmts_t&, 428 bool sort_flag=true); 429 bool ignore_contents_stmt(statement::base*) const; 430 void make_pkg_index_children(statement::base* stmt, 431 statement::base::stmts_t& outvec); 432 private: 433 void make_abs_path(statement::base* stmt,string& id) const; 434 void make_rel_path(statement::base* top,statement::base* stmt,string& id) const; 435 private: 436 void make_tag_id(const statement::base* stmt,string& id) const; 437 private: 438 const statement::base* get_file_stmt(const statement::base* stmt) const; 439 private: 440 void make_file_url(string& url,string& fn) const; 441 bool make_file_url(string& url,const statement::base* stmt); 442 private: 443 void make_unique_file_name(string& fn, 444 const statement::base* stmt); 445 private: 446 const char* format_name(const char*) const; 447 private: 448 /** 449 * Get the current date and time. 450 * @returns The date and time in a const char* buffer. 451 */ 452 const char* date_time() const; 453 private: 454 bool m_debug; 455 bool m_ok; 456 database& m_db; 457 set<string> m_keywords; 458 string m_meta; 459 string m_header; 460 string m_trailer; 461 string m_rptcsi; // Issue 0044 462 switches& m_sw; 463 unsigned m_multiple_ref_index; 464 }; 465 } 466 } 467 468 #endif 469