Query Parameters

srcref URLs accept 12 query parameters that control how lines are located in the target file. Parameters are divided into required (repository and begin-line matching) and optional (end-line matching for ranges).

Parameter Reference

Repository Parameters

Begin Parameters

These parameters determine the start line of the highlight.

End Parameters

These parameters determine the end line of the highlight. They are optional — when omitted or when eregex is empty, srcref highlights a single line.

Detailed Parameter Guide

bregex / eregex — Regex Patterns

The regex patterns use Java regex syntax. Each line of the file is tested individually against the pattern.

Simple literal match:

  // Match a literal string — no special regex characters needed
  val literalMatch =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "object Main",
    )

Escaped metacharacters:

  // Parentheses are regex metacharacters — escape them with backslashes
  val escapedParens =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(CallLogging\\)",
    )

boccur / eoccur — Occurrence Selection

When a regex matches multiple lines, the occurrence parameter selects which match to use. The value is 1-based (first match = 1).

  val secondOccurrence =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(",
      beginOccurrence = 2,
    )

boffset / eoffset — Line Offset

Offsets shift the highlighted line relative to the match:

• Positive offset: moves the highlight below the match
• Negative offset: moves the highlight above the match
• Zero (default): highlights the matched line itself

  val withOffset =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(CallLogging\\)",
      beginOffset = -1,
      endRegex = "install\\(Compression\\)",
      endOffset = 5,
    )

In this example:

• The begin line is moved 1 line above the install(CallLogging) match
• The end line is moved 5 lines below the install(Compression) match

btopd / etopd — Search Direction

Controls whether the file is searched top-down or bottom-up:

• true (default): searches from the first line to the last
• false: searches from the last line to the first

Top-down (default) — finds the first occurrence from the top:

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

Bottom-up — finds the first occurrence from the bottom:

  val bottomUp =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(",
      beginTopDown = false,
    )

Bottom-up search is particularly useful for finding closing braces 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,
    )

branch — Branch Selection

Defaults to master (or the value of the DEFAULT_BRANCH environment variable on self-hosted instances). Override it to target other branches:

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

How Parameters Interact

Single-Line Highlight

When eregex is empty (or omitted), srcref highlights a single line:

Final line = (bregex match) + boffset

Line-Range Highlight

When eregex is provided, srcref highlights from the begin line to the end line:

Begin line = (bregex match) + boffset
End line   = (eregex match) + eoffset
GitHub URL = ...#L{begin}-L{end}

If the begin and end lines are the same, only a single line is highlighted.

Search Direction + Occurrence

The occurrence counter resets based on direction:

• Top-down: occurrence 1 = the first match reading from line 1
• Bottom-up: occurrence 1 = the first match reading from the last line

This means boccur=1 with btopd=false gives you the last match in the file, while boccur=2 with btopd=false gives you the second-to-last match.

Error Handling

srcref provides clear error messages when parameters are invalid:

On error, srcref redirects to a /problem page displaying the error message along with all the original parameters, so you can fix the issue and retry.