int Ni_ReadStream( Ni_node restrict n, FILE * restrict stream, int fold_case );
Reads a FILE* stream in .ini format, turning it into a tree for Nickel to manipulate.
n (in) should be the Ni_node to use as the root when reading. It need not actually be the real root of a tree. This allows you to treat entire files as children of an existing node.
stream (in) should point to a FILE* stream which can be read for .ini data. The stream (obviously) must be readable, but it need not be seekable. See the C standard library for how FILEs work.
fold_case (in) should be whether you want tolower() called on every node's name. Nonzero means call tolower() to lowercase all names, 0 means leave names exactly as they are in the file.
Returns nonzero on success, or 0 if it fails.
Also returns 0 if you pass NULL for n (or stream).
Any nodes in the tree or subtree with n as its root that are specified in the stream's contents are overwritten with the values from the stream. Any nodes that weren't already in the tree are created. That is, the existing tree starting with n is left alone, except where overwritten by the stream. Note that all thusly created or overwritten nodes are put in the "modified" state. See Ni_GetModified() for an explanation of the "modified" state.
The most useful way to call this function is with n as the root of a new tree, fresh from a Ni_New() call. This gives you a tree with the exact contents of the stream. You can also pass n as the root of an existing tree. In this case, you'll get a mishmash of preexisting and overridden values (which can be useful if you're careful about the nodes' "modified" states [see Ni_GetModified() and Ni_SetModified()]). You can also use a non-root node in an existing tree. In this case, you simply get the entire contents of the stream as a child of that node, which can be useful for separating out files, but keeping them in the same tree (I guess).
If fold_case is nonzero, all chars in all node names are run over with tolower(), which uses the current locale information for how the conversion happens. Regardless, it translates byte by byte, improperly handling even UTF-8 data. For this reason, I recommend you never set the fold_case flag to nonzero. It's provided only for convenience for lazy people who still rely on ASCII data. Unfortunately, there's no Unicode-friendly alternative (yet) so for now just be careful about how you specify case in your .ini files.
If this function fails, it probably means either you're out of memory or there was an i/o error reading from the given stream (note that as invalid .ini data is mostly ignored by the parser, an i/o error here means a disk error, not a parse error). In either case, the contents of the entire tree or subtree with n as its root are undefined (somewhat unfortunately).
See the file format page for the particular syntax of .ini file this function can parse.
See also Ni_ReadFile().