Clarity.OpenEditor (Clarity v0.4.0)

View Source

Handles opening files in editors or browsers based on configuration.

This module provides a flexible editor integration system that supports:

  • Local editor commands with template variable substitution
  • URL mode for opening files in browsers via source URLs
  • Case-insensitive template variables (__FILE__, __LINE__, __COLUMN__)
  • Multiple configuration sources with priority hierarchy

Configuration

Editor configuration is managed by Clarity.Config. See the documentation for Clarity.Config for detailed configuration options and examples.

Template Variables

When using system command mode, the following case-insensitive template variables are supported:

  • __FILE__ - replaced with the file path
  • __LINE__ - replaced with the line number
  • __COLUMN__ - replaced with the column number

URL Mode

To enable URL mode, set the editor configuration to "__URL__" (case-insensitive) or the atom :url. In URL mode, the module will:

  1. Determine which application/dependency the file belongs to
  2. Extract the source_url from that application's configuration
  3. Generate a platform-specific URL using ExDoc-style patterns
  4. Return the URL for opening in a browser

Command Execution

This module executes system commands based on user configuration. Ensure that the configured commands are safe and trusted to avoid security risks. If you run this in an untrusted environment, set the editor to :url or "__URL__" to avoid executing arbitrary commands.

Clarity does not validate or sanitize the commands; it simply substitutes the template variables and executes them as-is.

Variable substitution does not escape special characters, so be cautious if file paths may contain spaces or shell-sensitive characters.

Summary

Types

action_result()

Functions

action(source_location)

Determines the action available for a given source location.

Types

action_result()

@type action_result() ::
  :editor_not_available
  | :action_not_available
  | {:url, String.t()}
  | {:execute, (-> :ok | {:error, term()})}

Functions

action(source_location)

@spec action(Clarity.SourceLocation.t()) :: action_result()

Determines the action available for a given source location.

Returns the appropriate action based on editor configuration and the ability to process the source location. This is the main entry point for editor integration.

Returns

  • :editor_not_available - No editor is configured
  • :action_not_available - Editor is configured but action cannot be determined (e.g., URL building failed, command preparation failed)
  • {:url, url} - URL mode with successfully built URL
  • {:execute, function} - System command mode with executable function

Examples

case Clarity.OpenEditor.action(source_location) do
  :editor_not_available -> 
    # Don't show editor button
  :action_not_available -> 
    # Don't show editor button 
  {:url, url} -> 
    # Show button that opens URL in browser
  {:execute, execute_fn} -> 
    # Show button that calls execute_fn.()
end