luajitos

README.md (8293B)

---

 # Lunar Editor
 
 A simple, elegant text editor for LuajitOS with word wrap and line numbers.
 
 ## Features
 
 - **Black text on white background** - Easy to read, classic text editor appearance
 - **Line numbers** - Grey line numbers displayed on the left (default: ON)
 - **Word wrap** - Automatically wrap long lines (default: ON)
 - **Keyboard navigation** - Full cursor control with arrow keys
 - **File operations** - Open and save files from/to user directory
 - **Status bar** - Shows current file, line/column, modification status, and settings
 
 ## Usage
 
 ### Starting the Editor
 
 ```lua
 -- Open empty editor
 run("com.luajitos.lunareditor")
 
 -- Open specific file
 run("com.luajitos.lunareditor", "~/myfile.txt")
 ```
 
 ### Keyboard Controls
 
 **Text Editing:**
 - **Type** - Insert characters at cursor
 - **Enter** - Insert new line
 - **Backspace** - Delete character before cursor
 - **Tab** - Insert 4 spaces
 
 **Navigation:**
 - **Arrow Keys** - Move cursor (Up, Down, Left, Right)
 - **Left/Right** - Move between characters
 - **Up/Down** - Move between lines
 
 **File Operations:**
 *(Currently requires API calls - see API section)*
 
 ### Current State Indicators
 
 The status bar shows:
 - **File name** - Current file path or `[Untitled]`
 - **[Modified]** - Appears if file has been edited
 - **Line X, Col Y** - Current cursor position
 - **Lines: N** - Total line count
 - **Wrap: ON/OFF** - Word wrap state
 - **LineNum: ON/OFF** - Line number display state
 
 ## Configuration
 
 Default settings are defined in the code:
 
 ```lua
 settings = {
     wordWrap = true,      -- Enable word wrap
     lineNumbers = true,   -- Show line numbers
     fontSize = 8,         -- Character width (pixels)
     lineHeight = 12       -- Line height (pixels)
 }
 ```
 
 ## File Operations
 
 ### Saving Files
 
 ```lua
 -- From within editor.lua or via exported function
 saveFile("~/myfile.txt")
 ```
 
 ### Loading Files
 
 ```lua
 -- From within editor.lua or via exported function
 loadFile("~/myfile.txt")
 
 -- Or pass as argument when running
 run("com.luajitos.lunareditor", "~/document.txt")
 ```
 
 ## Permissions
 
 The editor requires the following permissions:
 
 - **draw** - Display the editor window
 - **filesystem** - Read and write files
 
 ## Allowed Paths
 
 - **~/** - Full access to user home directory and all subdirectories
 
 This means you can edit any file in your home directory, such as:
 - `~/notes.txt`
 - `~/projects/code.lua`
 - `~/documents/readme.md`
 
 ## Visual Layout
 
 ```
 ┌─────────────────────────────────────────────────┐
 │ Lunar Editor                                  [X]│
 ├────┬──────────────────────────────────────────────┤
 │  1 │ This is line one                             │
 │  2 │ This is line two with some longer text that  │
 │    │ wraps to the next display line if word wrap  │
 │    │ is enabled                                   │
 │  3 │ Line three|                                  │
 │    │                                              │
 │    │                                              │
 ├────┴──────────────────────────────────────────────┤
 │ ~/myfile.txt [Modified] | Line 3, Col 11 | ... │
 └─────────────────────────────────────────────────┘
 ```
 
 **Legend:**
 - Left column: Line numbers (grey on light grey background)
 - Main area: Text content (black on white)
 - `|` - Cursor (blue, blinking)
 - Bottom bar: Status information (grey background)
 
 ## Color Scheme
 
 - **Background:** White (`0xFFFFFF`)
 - **Text:** Black (`0x000000`)
 - **Line numbers:** Grey (`0x808080`)
 - **Line number background:** Light grey (`0xF0F0F0`)
 - **Cursor:** Blue (`0x0000FF`)
 - **Status bar background:** Light grey (`0xE0E0E0`)
 
 ## Implementation Details
 
 ### Word Wrap Algorithm
 
 When word wrap is enabled:
 1. Calculate characters per line based on window width
 2. Split text at character limit
 3. Try to break at last space or tab before limit
 4. If no word boundary, break at character limit
 5. Create multiple display lines from single source line
 
 ### Line Number Display
 
 - Line numbers shown only for the first display segment of each source line
 - When a line wraps, wrapped segments have no line number
 - Line numbers always refer to source line, not display line
 - Grey color distinguishes them from text content
 
 ### Cursor Positioning
 
 - Cursor position tracked in source text (line and column)
 - Blinking cursor rendered at calculated display position
 - Auto-scroll ensures cursor stays visible when navigating
 - Cursor moves to end of line if target column doesn't exist
 
 ### File Format
 
 - Files saved with Unix line endings (`\n`)
 - No BOM or encoding markers (plain ASCII/UTF-8)
 - Trailing newline preserved if present in original file
 
 ## Limitations
 
 1. **No syntax highlighting** - Plain text only
 2. **No undo/redo** - Edit carefully
 3. **No search/replace** - Manual navigation only
 4. **No clipboard** - Can't copy/paste
 5. **No mouse selection** - Keyboard only
 6. **Fixed window size** - 800x600 pixels
 7. **ASCII only** - No Unicode support (limited by font rendering)
 
 ## Troubleshooting
 
 ### Editor doesn't respond to keyboard
 
 **Solution:** Click on the editor window to focus it.
 
 The editor must be the active window to receive keyboard input.
 
 ### Can't save file
 
 **Possible causes:**
 - File path outside `~/` directory
 - Missing filesystem permission
 - Directory doesn't exist
 
 **Solution:** Ensure you're saving to `~/` and the directory exists.
 
 ### Word wrap doesn't break at words
 
 This happens when:
 - Line has no spaces or tabs
 - Word is longer than line width
 
 In these cases, the line breaks at character limit.
 
 ### Line numbers missing
 
 Check that `settings.lineNumbers = true` in editor.lua.
 
 ## Examples
 
 ### Create a new file
 
 ```lua
 -- 1. Start editor
 run("com.luajitos.lunareditor")
 
 -- 2. Type your content
 -- (use keyboard to type)
 
 -- 3. Save it
 -- (requires calling saveFile function)
 ```
 
 ### Edit an existing file
 
 ```lua
 -- Open file
 run("com.luajitos.lunareditor", "~/readme.txt")
 
 -- Make changes
 -- (use arrow keys and typing)
 
 -- Save changes
 -- (requires calling saveFile function)
 ```
 
 ## Future Enhancements
 
 Potential features for future versions:
 
 - [ ] Menu bar with File, Edit, View options
 - [ ] Save/Save As dialogs
 - [ ] Open file dialog
 - [ ] Undo/Redo functionality
 - [ ] Search and replace
 - [ ] Goto line number
 - [ ] Clipboard support (cut/copy/paste)
 - [ ] Mouse selection and scrolling
 - [ ] Configurable color schemes
 - [ ] Syntax highlighting for Lua
 - [ ] Multi-file tabs
 - [ ] Status bar improvements (file size, encoding)
 - [ ] Keyboard shortcuts (Ctrl+S, Ctrl+O, etc.)
 
 ## Technical Specifications
 
 - **Window size:** 800x600 pixels
 - **Text area:** ~750x570 pixels (with line numbers)
 - **Line number width:** 50 pixels
 - **Status bar height:** 20 pixels
 - **Character width:** ~8 pixels
 - **Line height:** 12 pixels
 - **Approximate capacity:** ~95 chars/line, ~47 lines visible
 
 ## API Reference
 
 ### Internal Functions
 
 ```lua
 -- File operations
 saveFile(filepath)      -- Save current content to file
 loadFile(filepath)      -- Load file into editor
 
 -- Text manipulation
 insertChar(char)        -- Insert character at cursor
 insertNewline()         -- Insert new line at cursor
 deleteChar()            -- Delete character before cursor
 
 -- Cursor movement
 moveCursorLeft()        -- Move cursor left
 moveCursorRight()       -- Move cursor right
 moveCursorUp()          -- Move cursor up
 moveCursorDown()        -- Move cursor down
 
 -- Display
 rebuildDisplayLines()   -- Rebuild wrapped display lines
 wrapLine(text, width)   -- Wrap single line to width
 ```
 
 ## Credits
 
 **Developer:** luajitos
 **Version:** 1.0.0
 **Category:** Productivity
 **License:** Part of LuajitOS
 
 ## See Also
 
 - **Application Development Guide** - Learn to create LuajitOS apps
 - **SafeFS Documentation** - File system API reference
 - **Manifest Specification** - App configuration format