.. _file: .. note:: Python provides native support for manipulating files. Use that whenever possible to ensure your code is understandable by the greatest number of people. File Access (objected-oriented via NEURON) ------------------------------------------ .. class:: File Syntax: ``fobj = h.File()`` ``fobj = h.File("filename")`` Description: This class allows you to open several files at once, whereas the top level functions, :func:`ropen` and :func:`wopen` , allow you to deal only with one file at a time. The functionality of :func:`xopen` is not implemented in this class so use .. code-block:: python h.xopen(fobj.getname()) to execute a sequence of interpreter commands in a file. Example: .. code-block:: python from neuron import h f1 = h.File() //state that f1, f2, and f3 are pointers to the File class f2 = h.File() f3 = h.File() f1.ropen("file1") //open file1 for reading f2.wopen("file2") //open file2 for writing f3.aopen("file3") //open file3 for appending to the end of the file opens file1, file2, and file3 for reading, writing, and appending (respectively). .. warning:: The mswindows/dos version must deal with the difference between binary and text mode files. The difference is transparent to the user except for one limitation. If you mix text and binary data and you write text first to the file, then you need to do a File.seek(0) to explicitly switch to binary mode just after opening the file and prior to the first File.printf. An error message will occur if you read/write text to a file in text mode and then try to read/write a binary vector. This issue does not arise with the unix version. .. seealso:: :ref:`printf_doc`, :func:`ropen`, :func:`xopen`, :func:`wopen` ---- .. method:: File.ropen Syntax: ``.ropen()`` ``.ropen("name")`` Description: Open the file for reading. If the argument is not present it opens (for reading) the last specified file. ---- .. method:: File.wopen Syntax: ``.wopen()`` ``.wopen("name")`` Description: Open the file for writing. If the argument is not present it opens the last specified file. ---- .. method:: File.aopen Syntax: ``.aopen()`` ``.aopen("name")`` Description: Open the file for appending to the end of the file. If the argument is not present it opens the last specified file. ---- .. method:: File.xopen Syntax: ``.xopen()`` ``.xopen("name")`` Description: Open the file and execute it. (**not implemented**) Note: if instead of a "*name*", the number 0,1,or 2 is specified then the stdin, stdout, or stderr is opened. (**not implemented**) ---- .. method:: File.close Syntax: ``.close()`` Description: Flush and close the file. This occurs automatically whenever opening another file or destroying the object. ---- .. method:: File.mktemp Syntax: ``success = f.mktemp()`` Description: Sets the name to a temporary filename in the /tmp directory (or other writable path for mswin and mac). Success returns 1. Example of creating a temporary file: .. code-block:: python f = h.File() if f.mktemp() != 1: raise Exception('Unable to create temporary file') # create a tempoary file, get its name temp_file_name = f.getname() # do stuff, possibly using regular Python File IO instead # dispose of the temporary file f.unlink() ---- .. method:: File.unlink Syntax: ``success = f.unlink()`` Description: Remove the file specified by the current name. A return value of 1 means the file was removed (or at least it's link count was reduced by one and the filename no longer exists). ---- .. method:: File.printf Syntax: ``.printf("format", args, ...)`` Description: As in standard C \ ``printf`` and the normal NEURON :func:`printf` . ---- .. method:: File.scanvar Syntax: ``.scanvar()`` Description: Reads the next number as in the function ``fscan()`` and returns its value. Note: in order that .eof will return true after the last number, the last digit of that number should either be the last character in the file or be followed by a newline which is the last character in the file. ---- .. method:: File.scanstr Syntax: ``.scanstr(strptr)`` Description: Read the next string (delimited by whitespace) into \ ``strptr`` (must be a pointer to a NEURON string *not* a Python string). Returns the length of a string (if failure then returns -1 and the string pointed to by ``strptr`` is unchanged). ---- .. method:: File.gets Syntax: ``.gets(_ref_str)`` Description: Read up to and including end of line. Returns length of string. If at the end of file, returns -1 and does not change the argument. ``_ref_str`` is a reference to a NEURON string (e.g. one created via ``_ref_str = h.ref('')``); it is not a Python string. ---- .. method:: File.getname Syntax: ``name = fobj.getname()`` ``name = fobj.getname(strptr)`` Description: Return the name of the last specified file as a string. For backward compatibility, if the arg is present (must a pointer to a NEURON string) also copy it to that. ---- .. method:: File.dir Syntax: ``dirname = file.dir()`` Description: Return the pathname of the last directory moved to in the chooser. If the :meth:`File.chooser` has not been created, return the empty string. ---- .. method:: File.eof Syntax: ``fobj.eof()`` Description: Return true if at end of ropen'd file. ---- .. method:: File.flush Syntax: ``fobj.flush()`` Description: Flush pending output to the file. ---- .. method:: File.isopen Syntax: ``fobj.isopen()`` Description: Return true if a file is open. ---- .. method:: File.chooser Syntax: ``.chooser()`` ``.chooser("w,r,a,x,d or nothing")`` ``.chooser("w,r,a,x,d or nothing", "Banner", "filter", "accept", "cancel", "path")`` Description: File chooser interface for writing , reading, appending, or just specifying a directory or filename without opening. The banner is optional. The filter, eg. \ ``"*.dat"`` specifies the files shown in the browser part of the chooser. The "path" arg specifies the file or directory to use when the browser first pops up. The form with args sets the style of the chooser but does not pop it up. With no args, the browser pops up and can be called several times. Each time starting where it left off previously. The "d" style is used for selecting a directory (in contrast to a file). With the "d" style, three buttons are placed beneath the browser area with :guilabel:`Open` centered beneath the :guilabel:`Show`, :guilabel:`Cancel` button pair. The :guilabel:`Open` button must be pressed for the dialog to return the name of the directory. The :guilabel:`Show` button merely selects the highlighted browser entry and shows the relevant directory contents. A returned directory string always has a final "/". The "*x*" style is unimplemented. Use .. code-block:: none f.chooser("", "Execute a hoc file", "*.hoc", "Execute") if f.chooser(): h.xopen(f.getname()) Example: .. code-block:: python from neuron import h, gui f = h.File() f.chooser('', 'Example file browser', '*', 'Type file name', 'Cancel') while f.chooser(): print(f.getname()) .. image:: ../../images/filechooser.png :align: center ---- The following comes courtesy of Zach Mainen, ``zach@helmholtz.sdsc.edu``: ---- .. method:: File.vwrite Syntax: ``.vwrite(_ref_x)`` ``.vwrite(n, _ref_x)`` Description: Write binary doubles to a file from an array or variable using \ ``fwrite()``. The form with two arguments specifies the number of elements to write and the address from which to begin writing. With one argument, *n* is assumed to be 1. Must be careful that *x*\ [] has at least *n* elements after its passed address. i.e. If ``x = h.Vector(10)`` and ``f`` is an instance of a :class:`File` opened for writing, then one might call ``f.vwrite(5, x._ref_x[0]`` to write the first five values to a file.) ---- .. method:: File.vread Syntax: ``.vread(_ref_x)`` ``.vread(n, _ref_x)`` Description: Read binary doubles from a file into a pre-existing :class:`Vector` or variable using \ ``fread()``. .. seealso:: :func:`vwrite` ---- .. method:: File.seek Syntax: ``.seek()`` ``.seek(offset)`` ``.seek(offset,origin)`` Description: Set the file position. Any subsequent file access will access data beginning at the new position. Without arguments, goes to the beginning of file. Offset is in characters and is measured from the beginning of the file unless origin is 1 (measures from the current position) or 2 (from the end of the file). Returns 0 if successful, non-zero on error. Used with :meth:`tell`. ---- .. method:: File.tell Syntax: ``.tell()`` Description: Return the current file position or -1 on error. Used with :meth:`seek`.