README in bindata-1.0.0 vs README in bindata-1.1.0
- old
+ new
@@ -46,10 +46,22 @@
Copyright © 2007 - 2009 [Dion Mendel](mailto:dion@lostrealm.com)
---------------------------------------------------------------------------
+# Installation
+
+You can install BinData via rubygems.
+
+ gem install bindata
+
+Alternatively, visit the
+[download](http://rubyforge.org/frs/?group_id=3252) page and download
+BinData as a tar file.
+
+---------------------------------------------------------------------------
+
# Overview
BinData declarations are easy to read. Here's an example.
class MyFancyFormat < BinData::Record
@@ -246,12 +258,14 @@
: is the name of a supplied type (e.g. `uint32be`, `string`, `array`)
or a user defined type. For user defined types, the class name is
converted from `CamelCase` to lowercased `underscore_style`.
`field_name`
-: is the name by which you can access the data. Use either a
- `String` or a `Symbol`.
+: is the name by which you can access the field. Use either a
+ `String` or a `Symbol`. If name is nil or the empty string, then
+ this particular field is anonymous. An anonymous field is still
+ read and written, but will not appear in `#snapshot`.
Each field may have optional *parameters* for how to process the data.
The parameters are passed as a `Hash` with `Symbols` for keys.
Parameters are designed to be lazily evaluated, possibly multiple times.
This means that any parameter value must not have side effects.
@@ -915,9 +929,37 @@
{:ruby}
---------------------------------------------------------------------------
# Advanced Topics
+
+## Skipping over unused data
+
+Some binary structures contain data that is irrelevant to your purposes.
+
+Say you are interested in 50 bytes of data located 10 megabytes into the
+stream. One way of accessing this useful data is:
+
+ class MyData < BinData::Record
+ string :length => 10 * 1024 * 1024
+ string :data, :length => 50
+ end
+{:ruby}
+
+The advantage of this method is that the irrelevant data is preserved
+when writing the record. The disadvantage is that even if you don't care
+about preserving this irrelevant data, it still occupies memory.
+
+If you don't need to preserve this data, an alternative is to use
+`skip` instead of `string`. When reading it will seek over the irrelevant
+data and won't consume space in memory. When writing it will write
+`:length` number of zero bytes.
+
+ class MyData < BinData::Record
+ skip :length => 10 * 1024 * 1024
+ string :data, :length => 50
+ end
+{:ruby}
## Wrappers
Sometimes you wish to create a new type that is simply an existing type
with some predefined parameters. Examples could be an array with a