aboutsummaryrefslogtreecommitdiff
path: root/doc/nerv_io.md
diff options
context:
space:
mode:
authorTed Yin <[email protected]>2015-06-06 12:27:34 +0800
committerTed Yin <[email protected]>2015-06-06 12:27:34 +0800
commit3959b99c4853c4deb20324ad0c54906f8ed1348a (patch)
treec67e8d625fc5d31c048fca72e3dbeadafec0b9a2 /doc/nerv_io.md
parent0bb9cd4271f127c311fd9839855def8f9ea91dab (diff)
parent3faaef779e384e6283761906552c6c6c4eafb3dd (diff)
Merge pull request #19 from cloudygoose/master
add doc for io module
Diffstat (limited to 'doc/nerv_io.md')
-rw-r--r--doc/nerv_io.md107
1 files changed, 97 insertions, 10 deletions
diff --git a/doc/nerv_io.md b/doc/nerv_io.md
index d452d5d..07589df 100644
--- a/doc/nerv_io.md
+++ b/doc/nerv_io.md
@@ -2,25 +2,112 @@
Part of the [Nerv](../README.md) toolkit.
##Description##
-There are four classes in to deal with chunk data, which are __nerv.ChunkFile__, __nerv.ChunkFileHandle__, __nerv.ChunkInfo__, __nerv.ChunkData__. Below is the underlying C structs.
+The main class that the user uses to store and read parameter object to and from files is __nerv.ChunkFile__.
+In the file, a parameter object will be saved using a standard format. First is the length(in byte) of this object, then a table which includes some meta information of the object, and a data area. Below is an example text file.
+```
+[0000000000202]
+{type="nerv.ExampleP",info={message="just-a-try"},id="exampleP1"}
+3 3
+5.000000 5.000000 5.000000
+5.000000 5.000000 5.000000
+5.000000 5.000000 5.000000
+1 3
+4.000000 4.000000 4.000000
+[0000000000202]
+{type="nerv.ExampleP",info={message="just-a-try"},id="exampleP2"}
+3 3
+4.000000 4.000000 4.000000
+4.000000 4.000000 4.000000
+4.000000 4.000000 4.000000
+1 3
+3.000000 3.000000 3.000000
+```
+
+##Methods##
+* __ChunkFile ChunkFile(string fn, string mode)__
+`mode` can be `r` or `w`, for reading or writing a file. The returned __ChunkFile__ will be ready to write or read objects which follows the __nerv.Param__ interface(using `write_chunk` and `read_chunk`).
+* __void ChunkFile.write_chunk(ChunkFile self, Param p)__
+Write `p` into the file. `p:write` will be called.
+* __Param ChunkFile.read_chunk(ChunkFile self, string id, table global_conf)__
+Read the __Param__ object by id `id` from the file `self`. It will be constructed using `__init(id, global_conf)`. `p:read` will be called.
+* __void ChunkFile.close(ChunkFile self)__
+Close the opened file.
+
+##Examples##
+* An example showing how to use __ChunkFile__ to store and read parameter objects.
+```
+require 'io'
+do
+ local mt, mpt = nerv.class('nerv.ExampleP', 'nerv.Param')
+ function nerv.ExampleP:__init(id, global_conf)
+ self.id = id
+ self.global_conf = global_conf
+ self.matrix = nerv.MMatrixFloat(3, 3)
+ for i = 0, 2, 1 do
+ for j = 0, 2, 1 do
+ self.matrix[i][j] = 3
+ end
+ end
+ self.bias = nerv.MMatrixFloat(1, 3)
+ for i = 0, 2, 1 do
+ self.bias[i] = 2;
+ end
+ self:set_info({message = 'just-a-try'})
+ end
+ function nerv.ExampleP:addOne()
+ for i = 0, 2, 1 do
+ for j = 0, 2, 1 do
+ self.matrix[i][j] = self.matrix[i][j] + 1
+ end
+ end
+ for i = 0, 2, 1 do
+ self.bias[i] = self.bias[i] + 1
+ end
+ end
+ function nerv.ExampleP:read(pcdata)
+ self.matrix = nerv.MMatrixFloat.load(pcdata)
+ self.bias = nerv.MMatrixFloat.load(pcdata)
+ end
+ function nerv.ExampleP:write(pfhandle)
+ self.matrix:save(pfhandle)
+ self.bias:save(pfhandle)
+ end
+end
+global_conf = {}
+do
+ local f = nerv.ChunkFile('../tmp', 'w')
+ local exampleP1 = nerv.ExampleP('exampleP1', global_conf)
+ local exampleP2 = nerv.ExampleP('exampleP2', global_conf)
+ exampleP1:addOne()
+ exampleP1:addOne()
+ exampleP2:addOne()
+
+ f:write_chunk(exampleP1)
+ f:write_chunk(exampleP2)
+ f:close()
+end
+do
+ local f = nerv.ChunkFile('../tmp', 'r')
+ local exampleP1 = f:read_chunk('exampleP1', global_conf)
+ local exampleP2 = f:read_chunk('exampleP2', global_conf)
+ f:close()
+ print(exampleP1.matrix)
+ print(exampleP2.matrix)
+end
+```
+
+##Developer Notes##
+* There are four classes in to deal with chunk data, which are __nerv.ChunkFile__, __nerv.ChunkFileHandle__, __nerv.ChunkInfo__, __nerv.ChunkData__. Below is the underlying C structs.
```
typedef struct ChunkFileHandle {
FILE *fp;
} ChunkFileHandle;
-
typedef struct ChunkInfo {
off_t offset, length;
} ChunkInfo;
-
typedef struct ChunkData {
FILE *fp;
char *data;
} ChunkData;
```
-
-##Methods##
-* __ChunkFile ChunkFile.\_\_init(string mode, string fn)__
-`mode` can be `r` or `w`, for reading or writing a file.
-
-##Developer Notes##
-In __Nerv.io__, a returned(by `ChunkFile.__init`) __nerv.ChunkFile__ will have a member `handle`, which is a __nerv.ChunkFileHandle__. \ No newline at end of file
+* In __Nerv.io__, a returned(by `ChunkFile.__init`) __nerv.ChunkFile__ will have a member `handle`, which is a __nerv.ChunkFileHandle__. \ No newline at end of file