chunker/README
author Mahlon E. Smith <mahlon@martini.nu>
Sat, 22 Jan 2011 01:55:55 -0800
branchruby-modules
changeset 8 fe38422c10a4
parent 2 e5c705047540
permissions -rw-r--r--
Added signature for changeset 62a5ac525ce8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1
9e127bf6e84f Initial commit of chunker, a ruby module to aid with data blocks.
mahlon
parents:
diff changeset
     1
2
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     2
Preface:
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     3
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     4
	Ruby provides an automatic constant called DATA, which is an IO object
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     5
	that references all text in the current file under an __END__ token.
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     6
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     7
	I find it convenient to use the __END__ area to store all sorts of
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     8
	stuff, rather than have to worry about distributing separate files.
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
     9
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    10
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    11
The problem:
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    12
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    13
	The DATA constant is determined from whatever ruby believes $0 to be.
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    14
	It doesn't work inside of other required libraries, so you'll see stuff
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    15
	like this all the time:
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    16
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    17
	END = File.open( __FILE__ ).read.split( /^__END__/, 2 ).last
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    18
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    19
	It works, but it's more work than I want to do.
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    20
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    21
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    22
A workaround:
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    23
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    24
	Chunker solves this by parsing __END__ tokens for you, and making it
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    25
	available in the form of a 'DATA_END' constant.  It installs this
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    26
	constant into the class that includes Chunker, so you can use it again
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    27
	and again, assuming you use a different file for each class.
1
9e127bf6e84f Initial commit of chunker, a ruby module to aid with data blocks.
mahlon
parents:
diff changeset
    28
2
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    29
	It also automatically parses out other things that look like tokens, so
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    30
	you can easily have multiple, distinct documents all embedded into the
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    31
	__END__ block.
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    32
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    33
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    34
Usage:
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    35
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    36
	There is no direct interface to Chunker.  Just include it from a
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    37
	class to have that file's __END__ data blocks magically become DATA_*
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    38
	IO constants within that class.
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    39
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    40
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    41
Example:
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    42
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    43
	This produces the string "Yep.\n".
1
9e127bf6e84f Initial commit of chunker, a ruby module to aid with data blocks.
mahlon
parents:
diff changeset
    44
2
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    45
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    46
		require 'chunker'
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    47
		class Foom
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    48
			include Chunker
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    49
		end
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    50
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    51
		puts Foom.new.class.const_get( :DATA_WICKED ).read
1
9e127bf6e84f Initial commit of chunker, a ruby module to aid with data blocks.
mahlon
parents:
diff changeset
    52
2
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    53
		__END__
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    54
		Stuff in the END block!
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    55
		__WOW__
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    56
		Ultimate success!
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    57
		__WICKED__
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    58
		Yep.
e5c705047540 * Rename 'markers' to 'token'
mahlon
parents: 1
diff changeset
    59