filename.md

Introducing a #fileName Debug Identifier

• Proposal: SE-00XX
• Author(s): Erica Sadun
• Status: TBD
• Review manager: TBD

Introduction

This proposal introduces #fileName to the modernized debug identifier literals updated in SE-0028.

This proposal was discussed on-list in the [Pitch] Introducing #fileName debug identifier thread.

Motivation

Of all the possible expansions brought up in the SE-0028 discussion on modernizing debug identifiers, I believe #fileName offers the best reward for debug logging. A simple websearch for __FILE__ lastPathComponent yields page after page of results across both Swift and Objective-C.

While a full file path remains a vital component for context feedback, many error reporting systems trim paths for better readability. The following example shows a synthesized error using both approaches. For many projects, the latter feedback is more appropriate in being clear, succinct, and to the point.

CoreError(reason: "Reason", context: "/Users/ericasadun/Desktop/SviftTestbed/SviftTestbed/main.swift:29")
// versus
CoreError(reason: "Reason", context: "main.swift:29")

Detail Design

The #fileName identifier returns the source context file stripped of its path. Water has gone under the #identifier bridge since SE-0028, specifically a general embrace of lowerCamelCase identifiers and unambiguous names. I think #fileName conforms to that philosophy.

(One might consider renaming #line to #lineNumber, #file to #filePath, and #column to #fileColumn but those lie outside the scope of this proposal.)

Impact on Existing Code

This proposal does not break existing code and offers a way for developers to simplify their existing error-handling and logging code.

Example Use-Case

/// Picks up file and line context for error handling.
///
/// - parameter items: Caller supplies one or more instances
///   as "reasons", which need not be strings. Their default
///   representation will be added to the 'reasons' list.
/// - Parameter file: source file, derived from `__FILE__` context literal
/// - Parameter line: source line, derived from `__LINE__` context literal
public func ContextError(
    items: Any...,
    fileName: String = __FILE__,
    lineNumber: Int = __LINE__
    ) -> CoreError
{
    /// Munges supplied items into a single compound "reason"
    /// describing the reasons the error took place
    let reasons = items.map({ "\($0)" }).joinWithSeparator(", ")
    
    /// Trimmed file name, derived from calling context
    let coreFileName = (fileName as NSString).lastPathComponent
    
    /// Establish the context
    let context = "\(coreFileName):\(lineNumber) "
    
    // Produce and return a core error
    return CoreError(reasons, context)
}

Alternatives Considered

There are no alternatives considered. Although many developers requested a relative file path, with respect to the project home, to the best of my understanding Xcode does not offer an option for building a project with relative file paths.