6.10.11.1.2. Managing the tangler stack

6.10.11.1.2. Managing the tangler stack

These commands also push, pop, and set the tangler stack, but they also generate start and end section messages in the documentation file. They are intended for use by the end user.

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.

Start python section to interscript/frames/inputf.py[29]
   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: 
End python section to interscript/frames/inputf.py[29]