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.
649: #line 1002 "input_frame.ipk" 650: def push(self,f): 651: if self.tangler: self.code_foot() 652: self.tangler_push(f) 653: if self.tangler: self.code_head() 654: 655: def pop(self): 656: if self.tangler: self.code_foot() 657: self.tangler_pop() 658: if self.tangler: self.code_head() 659: 660: #line 1013 "input_frame.ipk" 661: def select(self,f): 662: if self.tangler: self.code_foot() 663: self.tangler_set(f) 664: if self.tangler: self.code_head() 665: 666: def code_head(self): 667: dst_filename = self.tangler.sink.name 668: dst_lineno = self.tangler.sink.lines_written 669: src_filename = self.original_filename 670: src_lineno = self.original_count 671: 672: index = self.pass_frame.section_index 673: list = index.get(dst_filename, []) 674: list.append((dst_lineno, src_filename, src_lineno)) 675: index[dst_filename]=list 676: secno = len(list) 677: self.weaver.code_head(self.tangler, secno) 678: 679: def code_foot(self): 680: dst_filename = self.tangler.sink.name 681: index = self.pass_frame.section_index 682: list = index.get(dst_filename, []) 683: secno = len(list) 684: self.weaver.code_foot(self.tangler, secno) 685: 686: def begin_comments(self): 687: if self.tangler: 688: self.tangler_push(self.tangler.get_comment_tangler()) 689: else: 690: self.tangler_push(None) 691: 692: def end_comments(self): 693: self.tangler_pop() 694: 695: def resume_code(self): 696: self.tangler_pop() 697: 698: def comment(self,v): 699: self.get_weaver().write_comment(v) 700: 701: def begin_string(self,eol = ' ', width = 0): 702: if self.tangler: 703: self.tangler_push(self.tangler.get_string_tangler(eol,width)) 704: else: 705: self.tangler_push(None) 706: 707: def end_string(self): 708: tangler_pop() 709: 710: def weave(self,s): 711: weaver = self.get_weaver() 712: weaver.write(s) 713: 714: def weave_line(self,s): 715: weaver = self.get_weaver() 716: weaver.writeline(s) 717: 718: def tangle(self,s, inhibit_sref=0): 719: if self.tangler: 720: line = self.original_count 721: file = self.original_filename 722: self.tangler.writeline(s,file,line,inhibit_sref) 723: else: 724: print "tangle: No tangler for",s 725: