sourcerer:0.1.0 (#221)

packages/preview/sourcerer/0.1.0/DOCS.md

@@ -0,0 +1,73 @@
+# Documentation
+The only function offered by this package is `code`, which renders a block of source code. It's only required parameter is `source`, which is a positional parameter and is expected to be raw text (`raw`). This block can additionally use a syntax specifier (`rs`, `py`, etc.) and it will be handled fine by the system.
+
+## Options
+### `line-spacing`: `length | relative`
+The spacing between lines of code and wrapped line sections.
+
+*Default*: `5pt`.
+
+### `line-offset`: `length | relative`
+The spacing between the line numbers to the lines.
+
+*Default*: `5pt`.
+
+### `numbering`: `bool`
+Wether to number the lines in the block. If `true`, the lines will be numbered. If numbering isn't used `line-offset` is ignored.
+
+*Default*: `true`.
+
+### `inset`: `length | relative`
+The inset of items in the code block, such as line numbers and lines of code.
+
+*Default*: `5pt`.
+
+### `radius`: `length | relative`
+The radius of the code block.
+
+*Default*: `3pt`.
+
+### `number-align`: `alignment`
+The alignment of the line numbers.
+
+*Default*: `left`.
+
+### `stroke`: `none | stroke`
+The stroke of the code block. If `none` is used, there will be no stroke.
+
+*Default*: `1pt + luma(180)`.
+
+### `fill`: `none | color | gradient`
+The filling of the code block. If `none` is used, there will be no filling.
+
+*Default*: `luma(250)`.
+
+### `text-style`: `dictionary`
+A dictionary of parameters to pass to the `text` function, used for rendering all text in the code block.
+
+*Default*: `()`.
+
+### `width`: `auto | length | relative`
+The width of the code block. Using `auto` means it will be scaled in accordance to the longest line.
+
+*Default*: `auto`.
+
+### `lines`: `auto | (int, int)`
+The line range to be displayed in the code block. Lines are specified here starting from `1`, and the range is inclusive. This means that in order to select lines `3` to `10`, we would use the array: `(3, 10)`.
+
+*Default*: `auto`.
+
+### `lang`: `none | str`
+The text shown inside of the top-right box, specifying the language used. The text can be of the full language name, so `Rust`, instead of `rs`, but that need not be. If `none` is used, the box won't be displayed.
+
+*Default*: `none`.
+
+### `lang-box`: `(radius: length | relative, outset: length | relative, fill: none | color | gradient, stroke: stroke | none)`
+Used to pass styling options to the top-right box showing the language used. `radius` controls the box radius, `outset`, its outset, `fill`, its fill and `stroke` its, stroke.
+
+*Default*: `(radius: 3pt, outset: 1.75pt, fill: rgb("#ffbfbf"), stroke: 1pt + rgb("#ff8a8a"))`
+
+## Notes
+- If any more customization is needed, feel free to open an issue or send a PR. These may not however be accepted, depending on their nature.
+- `sourcerer` uses the `"sourcerer"` `kind` for its figures, used for referencing lines. This means that using this same kind will cause issues in your documents.
+- It is recommended to use a `set` rule for the `code` function, for styling for example, the font used for rendering.

packages/preview/sourcerer/0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Yoav Grimland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/preview/sourcerer/0.1.0/README.md

@@ -0,0 +1,35 @@
+# Sourcerer
+Sourcerer is a Typst package for displaying stylized source code blocks, with some extra features. Main features include:
+
+- Rendering source code with numbering
+- Rendering only a range of lines from the source code, keeping the original highlighting of the code (For example, block comments are still rendered well, even if cut)
+- Adding in-code line labels which are easily referenceable (via `reference`)
+- Considerable customization options for the display of the code block
+- Consistent and pretty cutoff between pages
+- Displaying the language used for a code block in a readable manner, in-code-block
+
+# Usage
+First, import the package via:
+```typ
+#import "@preview/sourcerer:0.1.0": code
+```
+
+Then, display custom code blocks via the `code` function, like so:
+
+````typ
+#code(
+  lang: "Typst",
+  ```typ
+  Woah, that's pretty #smallcaps(cool)!
+  That's neat too.
+  ```
+)
+````
+
+This results in:
+
+<p align="center">
+  <img src="assets/sourcerer.png" width="750"/>
+</p>
+
+To view all of the options of the `code` function, consult the (documentation)[DOCS.md].

packages/preview/sourcerer/0.1.0/src/lib.typ

@@ -0,0 +1,115 @@
+#let code(
+  line-spacing: 5pt,
+  line-offset: 5pt,
+  numbering: true,
+  inset: 5pt,
+  radius: 3pt,
+  number-align: left,
+  stroke: 1pt + luma(180),
+  fill: luma(250),
+  text-style: (),
+  width: auto,
+  lines: auto,
+  lang: none,
+  lang-box: (
+    radius: 3pt,
+    outset: 1.75pt,
+    fill: rgb("#ffbfbf"),
+    stroke: 1pt + rgb("#ff8a8a")
+  ),
+  source
+) = {
+  show raw.line: set text(..text-style)
+  show raw: set text(..text-style)
+
+  set par(justify: false, leading: line-spacing)
+
+  let label-regex = regex("<((\w|_|-)+)>[ \t\r\f]*(\n|$)")
+
+  let labels = source
+    .text
+    .split("\n")
+    .map(line => {
+      let match = line.match(label-regex)
+
+      if match != none {
+        match.captures.at(0)
+      } else {
+        none
+      }
+    })
+
+  let unlabelled-source = source.text.replace(
+    label-regex,
+    "\n"
+  )
+
+  show raw.where(block: true): it => {
+    let lines = if lines == auto {
+      (0, it.lines.len())
+    } else {
+      (lines.at(0) - 1, lines.at(1))
+    }
+
+    block(
+      inset: inset,
+      radius: radius,
+      stroke: stroke,
+      fill: fill,
+      width: width,
+      { 
+        table(
+          columns: (auto, auto, 1fr),
+          inset: 0pt,
+          stroke: none,
+          column-gutter: (if numbering { line-offset } else { 0pt }, 0pt),
+          row-gutter: line-spacing,
+          align: (number-align, left, auto),
+          ..it
+            .lines
+            .slice(..lines)
+            .map(line => (
+              if numbering {
+                text(
+                  fill: stroke.paint,
+                  size: 1.25em,
+                  raw(str(line.number))
+                )
+              },
+              {
+                let line-label = labels.at(line.number - 1)
+
+                if line-label != none {
+                  show figure: it => it.body
+
+                  counter(figure.where(kind: "sourcerer")).update(line.number - 1)
+                  [
+                    #figure(supplement: "Line", kind: "sourcerer", outlined: false, line)
+                    #label(line-label)
+                  ]
+                } else {
+                  line
+                }
+              },
+              if line.number - 1 == lines.at(0) {
+                place(
+                  right + top,
+                  rect(
+                    fill: lang-box.fill,
+                    stroke: lang-box.stroke,
+                    inset: 0pt,
+                    outset: lang-box.outset,
+                    radius: radius,
+                    raw(lang)
+                  )
+                )
+              }
+            ))
+            .sum()
+        )
+      }
+    )
+  }
+
+  raw(block: true, lang: source.lang, unlabelled-source)
+}

packages/preview/sourcerer/0.1.0/typst.toml

@@ -0,0 +1,14 @@
+[package]
+name = "sourcerer"
+version = "0.1.0"
+authors = ["Yoav Grimland <[email protected]>"]
+license = "MIT"
+description = "Show code in a flexible, customizable way."
+repository = "https://github.com/miestrode/sourcerer"
+
+keywords = ["code", "sourcecode", "listing", "listings"]
+
+entrypoint = "src/lib.typ"
+compiler = "0.9.0"
+
+exclude = ["assets/*"]