read_file

The read_file tool is used to inspect file contents in your project. It allows VJSP to understand code, configuration files, and documentation to provide better assistance.

Parameters

This tool accepts the following parameters:

• path (required): The file path to read, relative to the current working directory
• start_line (optional): The line number to start reading from (1-indexed)
• end_line (optional): The line number to end reading at (1-indexed, inclusive)
• auto_truncate (optional): Whether to automatically truncate large files when no line range is specified (true/false)

What It Does

This tool reads the content of a specified file and returns the content with line numbers for easy referencing. It can read entire files or specific portions, and can even extract text from PDF and Word documents.

When to Use?

• When VJSP needs to understand existing code structure
• When VJSP needs to analyze configuration files
• When VJSP needs to extract information from text files
• When VJSP needs to view code before suggesting changes
• When you need to reference specific line numbers in discussions

Key Features

• Displays file content with line numbers for easy referencing
• Can read specific portions of a file by specifying line ranges
• Extracts readable text from PDF and DOCX files
• Intelligently truncates large files to focus on the most relevant parts
• Provides method definition summaries with line ranges for large code files
• Efficiently streams only the requested line ranges for better performance
• Easily discuss specific parts of code through line numbering

Limitations

• May not efficiently handle very large files without using line range parameters
• For binary files (except PDF and DOCX), may return unreadable content

How It Works

When the read_file tool is called, it follows this process:

1. Parameter Validation: Validates the required path parameter and optional parameters
2. Path Resolution: Resolves relative paths to absolute paths
3. Reading Strategy Selection:
   • The tool uses a strict priority hierarchy (detailed below)
   • It chooses between range reading, auto-truncation, or full file reading
4. Content Processing:
   • Adds line numbers to the content (e.g., "1 | const x = 13"), where 1 | is the line number
   • For truncated files, adds truncation notification and method definitions
   • For special formats (PDF, DOCX, IPYNB), extracts readable text

Reading Strategy Priority

The tool uses a clear decision hierarchy to determine how to read a file:

1. First Priority: Explicit Line Range

• If either start_line or end_line is provided, the tool always performs a range read
• The implementation efficiently streams only the requested lines, making it suitable for handling large files
• This takes priority over all other options

2. Second Priority: Auto-Truncation for Large Files

This only applies when all of the following conditions are met:

• Neither start_line nor end_line is specified
• The auto_truncate parameter is set to true
• The file is not a binary file
• The file exceeds the configured line threshold (typically 500-1000 lines)

When auto-truncation is enabled, the tool will:

• Only read the first portion of the file (determined by the maxReadFileLine setting)
• Add a truncation notification showing displayed lines versus total lines
• Provide a summary of method definitions with line ranges

3. Default Behavior: Read Entire File

• If none of the above conditions are met, it will read the entire file content
• For special formats like PDF, DOCX, and IPYNB, it uses specialized extractors

Usage Examples

Here are several scenarios demonstrating how the read_file tool is used and the typical outputs you might receive.

Reading an Entire File

To read the complete content of a file:

Input:

<read_file>
<path>src/app.js</path>
</read_file>

Simulated Output (for a small file like example_small.txt):

1 | This is the first line.
2 | This is the second line.
3 | This is the third line.

(Output will vary based on actual file content)

Reading Specific Lines

To read only a specific line range (e.g., 46-68):

Input:

<read_file>
<path>src/app.js</path>
<start_line>46</start_line>
<end_line>68</end_line>
</read_file>

Simulated Output (for lines 2-3 of example_five_lines.txt):

2 | Content of the second line.
3 | Content of the third line.

(Output shows only the requested lines with their original line numbers)

Reading a Large File (Auto-Truncate)

When reading a large file without specifying lines and with auto_truncate enabled (or defaults to true based on settings):

Input:

<read_file>
<path>src/large-module.js</path>
<auto_truncate>true</auto_truncate> <!-- Optional if defaults to true -->
</read_file>

Simulated Output (for large_file.log with 1500 lines, limited to 1000):

1 | Log entry 1...
2 | Log entry 2...
...
1000 | Log entry 1000...
[... truncated 500 lines ...]

(Output is limited to the configured maximum lines with a truncation notice)

Attempting to Read a Non-Existent File

If the specified file does not exist:

Input:

<read_file>
<path>non_existent_file.txt</path>
</read_file>

Simulated Output (Error):

Error: File not found at path 'non_existent_file.txt'.

Attempting to Read a Blocked File

If the file is excluded by rules in the .vjspignore file:

Input:

<read_file>
<path>.env</path>
</read_file>

Simulated Output (Error):

Error: Access to file '.env' is denied due to .vjspignore rules.