Merge branch 'develop'

Author: SpartanJ

README.md

@@ -0,0 +1,25 @@
+## Auto Complete
+
+The auto-complete plugin is in charge of providing suggestions for code-completion and signature help.
+
+### Auto Complete config object keys
+
+* **max_label_characters**: Maximum characters displayed in the suggestion box.
+* **suggestions_syntax_highlight**: Enables/disables syntax highlighting in suggestions.
+
+### Auto Complete keybindings object keys
+
+* **autocomplete-close-signature-help**: Closes the signature help
+* **autocomplete-close-suggestion**: Closes the suggestions
+* **autocomplete-first-suggestion**: Moves to the first suggestion in the auto complete list
+* **autocomplete-last-suggestion**: Moves to the last suggestion in the auto complete list
+* **autocomplete-next-signature-help**: Moves to the next signature help
+* **autocomplete-next-suggestion**: Moves to the next suggestion
+* **autocomplete-next-suggestion-page**: Moves to the next page of suggestions
+* **autocomplete-pick-suggestion**: Picks a suggestion
+* **autocomplete-pick-suggestion-alt**: Picks a suggestion (alternative keybinding)
+* **autocomplete-pick-suggestion-alt-2**: Picks a suggestion (alternative keybinding)
+* **autocomplete-prev-signature-help**: Moves to the previous signature help
+* **autocomplete-prev-suggestion**: Moves to the previous suggestion
+* **autocomplete-prev-suggestion-page**: Moves to the previous suggestion page
+* **autocomplete-update-suggestions**: Request to display or update currently displayed suggestions (if possible)

docs/autocomplete.md

@@ -0,0 +1,133 @@
+## Custom languages support
+
+Custom languages support can be added in the languages directory found at:
+
+* *Linux*: uses `XDG_CONFIG_HOME`, usually translates to `~/.config/ecode/languages`
+* *macOS*: uses `Application Support` folder in `HOME`, usually translates to `~/Library/Application Support/ecode/languages`
+* *Windows*: uses `APPDATA`, usually translates to `C:\Users\{username}\AppData\Roaming\ecode\languages`
+
+ecode will read each file located at that directory with `json` extension. Each file can contain one
+or several languages. In order to set several languages the root element of the json file should be
+an array, containing one object for each language, otherwise if the root element is an object, it
+should contain the language definition. Language definitions can override any currently supported
+definition. ecode will prioritize user defined definitions.
+
+### Language definition format
+
+```json
+{
+	"name": "language_name",
+	"files": [ "Array of file extensions supported" ],
+	"comment": "Sets the comment string used for auto-comment functionality.",
+	"patterns": [
+		{ "pattern": "lua_pattern", "type": "type_name" },
+		{ "pattern": "no_capture(pattern_capture_1)(pattern_capture_2)", "type": { "no_capture_type_name", "capture_1_type_name", "capture_2_type_name" } },
+		{ "pattern": ["lua_pattern_start", "lua_pattern_end", "escape_character"], "type": "type_name" }
+		{ "regex": "perl_regex", "type": "type_name" },
+		{ "regex": "no_capture(pattern_capture_1)(pattern_capture_2)", "type": { "no_capture_type_name", "capture_1_type_name", "capture_2_type_name" } },
+		{ "regex": ["regex_start", "regex_end", "escape_character"], "type": "type_name" }
+	],
+	"symbols": [
+		{ "symbol_name": "type_name" }
+	],
+	"visible": true, /* sets if the language is visible as a main language in the editor, optional parameter, true by default */
+	"auto_close_xml_tag": false, /* sets if the language defined supports auto close XML tags, optional parameter, false by default */
+	"lsp_name": "sets the LSP name assigned for the language, optional parameter, it will use the _name_ in lowercase if not set"
+}
+```
+
+### Porting language definitions
+
+ecode uses the same format for language definition as [lite](https://github.com/rxi/lite) and [lite-xl](https://github.com/lite-xl/lite-xl) editors.
+This makes much easier to add new languages to ecode. There's also a helper tool that can be download from
+ecode repository located [here](https://github.com/SpartanJ/ecode/tree/develop/tools/data-migration/lite/language)
+that allows to directly export a lite language definition to the JSON file format used in ecode.
+
+### Extending language definitions
+
+It's possible to easily extend any language definition by exporting it using the CLI arguments provided:
+`--export-lang` and `--export-lang-path`. A user wanting to extend or improve a language definition can
+export it, modify it and install the definition with a `.json` extension in the [custom languages path](#custom-languages-support).
+For example, to extend the language `vue` you will need to run:
+`ecode --export-lang=vue --export-lang-path=./vue.json`, exit the exported file and move it to the
+[custom languages path](#custom-languages-support).
+
+### Language definition example
+
+```json
+{
+  "name": "Elixir",
+  "files": [ "%.ex$", "%.exs$" ],
+  "comment": "#",
+  "patterns": [
+    { "pattern": "#.*\n",                "type": "comment"  },
+    { "pattern": [ ":\"", "\"", "\\" ],    "type": "number"   },
+    { "pattern": [ "\"\"\"", "\"\"\"", "\\" ], "type": "string"   },
+    { "pattern": [ "\"", "\"", "\\" ],     "type": "string"   },
+    { "pattern": [ "'", "'", "\\" ],     "type": "string"   },
+    { "pattern": [ "~%a[/\"|'%(%[%{<]", "[/\"|'%)%]%}>]", "\\" ], "type": "string"},
+    { "pattern": "-?0x%x+",              "type": "number"   },
+    { "pattern": "-?%d+[%d%.eE]*f?",     "type": "number"   },
+    { "pattern": "-?%.?%d+f?",           "type": "number"   },
+    { "pattern": ":\"?[%a_][%w_]*\"?",     "type": "number"   },
+    { "pattern": "[%a][%w_!?]*%f[(]",    "type": "function" },
+    { "pattern": "%u%w+",                "type": "normal"   },
+    { "pattern": "@[%a_][%w_]*",         "type": "keyword2" },
+    { "pattern": "_%a[%w_]*",            "type": "keyword2" },
+    { "pattern": "[%+%-=/%*<>!|&]",      "type": "operator" },
+    { "pattern": "[%a_][%w_]*",          "type": "symbol"   }
+  ],
+  "symbols": [
+    {"def": "keyword"},
+    {"defp": "keyword"},
+    {"defguard": "keyword"},
+    {"defguardp": "keyword"},
+    {"defmodule": "keyword"},
+    {"defprotocol": "keyword"},
+    {"defimpl": "keyword"},
+    {"defrecord": "keyword"},
+    {"defrecordp": "keyword"},
+    {"defmacro": "keyword"},
+    {"defmacrop": "keyword"},
+    {"defdelegate": "keyword"},
+    {"defoverridable": "keyword"},
+    {"defexception": "keyword"},
+    {"defcallback": "keyword"},
+    {"defstruct": "keyword"},
+    {"for": "keyword"},
+    {"case": "keyword"},
+    {"when": "keyword"},
+    {"with": "keyword"},
+    {"cond": "keyword"},
+    {"if": "keyword"},
+    {"unless": "keyword"},
+    {"try": "keyword"},
+    {"receive": "keyword"},
+    {"after": "keyword"},
+    {"raise": "keyword"},
+    {"rescue": "keyword"},
+    {"catch": "keyword"},
+    {"else": "keyword"},
+    {"quote": "keyword"},
+    {"unquote": "keyword"},
+    {"super": "keyword"},
+    {"unquote_splicing": "keyword"},
+    {"do": "keyword"},
+    {"end": "keyword"},
+    {"fn": "keyword"},
+    {"import": "keyword2"},
+    {"alias": "keyword2"},
+    {"use": "keyword2"},
+    {"require": "keyword2"},
+    {"and": "operator"},
+    {"or": "operator"},
+    {"true": "literal"},
+    {"false": "literal"},
+    {"nil": "literal"}
+  ]
+}
+```
+
+For more complex syntax definitions please see the definition of all the native languages supported
+by ecode [here](https://github.com/SpartanJ/eepp/tree/develop/src/eepp/ui/doc/languages) and
+[here](https://github.com/SpartanJ/eepp/tree/develop/src/modules/languages-syntax-highlighting/src/eepp/ui/doc/languages).

docs/customlanguages.md

@@ -0,0 +1,160 @@
+## Debugger
+
+*ecode* implements the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol) (DAP) for debugger support. This enables seamless debugging integration with various languages through a common protocol. DAP is used by VS Code and other major editors and has been implemented for a wide range of programming languages. For more information, see the [list of implementations](https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/).
+
+Initially, *ecode* provides support for some of the most common debug adapter implementations, with plans to add support for more languages in future updates.
+
+### How It Works
+
+There are two ways to use the debugger in *ecode*:
+
+1. **Using Default *ecode* Configurations:** These configurations are designed to work seamlessly with your build settings. The executable used in these default options is the `Run Target` of your currently selected `Build Configuration`.
+
+2. **Using Custom Launch Configurations:** Users can provide custom launch configurations within the project folder. These configurations should be located at `.ecode/launch.json` or `.vscode/launch.json`. *ecode* uses the same `launch.json` format as VS Code, ensuring compatibility for users migrating from other DAP-based editors. However, *ecode* will only recognize currently supported debuggers, as DAP implementations can vary significantly in configuration details.
+
+### Using *ecode* Default Configurations
+
+Once you have a `Build Configuration` with a selected `Run Target`, this will be used for the default `Launch` and `Attach` configurations for your language.
+
+- **Launch Configurations:** These configurations start an executable from your local environment, with the process managed by the debugger. This is the most common setup for most users. To use it:
+
+  - Ensure your `Run Target` is ready.
+  - Go to the `Debugger` tab in the Side Panel.
+  - Select the debugger based on the language you want to debug. For example, C or C++ binaries can be debugged using `gdb` or `lldb-dap` (also known as `lldb-vscode`), depending on your platform.
+  - Choose the appropriate `Debugger Configuration`, such as `Launch Binary`.
+  - Click `Debug` or press `Ctrl/Cmd + F5` to start debugging.
+
+- **Attach Configurations:** These configurations allow the debugger to attach to an already running process, either locally or remotely. You can attach to a process via its process ID or its binary name/path. Some configurations include a `(wait)` option, which waits for the process to start before attaching.
+
+  The default `Attach to Binary` option will also use the current `Run Target` to execute the binary. Unlike the `Launch` configuration, here the process is managed by *ecode* instead of the debugger. This feature is particularly useful for debugging CLI programs from the terminal if the `Run Target` is configured with `Run in Terminal`.
+
+### Using Custom Launch Configurations
+
+*ecode* supports custom launch configurations through the `launch.json` file, which can be placed in either the `.ecode/` or `.vscode/` folder within your project directory. This format is fully compatible with VS Code, making it easy for users transitioning from other editors.
+
+#### Creating a `launch.json` File
+
+The `launch.json` file defines how debugging sessions are launched or attached. A basic configuration looks like this:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Launch Program",
+      "type": "lldb",
+      "request": "launch",
+      "program": "${workspaceFolder}/bin/myapp",
+      "args": ["--verbose"],
+      "cwd": "${workspaceFolder}",
+      "stopOnEntry": false
+    }
+  ]
+}
+```
+
+#### Key Fields Explained
+
+- **`name`**: The display name for the configuration in the *ecode* debugger interface.
+- **`type`**: The debugger type, such as `gdb`, `lldb`, or any supported DAP adapter.
+- **`request`**: Specifies whether to `launch` a new process or `attach` to an existing one.
+- **`program`**: The path to the executable you want to debug.
+- **`args`**: Optional. Command-line arguments passed to the program.
+- **`cwd`**: The working directory for the program.
+- **`stopOnEntry`**: Optional. If `true`, the debugger will pause at the program's entry point.
+
+#### Advanced Customization
+
+You can create multiple configurations for different scenarios, such as:
+
+- Attaching to a remote process:
+
+```json
+{
+  "name": "Attach to Remote",
+  "type": "gdb",
+  "request": "attach",
+  "host": "192.168.1.100",
+  "port": 1234
+}
+```
+
+- Debugging with environment variables:
+
+```json
+{
+  "name": "Launch with Env Vars",
+  "type": "lldb",
+  "request": "launch",
+  "program": "${workspaceFolder}/bin/myapp",
+  "env": {
+    "DEBUG": "1",
+    "LOG_LEVEL": "verbose"
+  }
+}
+```
+
+*ecode* will automatically detect and load configurations from `launch.json`, prioritizing `.ecode/launch.json` if both are present. This approach ensures flexibility and consistency across projects, whether you're starting fresh or migrating from VS Code.
+
+*ecode* supports the same `launch.json` schema as VS Code, including standard input types such as:
+
+- **`pickProcess`**: Prompts the user to select a running process from a list. This is useful for attaching the debugger to an already running application.
+- **`pickString`**: Allows the user to select from a predefined list of string options.
+- **`promptString`**: Prompts the user to manually enter a string value, useful for dynamic input during debugging sessions.
+
+In addition to these standard inputs, *ecode* extends functionality with an extra input type:
+
+- **`pickFile`**: This *ecode*-specific input allows users to select a binary file directly from the file system. It is particularly useful when you need to choose an executable to be run and debugged without hardcoding the path in your `launch.json`.
+
+These input options make custom configurations flexible and dynamic, adapting to different debugging workflows and environments.
+
+#### Variables Reference
+
+ecode supports all vscode variable substitution in debugger configuration files. Variable substitution is supported inside some key and value strings in `launch.json` files using **${variableName}** syntax.
+
+##### Predefined variables
+
+The following predefined variables are supported:
+
+- **${userHome}** - the path of the user's home folder
+- **${workspaceFolder}** - the path of the folder opened in VS Code
+- **${workspaceFolderBasename}** - the name of the folder opened in VS Code without any slashes (/)
+- **${file}** - the current opened file
+- **${fileWorkspaceFolder}** - the current opened file's workspace folder
+- **${relativeFile}** - the current opened file relative to `workspaceFolder`
+- **${relativeFileDirname}** - the current opened file's dirname relative to `workspaceFolder`
+- **${fileBasename}** - the current opened file's basename
+- **${fileBasenameNoExtension}** - the current opened file's basename with no file extension
+- **${fileExtname}** - the current opened file's extension
+- **${fileDirname}** - the current opened file's folder path
+- **${fileDirnameBasename}** - the current opened file's folder name
+- **${cwd}** - the task runner's current working directory upon the startup of VS Code
+- **${lineNumber}** - the current selected line number in the active file
+- **${selectedText}** - the current selected text in the active file
+- **${execPath}** - the path to the running VS Code executable
+- **${defaultBuildTask}** - the name of the default build task
+- **${pathSeparator}** - the character used by the operating system to separate components in file paths
+- **${/}** - shorthand for **${pathSeparator}**
+
+### Language-Specific Configurations
+
+In addition to general configurations, *ecode* offers language-specific settings, such as loading core dumps. Each debugger and language may provide different configurations based on the debugger's capabilities and the language's characteristics.
+
+### Debugger keybindings object keys
+
+* **debugger-breakpoint-enable-toggle**: Toggles enable/disable current line breakpoint (if any)
+* **debugger-breakpoint-toggle**: Toggles breakpoint in current line
+* **debugger-continue-interrupt**: If debugger is running: continues or interrupt the current execution. If debugger is not running builds and run the debugger.
+* **debugger-start**: Starts the debugger
+* **debugger-start-stop**: Starts or stops the debugger (depending on its current status)
+* **debugger-step-into**: Steps into the current debugged line
+* **debugger-step-out**: Steps out the current debugged line
+* **debugger-step-over**: Steps over the current debugged line
+* **debugger-stop**: Stops the debugger
+* **toggle-status-app-debugger**: Opens/hides the debugger status bar panel
+
+### Debugger config object keys
+
+* **fetch_globals**: Enable/Disable if global variables should be fetched automatically (when available)
+* **fetch_registers**: Enable/Disable if registers should be fetched automatically (when available)
+* **silent**: Enable/Disable non-critical Debugger logs

docs/debugger.md

@@ -0,0 +1,46 @@
+## Auto Formatter
+
+The formatter plugin works exactly like the linter plugin, but it will execute tools that auto-format code.
+*ecode* provides support for several languages by default with can be extended easily by expanding the
+`formatters.json` configuration. `formatters.json` default configuration can be obtained from [here](https://raw.githubusercontent.com/SpartanJ/eepp/develop/bin/assets/plugins/formatters.json).
+It also supports some formatters natively, this means that the formatter comes with ecode without requiring any external dependency.
+And also supports LSP text document formatting, meaning that if you're running an LSP that supports formatting documents, formatting will be available too.
+To configure new formatters you can create a new `formatters.json` file in the [default configuration path](#plugins-configuration-files-location) of *ecode*.
+
+### `formatters.json` format
+
+```json
+{
+    "config": {
+        "auto_format_on_save": false
+    },
+    "keybindings": {
+        "format-doc": "alt+f"
+    },
+    "formatters": [
+        {
+            "file_patterns": ["%.js$", "%.ts$"],
+            "command": "prettier $FILENAME"
+        }
+    ]
+}
+```
+
+### Currently supported formatters
+
+Please check the [language support table](#language-support-table)
+
+### Formatter config object keys
+
+* **auto_format_on_save**: Indicates if after saving the file it should be auto-formatted
+
+### Formatter keybindings object keys
+
+* **format-doc**: Keybinding to format the doc with the configured language formatter
+
+### Formatter JSON object keys
+
+* **file_patterns**: Array of [Lua Patterns](https://www.lua.org/manual/5.4/manual.html#6.4.1) representing the file extensions that must use the formatter
+* **command**: The command to execute to run the formatter. $FILENAME represents the file path
+* **type**: Indicates the mode that which the formatter outputs the results. Supported two possible options: "inplace" (file is replaced with the formatted version), "output" (newly formatted file is the stdout of the program, default option) or "native" (uses the formatter provided by ecode)
+* **url** (optional): The web page URL of the formatter