File-Loader Plugins
===================

What File Loaders Do
--------------------

File-loader plugins convert external data files into a two-dimensional table
that PhysPlot can display. A loader receives a file path and returns a
rectangular data array.

Where Loaders Appear in the UI
------------------------------

Discovered loaders are shown in two places:

- **Settings > File Loader** (menu selection)
- **Data Loader** dropdown above the **Import Data** button (quick selection)

The selected loader is used when importing files. PhysPlot discovers loader
files at startup.

Layman Example
--------------

If your instrument saves data in a special format, a loader teaches PhysPlot how
to skip the header text and keep only the useful numeric columns. For example,
the OES HRF loader skips metadata and returns wavelength and intensity columns.

Required File Location
----------------------

Put new file-loader files in:

.. code-block:: text

   fileloader/

Use a clear filename:

.. code-block:: text

   fileloader/my_instrument_loader.py

Required Structure
------------------

Every loader should define:

``title``
   Text shown in the Data Loader dropdown.

``load_data(file_path)``
   Function that receives a file path and returns a two-dimensional table-like
   object.

Optional:

``DEFAULT_COLUMN_ROLES``
   A list of default role labels such as ``["X-axis", "Y-axis"]``. PhysPlot
   applies these roles automatically after import.

Minimal CSV-Like Template
-------------------------

.. code-block:: python

   """Loader for a custom instrument text file."""

   from pathlib import Path
   import numpy as np

   title = "My Instrument Loader"
   DEFAULT_COLUMN_ROLES = ["X-axis", "Y-axis"]


   def load_data(file_path):
       """load_data(file_path) -> numpy.ndarray

       Load two numeric columns from a custom instrument file.

       Parameters:
           file_path (str | pathlib.Path): Path selected in the import dialog.

       Returns:
           numpy.ndarray: Two-column array ready for the PhysPlot table.
       """
       rows = []
       for line in Path(file_path).read_text().splitlines():
           if line.startswith("#"):
               continue
           parts = line.split(",")
           if len(parts) < 2:
               continue
           rows.append((float(parts[0]), float(parts[1])))
        return np.asarray(rows, dtype=float)

Step-by-Step: Build a New Loader
--------------------------------

1. Create a new file in ``fileloader/`` (for example
   ``fileloader/my_device_loader.py``).
2. Define a human-readable ``title`` string.
3. Implement ``load_data(file_path)`` to parse your format and return a 2D
   array-like result.
4. Optionally define ``DEFAULT_COLUMN_ROLES`` to pre-assign column roles after
   import.
5. Restart PhysPlot so the loader is discovered and added to the menu and
   dropdown.
6. Select your loader from **Settings > File Loader** or the **Data Loader**
   dropdown, then import a file.

Loader Categories
-----------------

- **General tabular loader**: parse delimited numeric files.
- **Instrument-specific loader**: skip custom headers/metadata and keep
  meaningful columns.
- **Role-aware loader**: also sets ``DEFAULT_COLUMN_ROLES`` for automatic
  X/Y mapping.

OES HRF Pattern
---------------

The OES HRF loader demonstrates a common pattern:

1. Read the whole file as text.
2. Ignore metadata until a marker line.
3. Parse numeric rows.
4. Drop unnecessary index columns.
5. Return only the columns PhysPlot should show.

Practical Rules
---------------

- Always return a rectangular two-dimensional array.
- Convert values to floats when possible.
- Raise a helpful ``ValueError`` if the file contains no usable rows.
- Use ``DEFAULT_COLUMN_ROLES`` when a loader knows which columns are X and Y.
- Keep loader code independent from the GUI. Do not modify the table directly.

Existing Examples
-----------------

See:

- ``fileloader/default_loader.py``
- ``fileloader/oes_hrf_loader.py``