Skip to content

Commit 6929011

Browse files
mpsonntagmpsonntag
committed
[Matlab] Add basic nix.File documentation
1 parent d22fb4e commit 6929011

File tree

2 files changed

+271
-24
lines changed

2 files changed

+271
-24
lines changed

‎+nix/File.m‎

Lines changed: 259 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
1+
% nix.File class grants access to all NIX operations.
2+
%
3+
% A File represents a specific data source of a NIX back-end for example an NIX HDF5 file.
4+
% All entities of the nix data model (except the Value entity) must exist in the context
5+
% of an open File object. Therefore NIX entities cannot be initialized via their
6+
% constructors but only through the factory methods of their respective parent entity.
7+
%
8+
% When a file variable is cleared, the handle to the file will be automatically closed.
9+
%
10+
% nix.File properties:
11+
% blocks access to all nix.Block child entities.
12+
% sections access to all first level nix.Section child entities.
13+
%
14+
% See also nix.Block, nix.Section.
15+
%
16+
%
117
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
218
%
319
% All rights reserved.
@@ -7,38 +23,63 @@
723
% LICENSE file in the root of the Project.
824

925
classdef File < nix.Entity
10-
% File nix File object
1126

12-
properties(Hidden)
13-
% namespace reference for nix-mx functions
14-
alias = 'File'
27+
properties (Hidden)
28+
alias = 'File' % nix-mx namespace to access File specific nix backend functions.
1529
end
1630

1731
methods
1832
function obj = File(path, mode)
33+
% File constructor used to open or create a nix.File.
34+
%
35+
% path (char): path to a file to open or create.
36+
% mode (char): requires a valid nix.FileMode. Defaults to
37+
% nix.FileMode.ReadWrite if no FileMode is provided.
38+
%
39+
% Returns: (nix.File).
40+
%
41+
% See also nix.FileMode.
42+
1943
if (~exist('mode', 'var'))
20-
mode = nix.FileMode.ReadWrite; %default to ReadWrite
44+
mode = nix.FileMode.ReadWrite; % default to ReadWrite
2145
end
2246
h = nix_mx('File::open', path, mode);
2347
[email protected](h);
2448

25-
% assign relations
49+
% assign child entites
2650
nix.Dynamic.addGetChildEntities(obj, 'blocks', @nix.Block);
2751
nix.Dynamic.addGetChildEntities(obj, 'sections', @nix.Section);
2852
end
2953

3054
% braindead...
3155
function r = isOpen(obj)
56+
% Check if the file is currently open.
57+
%
58+
% Returns: (logical) True if the file is open, False otherwise.
59+
3260
fname = strcat(obj.alias, '::isOpen');
3361
r = nix_mx(fname, obj.nixhandle);
3462
end
3563

3664
function r = fileMode(obj)
65+
% Get the mode in which the file has been opened.
66+
%
67+
% Returns: (nix.FileMode).
68+
%
69+
% See also nix.FileMode.
70+
3771
fname = strcat(obj.alias, '::fileMode');
3872
r = nix_mx(fname, obj.nixhandle);
3973
end
4074

4175
function r = validate(obj)
76+
% Runs a backend validator over all contained entities and returns a
77+
% custom struct with warnings and error messages, if the current content
78+
% of the file violates the NIX datamodel as well as the ids of the
79+
% offending entities.
80+
%
81+
% Returns: (struct) Custom warning/error struct.
82+
4283
fname = strcat(obj.alias, '::validate');
4384
r = nix_mx(fname, obj.nixhandle);
4485
end
@@ -48,33 +89,120 @@
4889
% ----------------
4990

5091
function r = createBlock(obj, name, type)
92+
% Create a new nix.Block entity, that is immediately persisted to the file.
93+
%
94+
% name (char): the name of the Block, has to be unique within the file.
95+
% read only Block property.
96+
% type (char): the type of the Block, required.
97+
% Type can be used to give semantic meaning to an entity
98+
% and expose it to search methods in a broader context.
99+
% read/write Block property.
100+
%
101+
% Returns: (nix.Block) The newly created Block.
102+
%
103+
% Example: newBlock = f.createBlock('trial1', 'ephys');
104+
%
105+
% See also nix.Block.
106+
51107
fname = strcat(obj.alias, '::createBlock');
52108
h = nix_mx(fname, obj.nixhandle, name, type);
53109
r = nix.Utils.createEntity(h, @nix.Block);
54110
end
55111

56112
function r = blockCount(obj)
113+
% Get the number of Blocks in the file.
114+
%
115+
% Returns: (uint) The number of Blocks.
116+
%
117+
% Example: bc = f.blockCount();
118+
%
119+
% See also nix.Block.
120+
57121
r = nix.Utils.fetchEntityCount(obj, 'blockCount');
58122
end
59123

60124
function r = hasBlock(obj, idName)
125+
% Check if a Block exists in the file.
126+
%
127+
% idName (char): Name or ID of the Block.
128+
%
129+
% Returns: (logical) True if the Block exists, false otherwise.
130+
%
131+
% Example: check = f.hasBlock('23bb8a99-1812-4bc6-a52c-45e96864756b');
132+
% check = f.hasBlock('trial1');
133+
%
134+
% See also nix.Block.
135+
61136
r = nix.Utils.fetchHasEntity(obj, 'hasBlock', idName);
62137
end
63138

64139
function r = openBlock(obj, idName)
140+
% Retrieves an existing Block from the file.
141+
%
142+
% idName (char): Name or ID of the Block.
143+
%
144+
% Returns: (nix.Block) The nix.Block or an empty cell,
145+
% if the Block was not found.
146+
%
147+
% Example: getBlock = f.openBlock('23bb8a99-1812-4bc6-a52c-45e96864756b');
148+
% getBlock = f.openBlock('trial1');
149+
%
150+
% See also nix.Block.
151+
65152
r = nix.Utils.openEntity(obj, 'openBlock', idName, @nix.Block);
66153
end
67154

68155
function r = openBlockIdx(obj, index)
156+
% Retrieves an existing Block from the file, accessed by index.
157+
%
158+
% index (double): The index of the Block to read.
159+
%
160+
% Returns: (nix.Block) The Block at the given index.
161+
%
162+
% Example: getBlock = f.openBlockIdx(1);
163+
%
164+
% See also nix.Block.
165+
69166
idx = nix.Utils.handleIndex(index);
70167
r = nix.Utils.openEntity(obj, 'openBlockIdx', idx, @nix.Block);
71168
end
72169

73-
function r = deleteBlock(obj, del)
74-
r = nix.Utils.deleteEntity(obj, 'deleteBlock', del, 'nix.Block');
170+
function r = deleteBlock(obj, idNameEntity)
171+
% Deletes a Block from the file.
172+
%
173+
% When a Block is deleted, all its content (DataArray, Tags, Sources, etc)
174+
% will be deleted from the file as well.
175+
%
176+
% idNameEntity (char/nix.Block): Name or id of the entity to
177+
% be deleted or the entity itself.
178+
%
179+
% Returns: (logical) True if the Block has been removed, false otherwise.
180+
%
181+
% Example: check = f.deleteBlock('23bb8a99-1812-4bc6-a52c-45e96864756b');
182+
% check = f.deleteBlock('trial1');
183+
% check = f.deleteBlock(newBlock);
184+
%
185+
% See also nix.Block.
186+
187+
r = nix.Utils.deleteEntity(obj, 'deleteBlock', idNameEntity, 'nix.Block');
75188
end
76189

77190
function r = filterBlocks(obj, filter, val)
191+
% Get a filtered cell array of all Blocks within this file.
192+
%
193+
% filter (nix.Filter): the nix.Filter to be applied. Supports
194+
% the filters 'acceptall', 'id', 'ids',
195+
% 'name' and 'type'.
196+
% val (char): Value that is applied with the selected
197+
% filter.
198+
%
199+
% Returns: ([nix.Block]) A cell array of Blocks filtered according
200+
% to the applied nix.Filter.
201+
%
202+
% Example: getBlocks = f.filterBlocks(nix.Filter.type, 'ephys');
203+
%
204+
% See also nix.Block, nix.Filter.
205+
78206
r = nix.Utils.filter(obj, 'blocksFiltered', filter, val, @nix.Block);
79207
end
80208

@@ -83,43 +211,162 @@
83211
% ----------------
84212

85213
function r = createSection(obj, name, type)
214+
% Create a new nix.Section entity, that is immediately persisted to the file.
215+
%
216+
% name (char): the name of the Section, has to be unique within the file.
217+
% read only Section property.
218+
% type (char): the type of the Section, required.
219+
% Type can be used to give semantic meaning to an entity
220+
% and expose it to search methods in a broader context.
221+
% read/write Section property.
222+
%
223+
% Returns: (nix.Section) The newly created Section.
224+
%
225+
% Example: newSec = f.createSection('settings1', 'ephys');
226+
%
227+
% See also nix.Section.
228+
86229
fname = strcat(obj.alias, '::createSection');
87230
h = nix_mx(fname, obj.nixhandle, name, type);
88231
r = nix.Utils.createEntity(h, @nix.Section);
89232
end
90233

91234
function r = sectionCount(obj)
235+
% Get the number of root Sections in the file.
236+
%
237+
% Returns: (uint) The number of root (non nested) Sections.
238+
%
239+
% Example: sc = f.sectionCount();
240+
%
241+
% See also nix.Section.
242+
92243
r = nix.Utils.fetchEntityCount(obj, 'sectionCount');
93244
end
94245

95246
function r = hasSection(obj, idName)
247+
% Check if a Section exists as a direct child of the file.
248+
%
249+
% idName (char): Name or ID of the Section.
250+
%
251+
% Returns: (logical) True if the Section exists, false otherwise.
252+
%
253+
% Example: check = f.hasSection('23bb8a99-1812-4bc6-a52c-45e96864756b');
254+
% check = f.hasSection('settings1');
255+
%
256+
% See also nix.Section.
257+
96258
r = nix.Utils.fetchHasEntity(obj, 'hasSection', idName);
97259
end
98260

99261
function r = openSection(obj, idName)
262+
% Retrieves an existing Section from the file.
263+
%
264+
% idName (char): Name or ID of the Section.
265+
%
266+
% Returns: (nix.Section) The nix.Section or an empty cell,
267+
% if the Section was not found.
268+
%
269+
% Example: getSec = f.openSection('23bb8a99-1812-4bc6-a52c-45e96864756b');
270+
% getSec = f.openSection('settings1');
271+
%
272+
% See also nix.Section.
273+
100274
r = nix.Utils.openEntity(obj, 'openSection', idName, @nix.Section);
101275
end
102276

103277
function r = openSectionIdx(obj, index)
278+
% Retrieves an existing Section from the file, accessed by index.
279+
%
280+
% index (double): The index of the Section to read.
281+
%
282+
% Returns: (nix.Section) The Section at the given index.
283+
%
284+
% Example: getSec = f.openSectionIdx(1);
285+
%
286+
% See also nix.Section.
287+
104288
idx = nix.Utils.handleIndex(index);
105289
r = nix.Utils.openEntity(obj, 'openSectionIdx', idx, @nix.Section);
106290
end
107291

108-
function r = deleteSection(obj, del)
109-
r = nix.Utils.deleteEntity(obj, 'deleteSection', del, 'nix.Section');
292+
function r = deleteSection(obj, idNameEntity)
293+
% Deletes a Section from the file.
294+
%
295+
% When a Section is deleted, all of its child Sections, Properties and
296+
% Values will be deleted from the file as well.
297+
%
298+
% idNameEntity (char/nix.Section): Name or id of the entity to
299+
% be deleted or the entity itself.
300+
%
301+
% Returns: (logical) True if the Section has been removed, false otherwise.
302+
%
303+
% Example: check = f.deleteSection('23bb8a99-1812-4bc6-a52c-45e96864756b');
304+
% check = f.deleteSection('settings1');
305+
% check = f.deleteSection(newSec);
306+
%
307+
% See also nix.Section.
308+
309+
r = nix.Utils.deleteEntity(obj, 'deleteSection', idNameEntity, 'nix.Section');
110310
end
111311

112312
function r = filterSections(obj, filter, val)
313+
% Get a filtered cell array of all root Sections within this file.
314+
%
315+
% filter (nix.Filter): the nix.Filter to be applied. Supports
316+
% the filters 'acceptall', 'id', 'ids',
317+
% 'name' and 'type'.
318+
% val (char): Value that is applied with the selected
319+
% filter.
320+
%
321+
% Returns: ([nix.Section]) A cell array of Sections filtered according
322+
% to the applied nix.Filter.
323+
%
324+
% Example: getSecs = f.filterSections(nix.Filter.type, 'ephys');
325+
%
326+
% See also nix.Section, nix.Filter.
327+
113328
r = nix.Utils.filter(obj, 'sectionsFiltered', filter, val, @nix.Section);
114329
end
115330

116-
% maxdepth is an index
117331
function r = findSections(obj, maxDepth)
332+
% Get all Sections and their child Sections in this file recursively.
333+
%
334+
% This method traverses the trees of all Sections in the file and adds all
335+
% Sections to the resulting cell array, until the maximum depth of the nested
336+
% Sections has been reached. The traversal is accomplished via breadth first
337+
% and adds the Sections accordingly.
338+
%
339+
% maxDepth (double): The maximum depth of traversal to retrieve nested
340+
% Sections. Should be handled like an index.
341+
%
342+
% Example: allSec = f.findSections(2);
343+
% % will add all Sections until including the 2nd layer of Sections.
344+
%
345+
% See also nix.Section.
346+
118347
r = obj.filterFindSections(maxDepth, nix.Filter.acceptall, '');
119348
end
120349

121-
% maxdepth is an index
122350
function r = filterFindSections(obj, maxDepth, filter, val)
351+
% Get all Sections in this file recursively.
352+
%
353+
% This method traverses the trees of all Sections in the file. The traversal
354+
% is accomplished via breadth first and can be limited in depth. On each
355+
% node or Section a nix.Filter is applied. If the filter returns true, the
356+
% respective Section will be added to the result list.
357+
%
358+
% maxDepth (double): The maximum depth of traversal to retrieve nested
359+
% Sections. Should be handled like an index.
360+
% filter (nix.Filter): the nix.Filter to be applied. Supports
361+
% the filters 'acceptall', 'id', 'ids',
362+
% 'name' and 'type'.
363+
% val (char): Value that is applied with the selected
364+
% filter.
365+
%
366+
% Example: allSec = f.filterFindSections(2, nix.Filter.type, 'ephys');
367+
%
368+
% See also nix.Section, nix.Filter.
369+
123370
r = nix.Utils.find(obj, 'findSections', maxDepth, filter, val, @nix.Section);
124371
end
125372
end

0 commit comments

Comments
 (0)