CLASS ndi.document
NDI.DOCUMENT - NDI_database storage item, general purpose data and parameter storage
The ndi.document datatype for storing results in the ndi.database
Superclasses
none
Properties
Property | Description |
---|---|
document_properties | a struct with the fields for the document |
Methods
Method | Description |
---|---|
add_dependency_value_n | add a dependency to a named list |
add_file | add a file to a ndi.document |
current_file_list | return the list of files that have been associated with an ndi.document |
dependency | return names and a structure with all dependencies for an ndi.object |
dependency_value | return dependency value given dependency name |
dependency_value_n | return dependency values from list given dependency name |
doc_class | DOC_CLASS what is the document class type of an ndi.document object? |
doc_isa | is an ndi.document a member of a particular document_class? |
doc_superclass | return the document superclasses of an ndi.document object |
doc_unique_id | return the document unique identifier for an ndi.document |
document | create a new ndi.database object |
eq | are two ndi.document objects equal? |
id | return the document unique identifier for an ndi.document |
is_in_file_list | is a file name in a ndi.document's file list? |
plus | merge two ndi.document objects |
readblankdefinition | read a blank JSON class definitions from a file location string |
readjsonfilelocation | return the text from a json file location string in NDI |
readjsonfilelocation_orig | return the text from a json file location string in NDI |
remove_dependency_value_n | remove a dependency from a named list |
remove_file | remove file information from a did.document |
reset_file_info | reset the file information parameters for a new did.document |
set_dependency_value | set the value of a dependency field |
set_session_id | set the session id for an ndi.document object |
setproperties | Set property values of an ndi.document object |
validate | 0/1 evaluate whether ndi.document object is valid by its schema |
Methods help
add_dependency_value_n - add a dependency to a named list
NDI_DOCUMENT_OBJ = ADD_DEPENDENCY_VALUE_N(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, VALUE, ...)
Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
and adds a dependency name 'dependency_name_(n+1)', where n is the number of entries with
the form 'depenency_name_i' that exist presently. If there is no dependency field with that, then
an entry is added and i is 1.
This function accepts name/value pairs that alter its default behavior:
Parameter (default) | Description
-----------------------------------------------------------------
ErrorIfNotFound (1) | If 1, generate an error if the entry is
| not found. Otherwise, generate no error but take no action.
add_file - add a file to a ndi.document
DID_DOCUMENT_OBJ = ADD_FILE(NDI_DOCUMENT_OBJ, NAME, LOCATION, ...)
Adds a file's information to a ndi.document, for later ingestion into
the database. NAME is the name of the file record for the document.
LOCATION is a string that identifies the file or URL location on the
internet.
Note: NAME must not include any file separator characters on any
platform (':','\','/') and may not have leading or trailing spaces.
Leading or trailing spaces will be trimmed.
This function accepts name/value pairs that alter its default behavior:
Parameter (default) | Description
-----------------------------------------------------------------
ingest (1 or 0) | 0/1 Should the file be copied into the local
| database by ndi.database.add_doc() ?
| If LOCATION does not begin with 'http://' or
| 'https://', then ingest is 1 by default.
| If LOCATION begins with 'http(s)://', then
| ingest is 0 by default. Note that the file
| is only copied upon the later call to
| ndi.database.add_doc(), not at the call to
| ndi.document.add_file().
delete_original (1 or 0) | 0/1 Should we delete the file after ingestion?
| If LOCATION does not begin with 'http://' or
| 'https://', then delete_original is 1 by default.
| If LOCATION begins with 'http(s)://', then
| delete_original is 0 by default. Note that the
| file is only deleted upon the later call to
| ndi.database.add_doc(), not at the call to
| ndi.document.add_file().
location_type ('file' or | Can be 'file' or 'url'. By default, it is set
'url') | to 'file' if LOCATION does not begin with
| 'http://' or 'https://', and 'url' otherwise.
current_file_list - return the list of files that have been associated with an ndi.document
FL = CURRENT_FILE_LIST(NDI_DOCUMENT_OBJ)
Return a cell array of file names that are associated with an ndi.document object.
This list will be a subset of all files possible to add to the document in
ndi_document_obj.document_properties.file.file_list, and only includes files that have actually
been added in {ndi_document_obj.document_properties.file.file_info.name}.
dependency - return names and a structure with all dependencies for an ndi.object
[NAMES, DEPEND_STRUCT] = DEPENDENCY(NDI_DOCUMENT_OBJ)
Returns in the cell array NAMES the 'name' of all 'depends_on' entries in the ndi.document NDI_DOCUMENT_OBJ.
Further, this function returns a structure with all 'name' and 'value' entries in DEPEND_STRUCT.
dependency_value - return dependency value given dependency name
D = DEPENDENCY_VALUE(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, ...)
Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
and returns the 'value' associated with the given 'name'. If there is no such
field (either 'depends_on' or 'name'), then D is empty and an error is generated.
This function accepts name/value pairs that alter its default behavior:
Parameter (default) | Description
-----------------------------------------------------------------
ErrorIfNotFound (1) | If 1, generate an error if the entry is
| not found. Otherwise, return empty.
dependency_value_n - return dependency values from list given dependency name
D = DEPENDENCY_VALUE_N(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, ...)
Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
and returns the 'values' associated with the given 'name_i', where i varies from 1 to the
maximum number of entries titled 'name_i'. If there is no such field (either
'depends_on' or 'name_i'), then D is empty and an error is generated.
This function accepts name/value pairs that alter its default behavior:
Parameter (default) | Description
-----------------------------------------------------------------
ErrorIfNotFound (1) | If 1, generate an error if the entry is
| not found. Otherwise, return empty.
doc_class - DOC_CLASS what is the document class type of an ndi.document object?
C = DOC_CLASS(NDI_DOCUMENT_OBJ)
Returns the document class of an ndi.document.
(Found at ndi_document_obj.document_properties.document_class.class_name)
doc_isa - is an ndi.document a member of a particular document_class?
B = DOC_ISA(NDI_DOCUMENT_OBJ, DOCUMENT_CLASS)
Returns 1 if NDI_DOCUMENT_OBJ or one of its superclasses is a match
for DOCUMENT_CLASS. Otherwise returns 0.
doc_superclass - return the document superclasses of an ndi.document object
SC = DOC_SUPERCLASS(NDI_DOCUMENT_OBJ)
Returns the document superclasses of an ndi.document object. SC is a cell
array of strings.
doc_unique_id - return the document unique identifier for an ndi.document
UID = DOC_UNIQUE_ID(NDI_DOCUMENT_OBJ)
Returns the unique id of an ndi.document
(Found at NDI_DOCUMENT_OBJ.documentproperties.base.id)
document - create a new ndi.database object
NDI_DOCUMENT_OBJ = ndi.document(DOCUMENT_TYPE, 'PARAM1', VALUE1, ...)
or
NDI_DOCUMENT_OBJ = ndi.document(MATLAB_STRUCT)
Documentation for ndi.document/document
doc ndi.document
eq - are two ndi.document objects equal?
B = EQ(NDI_DOCUMENT_OBJ1, NDI_DOCUMENT_OBJ2)
Returns 1 if and only if the objects have identical document_properties.base.id
fields.
id - return the document unique identifier for an ndi.document
UID = ID (NDI_DOCUMENT_OBJ)
Returns the unique id of an ndi.document
(Found at NDI_DOCUMENT_OBJ.documentproperties.base.id)
is_in_file_list - is a file name in a ndi.document's file list?
[B, MSG, FI_INDEX] = IS_IN_FILE_LIST(NDI_DOCUMENT_OBJ, NAME)
Is the file NAME a valid named binary file for the ndi.document
NDI_DOCUMENT_OBJ? If so, B is 1; else, B is 0.
A name is a valid name if it appears in NDI_DOCUMENT_OBJ....
document_properties.files.file_list or if it is a numbered
file with an entry in document_properties.files.file_list
as 'filename.ext_#'. (For example, 'filename.ext_1' would
be valid if 'filename.ext_# is in the file_list.)
If the file NAME is not valid, a reason is returned in MSG.
If it is a valid file NAME, then the index value of NAME
in NDI_DOCUMENT_OBJ.DOCUMENT_PROPERTIES.FILES.FILE_INFO is also
returned.
plus - merge two ndi.document objects
NDI_DOCUMENT_OBJ_OUT = PLUS(NDI_DOCUMENT_OBJ_A, NDI_DOCUMENT_OBJ_B)
Merges the ndi.document objects A and B. First, the 'document_class'
superclasses are merged. Then, the fields that are in B but are not in A
are added to A. The result is returned in NDI_DOCUMENT_OBJ_OUT.
Note that any fields that A has that are also in B will be preserved; no elements of
those fields of B will be combined with A.
readblankdefinition - read a blank JSON class definitions from a file location string
S = READBLANKDEFINITION(JSONFILELOCATIONSTRING)
Given a JSONFILELOCATIONSTRING, this function creates a blank document using the JSON definitions.
A JSONFILELOCATIONSTRING can be:
a) a url
b) a filename (full path)
c) a filename referenced with respect to $NDIDOCUMENTPATH
See also: READJSONFILELOCATION
readjsonfilelocation - return the text from a json file location string in NDI
T = READJSONFILELOCATION(JSONFILELOCATIONSTRING)
A JSONFILELOCATIONSTRING can be:
a) a url
b) a filename (full path)
c) a filename (full path) but referenced with respect to $NDIDOCUMENTPATH or $NDICALCDOCUMENTPATH
d) a filename without any path that sits beneath $NDIDOCUMENTPATH or $NDICALCDOCUMENTPATH
e) a relative path beneath $NDIDOCUMENTPATH (e.g., daq/ndi_document_filenavigator.json)
readjsonfilelocation_orig - return the text from a json file location string in NDI
T = READJSONFILELOCATION(JSONFILELOCATIONSTRING)
A JSONFILELOCATIONSTRING can be:
a) a url
b) a filename (full path)
c) a relative filename with respect to $NDIDOCUMENTPATH
d) a filename referenced with respect to $NDIDOCUMENTPATH
remove_dependency_value_n - remove a dependency from a named list
NDI_DOCUMENT_OBJ = REMOVE_DEPENDENCY_VALUE_N(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, VALUE, N, ...)
Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
and removes the dependency name 'dependency_name_(n)'.
This function accepts name/value pairs that alter its default behavior:
Parameter (default) | Description
-----------------------------------------------------------------
ErrorIfNotFound (1) | If 1, generate an error if the entry is
| not found. Otherwise, generate no error but take no action.
remove_file - remove file information from a did.document
DID_DOCUMENT_OBJ = REMOVE_FILE(NDI_DOCUMENT_OBJ, NAME, [LOCATION], ...)
Removes the file information for a name or a name and location
combination from a did.document() object.
If LOCATION is not specified or is empty, then all locations are removed.
If NDI_DOCUMENT_OBJ does not have a file NAME in its file_list, then an erorr is
generated.
This function accepts name/value pairs that alter its default behavior:
Parameter (default) | Description
-----------------------------------------------------------------
ErrorIfNoFileInfo (0) | 0/1 If a name is specified and the
| file info is already empty, should we
| produce an error?
reset_file_info - reset the file information parameters for a new did.document
NDI_DOCUMENT_OBJ = RESET_FILE_INFO(NDI_DOCUMENT_OBJ)
Reset (make empty) all file info structures for a new did.document object.
Sets document_properties.files.file_info to an empty structure
set_dependency_value - set the value of a dependency field
NDI_DOCUMENT_OBJ = SET_DEPENDENCY_VALUE(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, VALUE, ...)
Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
and, if there is a dependency with a given 'dependency_name', then the value of the
dependency is set to DEPENDENCY_VALUE.
This function accepts name/value pairs that alter its default behavior:
Parameter (default) | Description
-----------------------------------------------------------------
ErrorIfNotFound (1) | If 1, generate an error if the entry is
| not found. Otherwise, add it.
set_session_id - set the session id for an ndi.document object
NDI_DOCUMENT_OBJ = SET_SESSION_ID(NDI_DOCUMENT_OBJ, SESSION_ID)
Sets the document_properties.base.session_id field to the value indicated.
setproperties - Set property values of an ndi.document object
NDI_DOCUMENT_OBJ = SETPROPERTIES(NDI_DOCUMENT_OBJ, 'PROPERTY1', VALUE1, ...)
Sets the property values of NDI_DOCUMENT_OBJ. PROPERTY values should be expressed
relative to NDI_DOCUMENT_OBJ.document_properties (see example).
See also: ndi.document, ndi.document/ndi.document
Example:
mydoc = mydoc.setproperties('base.name','mydoc name');
validate - 0/1 evaluate whether ndi.document object is valid by its schema
B = VALIDATE(NDI_DOCUMENT_OBJ)
Checks the fields of the ndi.document object against the schema in
NDI_DOCUMENT_OBJ.ndi_core_properties.validation_schema and returns 1
if the object is valid and 0 otherwise.