Skip to content

Advanced Usage

This page covers advanced techniques for creating precise srcref links using offset tricks, directional search, and pattern strategies.

Search Direction Strategies

Top-Down (Default)

Top-down search scans the file from line 1 to the last line. This is the default and works well for most cases:

  val url =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "fun main",
    )

Bottom-up search scans from the last line upward. This is powerful for finding closing constructs or the last occurrence of a pattern:

  // Find the last closing brace in a file (useful for end of class/object)
  val lastBrace =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "object Urls",
      endRegex = "^\\}",
      endTopDown = false,
    )

When to Use Bottom-Up

  • Finding the closing brace of a class, function, or block
  • Finding the last import statement
  • Finding the last occurrence of a repeated pattern
  • Finding the end of a file-level construct

Combining Directions

You can use different directions for begin and end patterns. A common pattern is top-down for the start and bottom-up for the end:

  // Highlight an entire function from declaration to closing brace
  val entireFunction =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "internal fun calcLineNumber",
      endRegex = "^\\ \\ \\}",
      endOccurrence = 1,
      endTopDown = false,
    )

This finds calcLineNumber from the top and its closing } from the bottom, covering the entire function regardless of how many internal braces it has.

Offset Techniques

Skipping Past Signatures

Use a positive offset to skip past a function signature and highlight only the body:

  // Skip past the function signature to highlight only the body
  val functionBody =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "internal fun calcLineNumber",
      beginOffset = 1,
      endRegex = "^\\ \\ \\}",
      endOccurrence = 1,
      endTopDown = false,
      endOffset = -1,
    )

Context Above the Match

Use a negative offset to include lines before the match — useful for capturing documentation comments or annotations:

  // Use negative offsets to highlight lines before the match
  val contextAbove =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "internal fun calcLineNumber",
      beginOffset = -5,
    )

This highlights 5 lines above calcLineNumber, capturing its KDoc comment.

Trimming Range Edges

Combine offsets on both begin and end to narrow a range:

  • beginOffset = 1 skips the opening line
  • endOffset = -1 skips the closing line
  // Skip past the function signature to highlight only the body
  val functionBody =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "internal fun calcLineNumber",
      beginOffset = 1,
      endRegex = "^\\ \\ \\}",
      endOccurrence = 1,
      endTopDown = false,
      endOffset = -1,
    )

Occurrence Selection

Finding the Nth Match

When a pattern appears multiple times, use occurrence to pick the right one:

  // Match the 3rd occurrence of "install(" in Main.kt
  val thirdInstall =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(",
      beginOccurrence = 3,
    )

When combined with bottom-up search, occurrences count from the end of the file:

btopd boccur Selects
true 1 First match from the top
true 2 Second match from the top
false 1 Last match (first from bottom)
false 2 Second-to-last match

Targeting Code Constructs

Highlighting an Entire Function

Match the declaration at the top and the closing brace from the bottom:

  // Highlight an entire function from declaration to closing brace
  val entireFunction =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "internal fun calcLineNumber",
      endRegex = "^\\ \\ \\}",
      endOccurrence = 1,
      endTopDown = false,
    )

Highlighting a Companion Object

  // Highlight a companion object block
  val companionBlock =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/ContentCache.kt",
      beginRegex = "companion object",
      endRegex = "^\\ \\ \\}",
      endTopDown = false,
    )

Highlighting a When Expression

  // Highlight a when expression block
  val whenBlock =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/ContentCache.kt",
      beginRegex = "return when",
      endRegex = "^\\ \\ \\ \\ \\ \\ \\}",
      endTopDown = false,
    )

Highlighting Enum Entries

Match from the first entry to the last:

  // Highlight all enum entries in QueryParams
  val enumEntries =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/QueryParams.kt",
      beginRegex = "ACCOUNT\\(",
      endRegex = "END_TOPDOWN\\(",
      endOffset = 0,
    )

Highlighting a Route Handler

  // Highlight a specific route handler
  val routeHandler =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Routes.kt",
      beginRegex = "get\\(GITHUB\\.path\\)",
      endRegex = "^\\s+\\}",
      endOccurrence = 1,
    )

Indentation-Aware Patterns

When matching closing braces (}), indentation helps disambiguate between nested and top-level braces.

Pattern Matches
^\} Top-level closing brace (no indent)
^ \} 2-space indented closing brace
^ \} 4-space indented closing brace
^\s+\} Any indented closing brace

Note

In Kotlin strings, spaces in regex are literal. "^\\ \\ \\}" matches a line starting with two spaces followed by }.

Regex Timeout Protection

srcref enforces a 5-second timeout on each regex search to prevent catastrophic backtracking from consuming server resources.

Patterns that can cause timeouts:

Dangerous Pattern Why Safe Alternative
(.+)+ Exponential backtracking .+
(a*)* Nested quantifiers a*
(a\|aa)+ Overlapping alternatives a+
.*.*.* Multiple unbounded quantifiers .*

If a timeout occurs, srcref returns: Regex matching timed out for begin regex: "pattern"

Working with URLs

Editing an Existing srcref URL

Append &edit to any srcref URL to open it in the web editor with all fields pre-populated:

# Add &edit to any srcref URL to open it in the editor:
https://www.srcref.com/github?account=pambrose&repo=srcref&branch=master&path=src/main/kotlin/com/pambrose/srcref/Main.kt&bregex=fun+main&boccur=1&boffset=0&btopd=true&edit

Manually Constructing URLs

When you can't use the API, construct URLs directly. Remember to URL-encode parameter values:

# Highlight a single line containing "fun main" in Main.kt:
https://www.srcref.com/github?account=pambrose&repo=srcref&branch=master&path=src/main/kotlin/com/pambrose/srcref/Main.kt&bregex=fun+main&boccur=1&boffset=0&btopd=true

For line ranges, add the end parameters:

# Highlight from "install(CallLogging)" to 3 lines past "install(Compression)":
https://www.srcref.com/github?account=pambrose&repo=srcref&branch=master&path=src/main/kotlin/com/pambrose/srcref/Main.kt&bregex=install%5C%28CallLogging%5C%29&boccur=1&boffset=0&btopd=true&eregex=install%5C%28Compression%5C%29&eoccur=1&eoffset=3&etopd=false

Self-Hosting Tips

Custom URL Prefix

When self-hosting, set the prefix parameter to your instance URL:

  val selfHosted =
    srcrefUrl(
      account = "myorg",
      repo = "myrepo",
      path = "src/App.kt",
      beginRegex = "class App",
      prefix = "https://srcref.internal.myorg.com",
      branch = "develop",
    )

Private Repositories

srcref fetches files from GitHub's raw content URL (raw.githubusercontent.com). For private repositories, you'll need to self-host and configure authentication at the network level.

Performance Considerations

Caching

srcref caches file content with ETag-based validation. Subsequent requests for the same file use HTTP conditional requests (304 Not Modified) to avoid re-downloading unchanged content.

  • Default cache size: 2048 entries (configurable via MAX_CACHE_SIZE)
  • LRU eviction runs every 5 minutes when the cache exceeds its limit
  • Maximum file size: 5MB (configurable via MAX_LENGTH)

Regex Efficiency

For best performance:

  1. Be specific — install\(CallLogging\) is faster than install\(.+\)
  2. Anchor when possible — ^import is faster than import
  3. Avoid backtracking — use possessive quantifiers or atomic groups
  4. Keep it simple — the simplest pattern that uniquely matches is best