Redaktilo Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require gnugat/redaktilo
   

   No additional configuration is required—it’s a standalone library.

2. Basic Usage Import the core class and create a Redaktilo instance with your text:

   use Gnugat\Redaktilo\Redaktilo;
   
   $text = "Hello, world!";
   $redaktilo = new Redaktilo($text);
   

3. First Use Case: Inserting Text Use the insert() method to manipulate text at a specific position:

   $redaktilo->insert(7, " beautiful ");
   echo $redaktilo->getText(); // Output: "Hello, beautiful world!"
   

Implementation Patterns

Core Workflows

1. Position-Based Manipulation

   • Use jump() to navigate to a specific position (e.g., line/column offsets):

     $redaktilo->jump(5, 0); // Move to line 5, column 0
     

   • Modify text at the cursor position with insert(), delete(), or replace().

2. Line/Column Awareness

   • Leverage getLine()/getColumn() to work with multi-line text:

     $line = $redaktilo->getLine(3); // Get the 3rd line
     $redaktilo->insertLine(2, "New line"); // Insert before line 2
     

3. Batch Operations

   • Chain methods for sequential edits:

     $redaktilo
         ->jump(0, 0)
         ->insert("Prefix: ")
         ->jump(0, 0)
         ->insertLine(0, "Header");
     

Integration Tips

• Laravel Blade Integration Use Redaktilo to dynamically generate or modify text in views:

  $redaktilo = new Redaktilo($userInput);
  $redaktilo->replace("old", "new");
  return view('editor', ['content' => $redaktilo->getText()]);
  

• Form Request Validation Validate structured text (e.g., CSV, Markdown) by parsing with Redaktilo:

  $request->validate([
      'content' => function ($attribute, $value, $fail) {
          $redaktilo = new Redaktilo($value);
          if ($redaktilo->getLineCount() > 100) {
              $fail('Maximum 100 lines allowed.');
          }
      }
  ]);
  

• File Manipulation Read/write files with Redaktilo for granular edits:

  $content = file_get_contents('file.txt');
  $redaktilo = new Redaktilo($content);
  $redaktilo->insertLine(0, "# Updated\n");
  file_put_contents('file.txt', $redaktilo->getText());
  

Gotchas and Tips

Pitfalls

1. Zero-Based Indexing

   • jump() and insertLine() use 0-based indexing for lines/columns. Off-by-one errors are common:

     // WRONG: Inserts AFTER line 0 (skips first line)
     $redaktilo->insertLine(1, "New line");
     
     // CORRECT: Inserts BEFORE line 0 (at the top)
     $redaktilo->insertLine(0, "New line");
     

2. Cursor Position After Deletion

   • delete() moves the cursor to the end of the deleted text. Reset it explicitly if needed:

     $redaktilo->delete(5); // Deletes 5 chars
     $redaktilo->jump(0, 0); // Reset cursor
     

3. Multi-Byte Characters

   • Redaktilo treats text as UTF-8 but counts bytes, not graphemes. For accurate Unicode handling, pre-process with mb_* functions:

     $text = mb_convert_encoding($text, 'UTF-8');
     

Debugging Tips

• Inspect State Use getText() or getCursorPosition() to debug:

  echo "Cursor at: " . $redaktilo->getCursorPosition();
  

• Undo/Redo Redaktilo doesn’t natively support undo/redo. Implement a stack pattern:

  $history = [];
  $redaktilo->insert(0, "Text");
  $history[] = $redaktilo->getText();
  

Extension Points

1. Custom Position Logic Extend Redaktilo to add domain-specific jumps (e.g., "next heading"):

   class CustomRedaktilo extends Redaktilo {
       public function jumpToNextHeading() {
           // Implement regex-based logic
       }
   }
   

2. Event Hooks Override methods to log changes or trigger events:

   $redaktilo->insert(0, "Text");
   event(new TextEdited($redaktilo->getText()));
   

3. Performance For large files, avoid loading the entire text into memory. Use fopen() + fseek() for chunked edits:

   $handle = fopen('large_file.txt', 'r+');
   $redaktilo = new Redaktilo(fread($handle, filesize('large_file.txt')));
   // ... edit ...
   fseek($handle, 0);
   fwrite($handle, $redaktilo->getText());
   fclose($handle);