Source Code for Module Peach.generator

  1   
  2  ''' 
  3  Base generator object implementations. 
  4   
  5  @author: Michael Eddington 
  6  @version: $Id: Peach.generator-pysrc.html 1138 2008-08-16 19:39:03Z meddingt $ 
  7  ''' 
  8   
  9  # 
 10  # Copyright (c) 2005-2007 Michael Eddington 
 11  # Copyright (c) 2004-2005 IOActive Inc. 
 12  # 
 13  # Permission is hereby granted, free of charge, to any person obtaining a copy  
 14  # of this software and associated documentation files (the "Software"), to deal 
 15  # in the Software without restriction, including without limitation the rights  
 16  # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
 17  # copies of the Software, and to permit persons to whom the Software is  
 18  # furnished to do so, subject to the following conditions: 
 19  # 
 20  # The above copyright notice and this permission notice shall be included in     
 21  # all copies or substantial portions of the Software. 
 22  # 
 23  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
 24  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
 25  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
 26  # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
 27  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
 28  # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
 29  # SOFTWARE. 
 30  # 
 31   
 32  # Authors: 
 33  #   Michael Eddington (mike@phed.org) 
 34   
 35  # $Id: Peach.generator-pysrc.html 1138 2008-08-16 19:39:03Z meddingt $ 
 36   
 37  import sys 
 38  import traceback 
 39   
 40 -class Generator: 
 41          ''' 
 42          Generators generate data.  Examples of generators could be a static 
 43          string or integer, a string repeater, etc.  Generators can be "incremented" 
 44          by calling C{next()} to produce the next varient of data.  Generators can 
 45          be fairly complex, comainting sub-generators to build things like packets. 
 46           
 47          Generators support the interator protocol and can be used as such. 
 48           
 49          When building a Generator one should keep in mind that the value from a 
 50          generator could be asked for more then once per "round".  Also it is 
 51          recommended that you use the default C{getValue()} implementation and override 
 52          the C{getRawValue()} method instead. 
 53           
 54          @see: L{SimpleGenerator} 
 55          ''' 
 56           
 57 -        def __init__(self): 
 58                  ''' 
 59                  Base constructor, please call me! 
 60                  ''' 
 61                   
 62                  self._group = None 
 63                  self._transformer = None 
 64                  self._identity = None   # Stacktrace of were we came from 
 65                  self._name = None 
 66                   
 67                  # For debugging.  This is slow (0.02 sec), sometimes this init 
 68                  # function can get called like 50K times during initialization 
 69                  # of a large fuzzing object tree! 
 70                  #self._identity = traceback.format_stack() 
 71           
 72 -        def identity(self): 
 73                  ''' 
 74                  Who are we and were do we come from? 
 75                  ''' 
 76                   
 77                  return self._identity 
 78           
 79 -        def __iter__(self): 
 80                  ''' 
 81                  Return iterator for Generator object.  This is always the 
 82                  Generator object itself. 
 83                   
 84                  @rtype: Generator 
 85                  @return: Returns iterator, this is always self. 
 86                  ''' 
 87                  return self 
 88           
 89 -        def next(self): 
 90                  ''' 
 91                  Next value. OVERRIDE 
 92                   
 93                  From Python docs on next(): 
 94                   
 95                  I{The intention of the protocol is that once an iterator's next() method 
 96                  raises StopIteration, it will continue to do so on subsequent calls. 
 97                  Implementations that do not obey this property are deemed broken. (This 
 98                  constraint was added in Python 2.3; in Python 2.2, various iterators are 
 99                  broken according to this rule.)} 
100                   
101                  For Generators, please use the GeneratorCompleted exception instead of 
102                  StopIteration (its a subclass). 
103                  ''' 
104                  #sys.stderr("Generator.next: Raising GeneratorCompleted\n") 
105                  raise GeneratorCompleted("Peach.generator.Generator") 
106           
107 -        def getValue(self): 
108                  ''' 
109                  Return data, passed through a transformer if set. 
110                   
111                  @rtype: string 
112                  @return: Returns generated data 
113                  ''' 
114                   
115                  if self._transformer != None: 
116                          return self._transformer.encode(self.getRawValue()) 
117                   
118                  return self.getRawValue() 
119           
120 -        def getRawValue(self): 
121                  ''' 
122                  Return raw value w/o passing through transformer if set. OVERRIDE 
123                   
124                  @rtype: string 
125                  @return: Data before transformations 
126                  ''' 
127                   
128                  return None 
129           
130 -        def getGroup(self): 
131                  ''' 
132                  Get group this Generator belongs to.  Groups are used to increment sets 
133                  of Generators. 
134                   
135                  @rtype: Group 
136                  @return: Returns Group this generator belongs to 
137                  ''' 
138                  return self._group 
139           
140 -        def setGroup(self, group): 
141                  ''' 
142                  Set group this Generator belongs to.  This function will automaticly add 
143                  the Generator into the Group. 
144                   
145                  Groups are used to increment sets 
146                  of Generators. 
147                   
148                  @type   group: Group 
149                  @param  group: Group this generator belongs to 
150                  ''' 
151                  self._group = group 
152                  if self._group != None: 
153                          self._group.addGenerator(self) 
154           
155 -        def getTransformer(self): 
156                  ''' 
157                  Get transformer (if set).  Transformers are used to transform data in 
158                  some way (such as HTML encoding, etc). 
159                   
160                  @rtype: Transformer 
161                  @return: Current transformer or None 
162                  ''' 
163                  return self._transformer 
164           
165 -        def setTransformer(self, trans): 
166                  ''' 
167                  Set trasnformer.  Transformers are used to transform data in some way 
168                  (such as HTML encoding, etc). 
169                   
170                  @type   trans: Transformer 
171                  @param  trans: Transformer to run data through 
172                  @rtype: Generator 
173                  @return: self 
174                  ''' 
175                  self._transformer = trans 
176                  return self      
177           
178 -        def reset(self): 
179                  ''' 
180                  Called to reset the generator to its initial state. OVERRIDE 
181                  ''' 
182                  pass 
183           
184 -        def getName(self): 
185                  ''' 
186                  Get the name of this generator.  Usefull for debugging. 
187                  ''' 
188                  return self._name 
189           
190 -        def setName(self, name): 
191                  ''' 
192                  Set the name of this generator.  Usefull for debugging complex 
193                  data generators.  Stacktraces may end up in a generator creation 
194                  statement giving limited feedback on which generator in an array 
195                  might be causing the problem. 
196                   
197                  @type   name: string 
198                  @param  name: Name of generator 
199                  ''' 
200                  self._name = name 
201   
202   
203 -class SimpleGenerator(Generator): 
204          ''' 
205          A simple generator contains another, possibly complex generator statement. 
206          Usefull when breaking things apart for reuse. 
207           
208          To use, simply create a class that contains a _generator: 
209           
210                  class MySimpleGenerator(SimpleGenerator): 
211                          def __init__(self, group = None): 
212                                  SimpleGenerator.__init__(self, group) 
213                                  self._generator = GeneratorList(None, [ 
214                                          Static('AAA'), 
215                                          Repeater(None, Static('A'), 1, 100) 
216                                          ]) 
217           
218          NOTE: Do not set group on you generators unless they will not be incremented 
219          by self._generator.next(). 
220           
221          @see: L{Generator} 
222          ''' 
223           
224 -        def __init__(self, group = None): 
225                  ''' 
226                  @type   group: Group 
227                  @param  group: Group to use 
228                  ''' 
229                   
230                  Generator.__init__(self) 
231                  self.setGroup(group) 
232                  self._generator = None 
233           
234 -        def next(self): 
235                  self._generator.next() 
236           
237 -        def getRawValue(self): 
238                  return self._generator.getValue() 
239           
240 -        def reset(self): 
241                  self._generator.reset() 
242   
243   
244 -class GeneratorCompleted(StopIteration): 
245          ''' 
246          Exception indicating that the generator has completed all 
247          permutations of its data 
248          ''' 
249          pass 
250   
251   
252   
253  # end 
254