.. _auto_file_read:

*READ FILE LINES*
=================

Reads a contiguous range of lines from a file attachment using memory-safe streaming (fopen/fgets), returning the content with padded line-number prefixes. Accepts a numeric attachment ID, a file path, or an attachment name. Use this worker when you need to inspect or pass a specific slice of a large text file without loading it entirely into memory.

When to use
-----------

Tagged: ``attachment``, ``file``, ``file_read``, ``large_file``, ``line_range``, ``streaming``, ``text``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - File
     - file
     - file
     - —
     - ✓
     - The file to read — supply a numeric attachment ID, an absolute/relative file path, or an attachment name; this field is required.
   * - Start Line
     - start_line
     - number
     - 1
     - 
     - 1-based line number at which reading begins; defaults to 1 (first line of the file).
   * - End Line
     - end_line
     - number
     - —
     - 
     - 1-based line number at which reading stops (inclusive); leave blank to read until max_lines or end-of-file.
   * - Max Lines
     - max_lines
     - number
     - 500
     - 
     - Hard cap on the number of lines returned to prevent context overflow; defaults to 500 — increase only when a larger slice is explicitly needed.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Content
     - content
     - text
     - The extracted lines as a single newline-delimited string, each prefixed with a right-aligned 6-character line number and a pipe separator (e.g., '     7/line text').
   * - Total Lines
     - total_lines
     - number
     - Total number of lines in the file (counted by streaming the remainder after the requested range), regardless of how many were returned.
   * - Lines Read
     - lines_read
     - number
     - Actual number of lines collected and included in content — may be less than the requested range when max_lines or end-of-file is reached first.
   * - Start Line Actual
     - start_line_actual
     - number
     - The 1-based line number where reading actually began (reflects any clamping of the start_line input to a minimum of 1).
   * - End Line Actual
     - end_line_actual
     - number
     - The 1-based line number of the last line included in content.
   * - Status
     - status
     - string
     - Human-readable result message, e.g. 'Success: Read 42 lines from myfile.txt (total: 1200 lines)'; non-empty on success, replaced by an error message on failure.

Disciplines
-----------

- data.io.file

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>file_read</code>. Schema hash: <code>d1bbe85155af</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>