:- module(asm).
:- export print_wam / 1.
:- export wam / 2.
:- export wam / 1.
:- export pasm / 3.
:- export disasm / 3.
:- export disasm / 2.
:- export asm / 3.
:- export asm / 2.
:- tool(wam / 1,wam / 2).
:- tool(disasm / 2,disasm / 3).
:- tool(asm / 2,asm / 3).
:- comment(wam / 2, hidden).
:- comment(disasm / 3, hidden).
:- comment(asm / 3, hidden).
:- comment(summary, "Assemble and disassemble predicates").
:- comment(desc, "    The asm library provide tools for assembling and disassembling the WAM\n    code representation of predicates to and from memory. It also allows\n    the formatted printing of the WAM code. This library is used by the\n    fcompile library to generate the object code, which is a form of the\n    WAM code that can be read back in and assembled into the predicates.").
:- comment(asm / 2, [summary : "Assemble the WAM instructions WAMCode into ECLiPSe as predicate PredSpec. \n\n", template : "asm(+PredSpec, +WAMCode)", desc : html("   Assembles the WAM instruction WAMCode into the current ECLiPSe session\n   as the predicate PredSpec. The WAM code is in the form of a list, with\n   each element representing one WAM instruction. The format of the WAMCode\n   is the same as that generated by disasm/2,3. Thus the predicate can be\n   used to load a predicate previously dissasembled by disasm/2,3 without\n   having to compile the source Prolog form of the predicate.\n\n<P>\n   The library asm must be loaded to use diasm/2.\n\n<P>\n   If PredSpec is an existing defined predicate, the older definition will\n   be replaced. If WAMCode is not in the correct format, an exception will\n   be generated and the predicate PredSpec would not be redefined. \n\n<P>\n"), args : ["+PredSpec" : "Atom/Integer.", "+WAMCode" : "A list of WAM instructions in the right format."], resat : "   No.", fail_if : "   None.\n\n", exceptions : [5 : "PredSpec is not in correct form.", 6 : "WAMCode is not in correct form.  "], see_also : [asm / 3, disasm / 2, disasm / 3, pasm / 3]]).
:- comment(asm / 3, [summary : "Assemble the WAM instructions WAMCode into ECLiPSe in module Module as\npredicate PredSpec.  \n\n", template : "asm(+PredSpec, +WAMCode, +Module)", desc : html("   Assembles the WAM instruction WAMCode into the current ECLiPSe session\n   in an existing module Module as the predicate PredSpec. The WAM code is\n   in the form of a list, with each element representing one WAM\n   instruction. The format of the WAMCode is the same as that generated by\n   disasm/2,3. Thus the predicate can be used to load a predicate\n   previously dissasembled by disasm/2,3 without having to compile the\n   source Prolog form of the predicate.\n\n<P>\n   The library asm must be loaded to use diasm/3.\n\n<P>\n   If PredSpec is an existing defined predicate, the older definition will\n   be replaced. If WAMCode is not in the correct format, an exception will\n   be generated and the predicate PredSpec would not be redefined. \n\n<P>\n"), args : ["+PredSpec" : "Atom/Integer.", "+WAMCode" : "A list of WAM instructions in the right format.", "+Module" : "An atom."], resat : "   No.", fail_if : "   None.\n\n", exceptions : [5 : "PredSpec or Module is not in correct form.", 6 : "WAMCode is not in correct form.  ", 80 : "Module is not an existing module."], see_also : [asm / 2, disasm / 2, disasm / 3, pasm / 3]]).
:- comment(disasm / 2, [summary : "Disassemble an existing predicate PredSpec in the current module to its WAM\nabstract machine representation WAMCode.\n\n", template : "disasm(+PredSpec, ?WAMCode)", desc : html("   Unifies WAMCode with the WAM instructions representing the abstract\n   machine code for the predicate specified by PredSpec (in Name/Arity\n   form). The WAM code is in the form of a list, with each element\n   representing one WAM instruction. The format of the WAMCode is the same\n   as that used by asm/2,3 and pasm/3 to assemble a predicate. Thus, the\n   WAM code generated by disasm/2,3 can be used to load the predicate into\n   ECLiPSe without having to compile the source Prolog form. \n\n<P>\n   The library asm must be loaded to use diasm/2.\n\n<P>\n   Currently asm/2 cannot disassemble dynamic predicates.\n\n<P>\n"), args : ["+PredSpec" : "Atom/Integer.", "?WAMCode" : "Variable or a list of WAM instructions in the right format."], resat : "   No.", fail_if : "   Fails if WAMCode is initially instantiated and does not unify with the WAM\n   code generated by asm/1 for the predicate, or if PredSpec is dynamic.\n\n", exceptions : [5 : "PredSpec is not in correct form.", 60 : "PredSpec does not exist in current module."], eg : "\n   for fruit/1 defined by:\n\n      fruit(orange).\n\n   ?- disasm(fruit / 1, W).\n   W = [get_atom(a(1), orange), retd, code_end]\n\n\n\n", see_also : [disasm / 3, asm / 2, asm / 3, pasm / 3, wam / 1]]).
:- comment(disasm / 3, [summary : "Disassemble an existing predicate PredSpec in the module Module to its WAM\nabstract machine representation WAMCode.\n\n", template : "disasm(+PredSpec, ?WAMCode, +Module)", desc : html("   Unifies WAMCode with the WAM instructions representing the abstract\n   machine code for the predicate specified by PredSpec (in Name/Arity\n   form) in module Module. The WAM code is in the form of a list, with each\n   element representing one WAM instruction. The format of the WAMCode is\n   the same as that used by asm/2,3 and pasm/3 to assemble a\n   predicate. Thus, the WAM code generated by disasm/2,3 can be used to\n   load the predicate into ECLiPSe without having to compile the source\n   Prolog form.\n\n<P>\n   The library asm must be loaded to use diasm/3.\n\n<P>\n   Currently asm/3 cannot disassemble dynamic predicates.\n\n<P>\n   If PredSpec is dynamic.\n\n<P>\n"), args : ["+PredSpec" : "Atom/Integer.", "?WAMCode" : "Variable or a list of WAM instructions in the right format.", "+Module" : "Atom"], resat : "   No.", fail_if : "   Fails if WAMCode is initially instantiated and does not unify with the WAM\n   code generated by asm/1 for the predicate, or if PredSpec is dynamic.\n\n", exceptions : [5 : "PredSpec or Module not in correct form.", 60 : "PredSpec does not exist in module Module.", 80 : "Module is not an existing module."], see_also : [disasm / 2, asm / 2, asm / 3, pasm / 3, wam / 1]]).
:- comment(pasm / 3, [summary : "Partially assemble WAMCode into an object format.\n\n", template : "pasm(+WAMCode, ?Size, ?Object)", desc : html("   Partially assemble the WAM instructions given WAMCode without loading it\n   into the current session. Instead, an object format is generated. This\n   object format can be loaded into an ECLiPSe session using the low level\n   built-in store_pred/5. fcompile/1,2 uses this predicate to generate the\n   object code for predicates.\n\n<P>\n   The partially assembled code consists of Object, which is a typed\n   representation of the words that need to be stored into memory; and\n   Size, the size in words that this object code will occupy in memory.\n\n<P>\n"), args : ["+WAMCode" : "A list of WAM instructions in the right format.", "?Size" : "Variable or integer", "?Object" : "A list of object words in the right format."], resat : "   No.", fail_if : "   If WAMCode is not in correct format.\n\n", see_also : [asm / 2, asm / 3, disasm / 2, disasm / 3, fcompile / 1, fcompile / 2]]).
:- comment(wam / 1, [summary : "Prints the formatted WAM code for predicate PredSpec.\n\n", template : "wam(+PredSpec)", desc : html("   Prints the WAM instructions representing the predicate specified by\n   PredSpec from the current module in a formatted form. Requires the \n   library asm to be loaded.\n\n<P>\n   If PredSpec is an atom (i.e. no arity is given), then a predicate with\n   that name is printed, and if there are more than one predicate defined\n   (i.e. same name but different arities), then these different predicates\n   will be printed by backtracking.\n\n<P>\n   This predicate is intended as a replacement for the lower level als/1,\n   which performs the same function. The differences are that the abstract\n   instruction names are printed in a more human oriented form (rather than\n   the internal names used by ECLiPSe), and labels and their references are\n   printed symbolically. Note that the predicate is implemented via the\n   disasm/3 predicate of the library, and hence the same restrictions\n   applies: it cannot be used to print the code for dynamic predicates.\n\n<P>\n"), args : ["+PredSpec" : "Atom, or Atom/Integer"], resat : "   Yes.", fail_if : "   If PredSpec is a dynamic predicate.\n\n", exceptions : [5 : "PredSpec not in correct form.", 60 : "PredSpec not defined in the current module."], see_also : [disasm / 2, disasm / 3, wam / 2, als / 1]]).
:- comment(wam / 2, [summary : "Prints the formatted WAM code for predicate PredSpec from module Module.", template : "wam(+PredSpec, +Module)", desc : html("   Prints the WAM instructions representing the predicate specified by\n   PredSpec in a formatted form. Requires the library asm to be loaded.\n\n<P>\n   If PredSpec is an atom (i.e. no arity is given), then a predicate with\n   that name is printed, and if there are more than one predicate defined\n   (i.e. same name but different arities), then these different predicates\n   will be printed by backtracking.\n\n<P>\n   This predicate is intended as a replacement for the lower level als/1,\n   which performs the same function. The differences are that the abstract\n   instruction names are printed in a more human oriented form (rather than\n   the internal names used by ECLiPSe), and labels and their references are\n   printed symbolically. Note that the predicate is implemented via the\n   disasm/3 predicate of the library, and hence the same restrictions\n   applies: it cannot be used to print the code for dynamic predicates.\n\n<P>\n"), args : ["+PredSpec" : "Atom, or Atom/Integer", "+Module" : "Atom."], resat : "   Yes.", fail_if : "   If PredSpec is a dynamic predicate.\n\n", exceptions : [5 : "PredSpec or Module not in correct form.", 60 : "PredSpec not defined in module Module.", 80 : "Module is not an existing module."], see_also : [disasm / 2, disasm / 3, wam / 1, als / 1]]).
