Skip to content

Programmatic API

srcref is published to Maven Central as com.pambrose:srcref, providing the Api.srcrefUrl() function for generating srcref URLs programmatically.

Installation

dependencies {
    implementation("com.pambrose:srcref:2.3.0")
}

dependencies {
    implementation 'com.pambrose:srcref:2.3.0'
}

<dependency>
    <groupId>com.pambrose</groupId>
    <artifactId>srcref</artifactId>
    <version>2.3.0</version>
</dependency>

srcrefUrl() Function

The Api.srcrefUrl() function generates a srcref URL string that, when visited, dynamically resolves to a GitHub permalink.

Signature

fun srcrefUrl(
    account: String,
    repo: String,
    path: String,
    beginRegex: String,
    beginOccurrence: Int = 1,
    beginOffset: Int = 0,
    beginTopDown: Boolean = true,
    endRegex: String = "",
    endOccurrence: Int = 1,
    endOffset: Int = 0,
    endTopDown: Boolean = true,
    prefix: String = "https://www.srcref.com",
    branch: String = "master",
    escapeHtml4: Boolean = false,
): String

Parameters

Parameter Type Default Description
account String — GitHub username or organization
repo String — Repository name
path String — File path in the repository
beginRegex String — Regex to find the start line
beginOccurrence Int 1 Which occurrence of the begin match (1-based)
beginOffset Int 0 Lines to offset from begin match
beginTopDown Boolean true true = top-down, false = bottom-up
endRegex String "" (empty) Regex to find the end line (empty = single line)
endOccurrence Int 1 Which occurrence of the end match
endOffset Int 0 Lines to offset from end match
endTopDown Boolean true Search direction for end match
prefix String https://www.srcref.com Base URL of the srcref service
branch String master Git branch name
escapeHtml4 Boolean false HTML-escape the output URL

Return Value

Returns a String containing the complete srcref URL. When visited, this URL will dynamically resolve the regex patterns and redirect to the corresponding GitHub permalink.

Examples

Basic Usage — Single Line

Highlight a single line by providing only the begin regex:

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

Line Range

Highlight a range of lines from begin to end pattern:

  val lineRange =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(CallLogging\\)",
      endRegex = "install\\(Compression\\)",
      endOffset = 3,
    )

Selecting the Nth Occurrence

When a pattern matches multiple lines, select which one:

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

Search from the end of the file backward — useful for finding the last occurrence of a pattern:

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

Line Offsets

Shift the highlight above or below the actual match:

  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,
    )

HTML-Escaped Output

When embedding a srcref URL in HTML, enable escaping to safely handle & characters:

  val htmlSafe =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "fun main",
      escapeHtml4 = true,
    )
  // Safe to embed directly in HTML: <a href="../$htmlSafe">link</a>

Custom Prefix and Branch

For self-hosted instances or non-default branches:

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

Complex Range Selection

Combine multiple parameters for precise targeting:

  val complexRange =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "fun Application\\.module\\(\\)",
      beginOffset = 0,
      endRegex = "configureRoutes\\(\\)",
      endOccurrence = 1,
      endOffset = 1,
      endTopDown = true,
    )

Use Cases

Embedding in Markdown Documentation

Generate links for use in README files or documentation:

  // Generate a link for use in Markdown documentation
  val markdownLink =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Api.kt",
      beginRegex = "fun srcrefUrl\\(",
      endRegex = "^\\ \\ \\)",
      endTopDown = false,
    )
  // In Markdown: [View the srcrefUrl() function]($markdownLink)

Embedding in HTML Pages

Use escapeHtml4 = true for safe HTML embedding:

  // Generate an HTML-escaped link for embedding in HTML pages
  val htmlLink =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Api.kt",
      beginRegex = "fun srcrefUrl\\(",
      escapeHtml4 = true,
    )
  // In HTML: <a href="../$htmlLink">View source</a>

Linking to Multiple Files

Create links to different files in the same repository:

  // You can create srcref URLs pointing to different files in the same repo
  val mainFile =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "fun main",
    )

  val routesFile =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Routes.kt",
      beginRegex = "fun Application\\.configureRoutes",
    )

  val urlsFile =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "object Urls",
    )

Linking to Presentation Slides

srcref was originally created for kslides, a Kotlin DSL for creating presentations. It enables presentation slides to link to live code that stays current:

val slideLink =
    srcrefUrl(
        account = "kslides",
        repo = "kslides",
        path = "kslides-core/src/main/kotlin/com/kslides/Presentation.kt",
        beginRegex = "srcrefUrl\\(",
        endRegex = "escapeHtml4 = true",
        endOffset = 1,
    )

URL Structure

The generated URL follows this format:

{prefix}/github?account={account}&repo={repo}&branch={branch}&path={path}&bregex={bregex}&boccur={boccur}&boffset={boffset}&btopd={btopd}[&eregex={eregex}&eoccur={eoccur}&eoffset={eoffset}&etopd={etopd}]
  • All parameter values are URL-encoded automatically
  • End parameters are omitted when endRegex is empty
  • The escapeHtml4 flag only affects the output string — it is not a URL parameter