Project

General

Profile

Bug #4694 ยป 0001-added-documentation-for-ERB-Compiler.patch

thinkerbot (Simon Chiang), 05/14/2011 02:32 PM

View differences:

lib/erb.rb
1 1
# = ERB -- Ruby Templating
2 2
#
3 3
# Author:: Masatoshi SEKI
4
# Documentation:: James Edward Gray II and Gavin Sinclair
4
# Documentation:: James Edward Gray II, Gavin Sinclair, and Simon Chiang
5 5
#
6 6
# See ERB for primary documentation and ERB::Util for a couple of utility
7 7
# routines.
......
265 265
#--
266 266
# ERB::Compiler
267 267
class ERB
268
  class Compiler # :nodoc:
268
  # = ERB::Compiler
269
  # 
270
  # Compiles ERB templates into Ruby code; the compiled code produces the
271
  # template result when evaluated. ERB::Compiler provides hooks to define how
272
  # generated output is handled.
273
  #
274
  # Internally ERB does something like this to generate the code returned by
275
  # ERB#src:
276
  #
277
  #   compiler = ERB::Compiler.new('<>')
278
  #   compiler.pre_cmd    = ["_erbout=''"]
279
  #   compiler.put_cmd    = "_erbout.concat"
280
  #   compiler.insert_cmd = "_erbout.concat"
281
  #   compiler.post_cmd   = ["_erbout"]
282
  #
283
  #   code, enc = compiler.compile("Got <%= obj %>!\n")
284
  #   puts code
285
  #
286
  # <i>Generates</i>:
287
  #
288
  #   #coding:UTF-8
289
  #   _erbout=''; _erbout.concat "Got "; _erbout.concat(( obj ).to_s); _erbout.concat "!\n"; _erbout
290
  #
291
  # By default the output is sent to the print method.  For example:
292
  #
293
  #   compiler = ERB::Compiler.new('<>')
294
  #   code, enc = compiler.compile("Got <%= obj %>!\n")
295
  #   puts code
296
  #
297
  # <i>Generates</i>:
298
  #
299
  #   #coding:UTF-8
300
  #   print "Got "; print(( obj ).to_s); print "!\n"
301
  #
302
  # == Evaluation
303
  #
304
  # The compiled code can be used in any context where the names in the code
305
  # correctly resolve. Using the last example, each of these print 'Got It!'
306
  #
307
  # Evaluate using a variable:
308
  #
309
  #   obj = 'It'
310
  #   eval code
311
  # 
312
  # Evaluate using an input:
313
  #
314
  #   mod = Module.new
315
  #   mod.module_eval %{
316
  #     def get(obj)
317
  #       #{code}
318
  #     end
319
  #   }
320
  #   extend mod
321
  #   get('It')
322
  #
323
  # Evaluate using an accessor:
324
  #
325
  #   klass = Class.new Object
326
  #   klass.class_eval %{
327
  #     attr_accessor :obj
328
  #     def initialize(obj)
329
  #       @obj = obj
330
  #     end
331
  #     def get_it
332
  #       #{code}
333
  #     end
334
  #   }
335
  #   klass.new('It').get_it
336
  #
337
  # Good! See also ERB#def_method, ERB#def_module, and ERB#def_class.
338
  class Compiler
269 339
    class PercentLine # :nodoc:
270 340
      def initialize(str)
271 341
        @value = str
......
501 571
      end
502 572
    end
503 573

  
504
    def content_dump(s)
574
    def content_dump(s) # :nodoc:
505 575
      n = s.count("\n")
506 576
      if n > 0
507 577
        s.dump + "\n" * n
......
510 580
      end
511 581
    end
512 582

  
583
    # Compiles an ERB template into Ruby code.  Returns an array of the code
584
    # and encoding like ["code", Encoding].
513 585
    def compile(s)
514 586
      enc = s.encoding
515 587
      raise ArgumentError, "#{enc} is not ASCII compatible" if enc.dummy?
......
575 647
      return out.script, enc
576 648
    end
577 649

  
578
    def prepare_trim_mode(mode)
650
    def prepare_trim_mode(mode) # :nodoc:
579 651
      case mode
580 652
      when 1
581 653
	return [false, '>']
......
599 671
      end
600 672
    end
601 673

  
602
    def make_scanner(src)
674
    def make_scanner(src) # :nodoc:
603 675
      Scanner.make_scanner(src, @trim_mode, @percent)
604 676
    end
605 677

  
678
    # Construct a new compiler using the trim_mode. See ERB#new for available
679
    # trim modes.
606 680
    def initialize(trim_mode)
607 681
      @percent, @trim_mode = prepare_trim_mode(trim_mode)
608 682
      @put_cmd = 'print'
......
611 685
      @post_cmd = []
612 686
    end
613 687
    attr_reader :percent, :trim_mode
614
    attr_accessor :put_cmd, :insert_cmd, :pre_cmd, :post_cmd
688

  
689
    # The command to handle text that ends with a newline
690
    attr_accessor :put_cmd
691

  
692
    # The command to handle text that is inserted prior to a newline
693
    attr_accessor :insert_cmd
694

  
695
    # An array of commands prepended to compiled code
696
    attr_accessor :pre_cmd
697

  
698
    # An array of commands appended to compiled code
699
    attr_accessor :post_cmd
615 700

  
616 701
    private
617 702
    def detect_magic_comment(s)
618
-