1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22 23:- comment(alias, "Directives"). 24:- comment(summary, "Directives that can only appear in compiled files"). 25:- comment(categories, ["Built-In Predicates"]). 26 27:- tool(include / 1). 28:- tool(comment / 2). 29 30:- comment(pragma / 1, [ 31 summary:"Enable or disable compilation or other source processing options.", 32 index: [debug,expand,opt_level,system,skip,warnings], 33 amode:(pragma(+) is det), 34 desc:html("\ 35 The pragma/1 directive allows to control various compiler options, or 36 other source processing options. A pragma can only be used as a 37 directive in source files or lists given to compile_term/1,2. 38 The effect of a pragma is local to a source file (unlike set_flag/2). 39 Settings are in effect until the next pragma that overrides it or until 40 the end of the file. 41<PRE> 42 Option Effect 43 --------------------------------------------------------------- 44 [no]debug generate debuggable code 45 [no]expand do goal expansion/inline compilation 46 opt_level(N) set optimizer level (N>=0) 47 [no]skip set the skipped flag for all compiled predicates 48 system set the type of all compiled predicates to 'built_in' 49 [no]warnings generate compiler warnings 50</PRE> 51 The default for debug/nodebug depends on the global flag debug_compile 52 and the debug compiler option. 53 The default for expand/noexpand depends on the global flag goal_expansion 54 and the expand_goals compiler option. 55 The default for opt_level depends on the opt_level compiler option. 56 The default for skip is off. The default for warnings is on. 57 The global flags are set with set_flag/2 and tested with get_flag/2. 58<P> 59 Pragmas which the compiler does not recognise are silently ignored by 60 the compiler, but are recorded and can be retrieved using current_pragma/1. 61 Such pragmas can be atoms or structures with arbitrary arguments. 62<P> 63"), 64 args:["Option" : "An atom."], 65 exceptions:[148 : "An unknown Option was given."], 66 eg:" 67:- pragma(debug). 68:- pragma(expand). 69twice(X, Y) :- % this is compiled into debuggable 70 Y is 2*X. % code with expanded arithmetic 71 72 73 74", 75 see_also:[compile / 1, env / 0, get_flag / 2, get_flag / 3, pred / 1, set_flag / 3, set_flag / 2, (skipped) / 1, (unskipped) / 1, current_pragma/1]]). 76 77:- comment(comment/2, 78 79[ 80summary: "Adding documentational information to ECLiPSe files.", 81 82index: ["Literate programming"], 83 84args: ["Type": "Comment type", 85 "Information": "Information for Type"], 86 87amode:(comment(++,+) is det), 88 89see_also: 90[icompile/1,icompile/2,eci_to_html/3,ecis_to_htmls/0,ecis_to_htmls/3], 91 92desc: html("\ 93The comment/2 predicate allows documentational information to be added to 94ECLiPSe modules which can then be extracted and processed automatically by 95using the document tools in the document library. Please note that any 96reference to `comment' in the rest of this description means the comment 97predicate, not the normal ECLiPSe comment (% and /* ... */). 98<P> 99Operationally, comment/2 always succeeds, so it is a no-op and is 100ignored by ECLiPSe when executed. In order to be processed by the 101document tools, it should appear as a directive in the program, i.e. as 102<PRE> 103:- comment(Type, Information). 104</PRE> 105A comment directive provides information on various aspects of the module 106in which the comment occurs. The Type argument specifies what the aspect 107is, and Information gives the information associated with that aspect. Some 108restrictions should be observed to the placement of comments to allow automatic 109processing to correctly process the comments. These are listed at the end. 110 111The documentation generation tools and the tkeclipse library browser tool 112make use of the comments to generate documentations for modules. They 113recognise several comment types as specified by the Type argument and 114extract the information accordingly. 115The comments can occur in any order inside the module, and none 116are compulsory; if they are missing, then the information they could have 117provided is simply not used in the documentation generation. Most comment 118type should only occur at most once per module unless marked *multiple* in 119the following description. In the case of *multiple*, all occurrence of the 120comments of the type are processed by the documentation tools. Otherwise, 121only the first textual occurrence will be used. 122<P> 123The documentation tools recognise the following module-level comments: 124<DL> 125<DT><STRONG>comment(summary, String)</STRONG> 126 <DD>String is a short (one line) summary of the module. 127 128<DT><STRONG>comment(desc, Description)</STRONG> 129 <DD>Description is a longer Text (see below) describing the module in more 130 detail than summary. 131 132<DT><STRONG>comment(alias, String)</STRONG> *once* per file 133 <DD>String is used to override the module name used by the document 134 processing for the comments in the file. This allows the user to 135 generate groupings of comments in the documentation other than the 136 module in which the comments resides. 137 138<DT><STRONG>comment(status, String)</STRONG> 139 <DD>String is a single word, describing the status of the library. 140 Classification used in ECLiPSe: prototype, evolving, stable, phase_out, 141 deprecated. 142 143<DT><STRONG>comment(author, String)</STRONG> 144 <DD>String is the name of author(s) of the module. 145 146<DT><STRONG>comment(copyright, String)</STRONG> 147 <DD>String is the copyright notice that the documentation library will 148 generate for the documentations it produce from the comments. 149 150<DT><STRONG>comment(date, String)</STRONG> 151 <DD>This is designed for version control. String is a time-stamp 152 for the file. With CVS version control software, the string can 153 initially be set to \"$Date$\", which will be expanded by 154 CVS into the actual date each time the file is checked in. 155 156<DT><STRONG>comment(include, FileNames)</STRONG> *multiple* 157 <DD>FileNames is either one file name or a list of file names. The file 158 name is either a string or an atom. These are names of files in which 159 additional comments for the module are located. They are only processed 160 by the document library tools. 161 162<DT><STRONG>comment(index, ListOfStrings)</STRONG> 163 <DD>The strings are used by the documentation generation process to provide 164 pointers in the document index to the module: each string is added to 165 the index pointing at the module description. This is used to add extra 166 entries in the index in addition to the ones that are automatically 167 generated. 168 169<DT><STRONG>comment(categories, ListOfStrings)</STRONG> 170 <DD>A list of strings describing into which categories the library 171 belongs. This is used to generate a classified index page. 172 While the category names can be freely chosen, it is recommended 173 to stick to the predefined ones: \"Algorithms\", \"Compatibility\", 174 \"Constraints\", \"Data Structures\", \"Development Tools\", 175 \"Interfacing\", \"Programming Utilities\", \"Techniques\", 176 \"Visualisation\". 177</DL> 178In addition, it is possible to comment individual predicates and 179structures, using comment directives of the form: 180<DL> 181<DT><STRONG>comment(Name/Arity, ListofProperties)</STRONG> *once* for each Name/Arity 182 <DD>Name and Arity are the specification for a predicate in the module and 183 ListofProperties is a list of information for the predicate. The entries 184 are described below. 185 <P> 186 Instead of a list of properties, the atom 'hidden' can be specified. 187 This will prevent an undocumented, exported predicate from showing up 188 in the generated library documentation. 189 190<DT><STRONG>comment(struct(Name), ListofProperties)</STRONG> *once* for each structure 191 <DD>Name is the name of a structure and ListofProperties is a list 192 of information for the structure. The entries are described below 193 (admissible properties are: summary, fields, desc, see_also, 194 eg, index). 195</DL> 196In these comments, the ListOfProperties is a list of properties of the form: 197<PRE> 198 PropertyName: PropertyInformation 199</PRE> 200The properties can occur in any order in the list. 201The following ones are recognized by the document tools: 202<DL> 203<DT><STRONG>amode: FunctorTemplate</STRONG> *multiple* 204 <DD>FunctorTemplate is a structure corresponding to the functor of 205 the predicate with the arguments filled in with the modes admissible 206 for a call to the predicate. The valid modes are those generally 207 recognised by ECLiPSe (++, +, -, ?), with the following meaning: 208 <PRE> 209 ++ ground (fully instantiated, not containing variables) 210 + instantiated (not a variable) 211 - variable 212 ? any 213 </PRE> 214 The amode field can also be used to specify the determinism of a 215 call with a specific mode. In this case, the format is 216 <PRE> 217 amode:(FunctorTemplate is Determinism) 218 </PRE> 219 where FunctorTemplate is as above, and Determinism is an atom specifying 220 the determinism behaviour of a call with the particular mode. Determinism 221 can be one of: erroneous, failure, det, semidet, multi, nondet. Their 222 meaning is as defined for the Mercury programming language and can be 223 summarised as follows: 224 <PRE> 225 | Maximum number of solutions 226 Can fail? | 0 1 > 1 227 ------------+------------------------------------------ 228 no | erroneous det multi 229 yes | failure semidet nondet 230 </PRE> 231 The amode property can occur multiple times, each giving a 232 different mode for the predicate. The document tools 233 will generate the multiple modes description in the detail 234 description of the predicate, but will combine the modes by 235 generalising all the amodes to produce a general template 236 for the predicate in any summary description of the predicate. 237 238<DT><STRONG>args: ListofArgs</STRONG> 239 <DD>ListofArgs is a list of the argument descriptions describing the 240 argument. The length of the list should correspond to the arity of the 241 predicate. The argument description is of the form: 242 <PRE> 243 ArgName: Description 244 </PRE> 245 where both ArgName and Description are strings. If present, ArgName will 246 be used in the mode template. 247 248<DT><STRONG>desc: Description</STRONG> 249 <DD>Description is a Text (see below) giving a long description of the 250 predicate. 251 252<DT><STRONG>eg: Description</STRONG> 253 <DD>Description is a Text (see below) for examples of using the 254 predicate. This is used to generate the Examples section of the 255 predicate description. 256 257<DT><STRONG>exceptions: ListofErrors</STRONG> 258 <DD>ListofErrors is a list of error description of the form: 259 <PRE> 260 Int: Text 261 </PRE> 262 where Int is a error code for an error that can occur with the predicate 263 and Text describes the error. This is used to generate the 264 `Exceptions' section of the predicate description. 265 266<DT><STRONG>fail_if: Text</STRONG> 267 <DD>Text is a string describing the fail conditions for the predicate. It 268 is used to generate the `Fail Conditions' section of the predicate 269 description. 270 271<DT><STRONG>fields: ListofFields</STRONG> *structures only* 272 <DD>ListofFields is a list of the field descriptions describing the 273 structure fields. A field description is of the form: 274 <PRE> 275 FieldName: Description 276 </PRE> 277 where FieldName is an atom or string and Description is a Text. 278 279<DT><STRONG>index: ListofStrings</STRONG> 280 <DD>Each string in ListofString will be added to the index generated by the 281 document tools, pointing at the predicate. This is used to add 282 additional index entries for the predicate in addition to the predicate 283 names that is generated automatically. 284 285<DT><STRONG>resat: Resatisfiable</STRONG> 286 <DD>Resatisfiable is either yes or no, specifying if the predicate is 287 resatisfiable. This is used to generate the `Resatisfiable' section of 288 the predicate description. 289 290<DT><STRONG>see_also: ListofSpecs</STRONG> 291 <DD>ListofSpecs is a list of items, referring to other predicates 292 and libraries which are related to the commented predicate. This 293 is used to generate the `See Also' section of the predicate description. 294 The specs can be of the form Name/Arity, LibName:Name/Arity, 295 library(LibName). Name, Arity and LibName can be uninstantiated, 296 in which case links to every matching predicate or library will be 297 generated. The form link(URL,Text) can be used to insert arbitrary 298 hyperlinks. 299 300<DT><STRONG>summary: String</STRONG> *compulsory* 301 <DD>String is a short (one line) summary of the predicate. 302 303<DT><STRONG>template: String or list of strings</STRONG> 304 <DD>This is normally not needed. It is only useful to override 305 the most general default template that will otherwise be 306 automatically generated from the predicate name, the arguments and 307 and the amode information. 308 309<DT><STRONG>kind: ListofKinds</STRONG> 310 <DD>ListofKinds is a list of 'kind' information about the commented 311 predicate. Unlike the other fields, the kind information is not intended 312 for the generated documentation for the predicate, but instead, it is 313 intended for producing meta-information about the predicate that can 314 then be processed by ECLiPSe programs. Each item in the ListofKinds 315 has the following form: 316 <PRE> 317 Kind 318 </PRE> 319 or 320 <PRE> 321 Kind:Info 322 </PRE> 323 where Kind is an atom specifying some classification of the predicate 324 (e.g. constraint). Info is a list of further information about the 325 predicate, and can be the following: 326 <PRE> 327 root: Root 328 extra: Extra 329 </PRE> 330 where Root is an atom, the name of the 'root' module for the predicate. 331 If it is not specified, the root module is taken to be the module in 332 which the predicate is defined. 333 Extra is a list of Kind-specific information about the predicate. 334</P><P> 335 Each item in the ListofKinds will be processed by the document tools into 336 an ECLiPSe fact, and facts gathered from all the processed comment files 337 will be placed into a file after the processing. The fact is of the form: 338 <PRE> 339 kind(Kind, Name, Arity, Root, Module, Extra) 340 </PRE> 341 where Name and Arity is the name and arity of the predicate, and Module is 342 the module the predicate is defined in. 343</DL> 344Note that only the 'summary' property is compulsory, and apart from 345'amode', each property should occur at most once. 346<P> 347For the longer descriptions in the comments, a `Text' is allowed. 348This is either a normal ascii string or a string in a document markup 349language. In the latter case, the string must be enclosed in a 350wrapper. Currently the following are supported: 351<DL> 352<DT><STRONG>html(String)</STRONG> 353 <DD>String is in HTML format and can contain HTML tags. 354 Special characters must be written using HTML notation. 355 The string must be embeddable into an HTML document, 356 i.e. there should be no <html> .. </html> and 357 no headings. 358<DT><STRONG>ascii_fmt(String)</STRONG> 359 <DD>String is in ascii format. It will be rendered using a proportional 360 font and spacing and line breaks will be lost. 361<DT><STRONG>ascii(String)</STRONG> 362 <DD>String is in ascii format. It can consist of multiple lines 363 and will be rendered using a fixed width font with all spacing and 364 line breaks being preserved. 365 (To break lines without inserting a significant line break, 366 precede the line break with a '\\'). 367<DT><STRONG>String</STRONG> 368 <DD>The same as ascii_fmt(String), except in the 'eg' field 369 where it is interpreted as ascii(String). 370</DL> 371In order to allow automatic processing, the following should be observed 372with the placement of comments: 373<UL> 374 <LI> A comment should occur in a file. 375 376 <LI> A comment must occur as a directive. 377 378 <LI> A comment applies to a module, so it should occur textually inside 379 a module, i.e. after any module declarations. If the program does 380 not contain any module declarations, the file name (without suffix) 381 is assumed to be the module. 382 383 <LI> The file containing comments should only have a single module defined. 384</UL> 385Note that in addition to allowing automatic documentation generation, the 386comment predicates can also be used to provide information on the module 387itself when the user reads the program. Thus it can also act as comments in 388the same way as the traditional comments, but in a more structured way. 389"), 390eg:"\ 391 392% comments for the document library 393:- comment(summary, \"Automatic document generation library\"). 394 395:- comment(index, [\"Literate programming\", 396 \"automatic documentation generation\"]). 397 398% comment for comment/2 399:- comment(comment/2, [ 400 401 summary: \"Adding documentational information to ECLiPSe files.\", 402 403 index: [\"Literate programming\"], 404 405 args: [\"Type\": \"Comment type\", 406 \"Information\": \"Information for Type\"], 407 408 amode: comment(+,+), 409 410 resat: no, 411 412 fail_if: \"None. Always succeed.\", 413 414 see_also: 415 [icompile/1,icompile/2,eci_to_html/3,ecis_to_htmls/0,ecis_to_htmls/3], 416 417 desc: html(\"\ 418 The comment/2 predicate allows documentational information to be added to 419 ..... 420 \"), 421 422 eg: \"\ 423 424 % comments for the document library 425 :- comment(summary, \\\"Automatic document generation library\\\"). 426 427 ....the other examples you are seeing now 428 \" 429 430 ]). % end of comment directive for comment/2 431 432 433% other examples 434:- comment(fcompile/2, [ 435 summary: \"Generates an object file from the ECLiPSe source File in module Module.\", 436 args: [\"File\":\"Name of source file (Atom or string)\", 437 \"Module\":\"Name of module (Atom)\"], 438 amode: fcompile(+,+) 439 ]). 440 441 442:- comment(atom_string/2, [ 443 summary: \"Conversion between an atom and a string.\", 444 args: [\"Atom\": \"Atom or variable\", 445 \"String\": \"String or variable\"], 446 amode:(atom_string(+,-) is det), 447 amode:(atom_string(-,+) is det), 448 desc: \"\\ 449 If Atom is instantiated, converts it to a string String. 450 If String is instantiated, converts it to an atom Atom.\", 451 452 resat: no, 453 454 fail_if: \"\\ 455 Fails if the string String does not unify with the string version of the 456 atom Atom.\", 457 458 exceptions: [5: \"Atom is instantiated, but not to an atom.\", 459 5: \"String is instantiated, but not to a string.\", 460 4: \"Neither Atom nor String are instantiated.\"] 461 ]). 462 463" 464]). % end of comment directive 465 466 467:- comment(include/1, [ 468 summary: "Include other files as part of the program source.", 469 args: ["FileSpec": 470 "File name(s) (atom/string or list of atoms/strings)" 471 ], 472 amode:(include(+) is det), 473 see_also: ['.'/2,comment/2,library(source_processor)], 474 desc: html("\ 475<P> 476 Include the contents of other file(s) as if the contents of those 477 file(s) had been inserted in place of the directive. If more than 478 one file is specified, they are included in the order in which they 479 appear in the list FileSpec. 480</P><P> 481 Included files can contain clauses, directives and queries, but should 482 not contain module/1,3 directives (they would be interpreted as 483 occurring within the including file, and the included module would 484 not end at the end of the included file). The correct way to use 485 another module is via the use_module/1 directive. 486</P><P> 487 The square bracket notation [File] can be used as a synonym 488 for include(File) when used as a directive. 489</P><P> 490 To include files that contain only comment/2 directives, it is 491 preferable to use comment(include, File) - the file will then only 492 be included (and needed) by the comment processor, not the compiler. 493</P><P> 494 The rules for expanding the include file names are the same as 495 those used in compile/1,2 regarding suffixes and paths. 496</P>") 497]). 498 499 500:- comment(if/1, [ 501 summary: "Conditional compilation directive.", 502 args: ["Goal":"Goal to be tested" ], 503 amode:(if(+) is det), 504 see_also: [elif/1,else/0,endif/0,library(source_processor)], 505 desc: html("\ 506<P> 507 The compiler and other source-processing tools recognise the conditional 508 compilation directives if/1, elif/1, else/0 and endif/0. The first two 509 take a goal as their argument, and parts of the program source can be 510 included or excluded depending of the satisfiability of that goal. 511<P> 512 Note that these directives are the only ones that are not treated as 513 predicate separators and can be placed around individual clauses of 514 a predicate. 515 "), 516 eg:" 517 :- if(get_flag(hostarch,\"i386_nt\")). 518 519 ...Windows-specific code... 520 521 :- elif( (get_flag(version_as_list,Version), Version @>= [6,0]) ). 522 523 ...code for version 6.0 and later... 524 525 :- else. 526 527 ...alternative code... 528 529 :- endif. 530 " 531]). 532 533 534:- comment(elif/1, [ 535 summary: "Conditional compilation directive.", 536 args: ["Goal":"Goal to be tested" ], 537 amode:(elif(+) is det), 538 see_also: [if/1,else/0,endif/0], 539 desc: html("See if/1 for details.") 540]). 541 542:- comment(else/0, [ 543 summary: "Conditional compilation directive.", 544 amode:(else is det), 545 see_also: [if/1,elif/1,endif/0], 546 desc: html("See if/1 for details.") 547]). 548 549:- comment(endif/0, [ 550 summary: "Conditional compilation directive.", 551 amode:(endif is det), 552 see_also: [if/1,elif/1,else/0], 553 desc: html("See if/1 for details.") 554]). 555 556