Pushing and popping the stack is useful, for example, to temporarily write a C function declaration to the header file just before it is defined. (In fact, Interscript has some special case functionality to support this while avoiding writing the function signature twice.)
The begin and end comments functions push and pop the tangler stack, the push comments function pushes the comment tangler associated withe the current tangler (if there is a current tangler, otherwise it pushes None. The comment tangler associated with the current tangler could also be, and is by default, None.)
Note that the begin and end comments functions invoke the internal push and pop functions; that is, they do not write begin and end section messages to the documentation file. That's because the comments are actually written to the code file, they're just formatted by the weaver like documentation rather than code.
Design note: There is always a current tangler object, possibly None. Interscript knows it is writing code, except when the current tangler is None, in which case it is writing documentation. I'm not so sure this is a wonderful scheme :-(
The begin and end string functions write the enclosed lines to the code file formatted as a (single) string. The resultant output is echoed to the documentation file.
The begin and end string functions reformat the enclosed lines as a single string in the target programming language. In C, for example, special character such as slosh are replaced by two sloshes. (Note that a leading @ can be included only by writing @@).
The begin string function supports two optional arguments. The eol argument determines what to insert at the end of a line, it will usually be either an empty string, a newline character sequence, or a single space.
Trailing whitespace is removed from each line. It is not possible to disable this feature, and that is deliberate. However, a second argument, width, if positive, will then pad the line to the specified width with spaces. This feature is designed to support two dimensional character arrays.
Design note: there is as yet not support for international character sets.
795: #line 1151 "input_frame.ipk" 796: def push(self,f): 797: if self.current_tangler: self.code_foot() 798: self.current_tangler_push(f) 799: if self.current_tangler: self.code_head() 800: 801: def pop(self): 802: if self.current_tangler: self.code_foot() 803: self.current_tangler_pop() 804: if self.current_tangler: self.code_head() 805: 806: #line 1162 "input_frame.ipk" 807: def select(self, *args, **kwds): 808: for arg in args: 809: self.select1(arg) 810: if kwds.has_key('tangler'): 811: self.select_tangler(kwds['tangler']) 812: if kwds.has_key('weaver'): 813: self.set_weaver(kwds['weaver']) 814: 815: def select1(self, arg): 816: if has_protocol(arg,'tangler'): 817: self.select_tangler(arg) 818: elif has_protocol(arg, 'weaver'): 819: self.set_weaver(arg) 820: else: 821: pass #permissive 822: 823: def select_tangler(self,f): 824: if self.current_tangler: self.code_foot() 825: self.tangler_set(f) 826: if self.current_tangler: self.code_head() 827: 828: def code_head(self): 829: dst_filename = self.current_tangler.sink.name 830: dst_lineno = self.current_tangler.sink.lines_written 831: src_filename = self.original_filename 832: src_lineno = self.original_count 833: 834: index = self.pass_frame.section_index 835: list = index.get(dst_filename, []) 836: list.append((dst_lineno, src_filename, src_lineno)) 837: index[dst_filename]=list 838: secno = len(list) 839: self.current_weaver.code_head(self.current_tangler, secno) 840: 841: def code_foot(self): 842: dst_filename = self.current_tangler.sink.name 843: index = self.pass_frame.section_index 844: list = index.get(dst_filename, []) 845: secno = len(list) 846: self.current_weaver.code_foot(self.current_tangler, secno) 847: 848: def begin_comments(self): 849: if self.current_tangler: 850: self.current_tangler_push(self.current_tangler.get_comment_tangler()) 851: else: 852: self.current_tangler_push(None) 853: 854: def end_comments(self): 855: self.current_tangler_pop() 856: 857: def resume_code(self): 858: self.current_tangler_pop() 859: 860: def comment(self,v): 861: self.get_weaver().write_comment(v) 862: 863: def begin_string(self,eol = ' ', width = 0): 864: if self.current_tangler: 865: self.current_tangler_push(self.current_tangler.get_string_tangler(eol,width)) 866: else: 867: self.current_tangler_push(None) 868: 869: def end_string(self): 870: tangler_pop() 871: 872: def weave(self,s): 873: weaver = self.get_weaver() 874: weaver.write(s) 875: 876: def weave_line(self,s): 877: weaver = self.get_weaver() 878: weaver.writeline(s) 879: 880: def tangle(self,s, inhibit_sref=0): 881: if self.current_tangler: 882: line = self.original_count 883: file = self.original_filename 884: self.current_tangler.writeline(s,file,line,inhibit_sref) 885: else: 886: print "tangle: No tangler for",s 887: