Skip to content

Commit 7cbd1ea

Browse files
miestrodemiestrode
authored
sourcerer:0.1.0 (#221)
1 parent dcbb9f6 commit 7cbd1ea

File tree

6 files changed

+258
-0
lines changed

6 files changed

+258
-0
lines changed

‎packages/preview/sourcerer/0.1.0/DOCS.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Documentation
2+
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.
3+
4+
## Options
5+
### `line-spacing`: `length | relative`
6+
The spacing between lines of code and wrapped line sections.
7+
8+
*Default*: `5pt`.
9+
10+
### `line-offset`: `length | relative`
11+
The spacing between the line numbers to the lines.
12+
13+
*Default*: `5pt`.
14+
15+
### `numbering`: `bool`
16+
Wether to number the lines in the block. If `true`, the lines will be numbered. If numbering isn't used `line-offset` is ignored.
17+
18+
*Default*: `true`.
19+
20+
### `inset`: `length | relative`
21+
The inset of items in the code block, such as line numbers and lines of code.
22+
23+
*Default*: `5pt`.
24+
25+
### `radius`: `length | relative`
26+
The radius of the code block.
27+
28+
*Default*: `3pt`.
29+
30+
### `number-align`: `alignment`
31+
The alignment of the line numbers.
32+
33+
*Default*: `left`.
34+
35+
### `stroke`: `none | stroke`
36+
The stroke of the code block. If `none` is used, there will be no stroke.
37+
38+
*Default*: `1pt + luma(180)`.
39+
40+
### `fill`: `none | color | gradient`
41+
The filling of the code block. If `none` is used, there will be no filling.
42+
43+
*Default*: `luma(250)`.
44+
45+
### `text-style`: `dictionary`
46+
A dictionary of parameters to pass to the `text` function, used for rendering all text in the code block.
47+
48+
*Default*: `()`.
49+
50+
### `width`: `auto | length | relative`
51+
The width of the code block. Using `auto` means it will be scaled in accordance to the longest line.
52+
53+
*Default*: `auto`.
54+
55+
### `lines`: `auto | (int, int)`
56+
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)`.
57+
58+
*Default*: `auto`.
59+
60+
### `lang`: `none | str`
61+
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.
62+
63+
*Default*: `none`.
64+
65+
### `lang-box`: `(radius: length | relative, outset: length | relative, fill: none | color | gradient, stroke: stroke | none)`
66+
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.
67+
68+
*Default*: `(radius: 3pt, outset: 1.75pt, fill: rgb("#ffbfbf"), stroke: 1pt + rgb("#ff8a8a"))`
69+
70+
## Notes
71+
- 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.
72+
- `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.
73+
- 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

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

‎packages/preview/sourcerer/0.1.0/README.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Sourcerer
2+
Sourcerer is a Typst package for displaying stylized source code blocks, with some extra features. Main features include:
3+
4+
- Rendering source code with numbering
5+
- 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)
6+
- Adding in-code line labels which are easily referenceable (via `reference`)
7+
- Considerable customization options for the display of the code block
8+
- Consistent and pretty cutoff between pages
9+
- Displaying the language used for a code block in a readable manner, in-code-block
10+
11+
# Usage
12+
First, import the package via:
13+
```typ
14+
#import "@preview/sourcerer:0.1.0": code
15+
```
16+
17+
Then, display custom code blocks via the `code` function, like so:
18+
19+
````typ
20+
#code(
21+
lang: "Typst",
22+
```typ
23+
Woah, that's pretty #smallcaps(cool)!
24+
That's neat too.
25+
```
26+
)
27+
````
28+
29+
This results in:
30+
31+
<p align="center">
32+
<img src="assets/sourcerer.png" width="750"/>
33+
</p>
34+
35+
To view all of the options of the `code` function, consult the (documentation)[DOCS.md].

‎packages/preview/sourcerer/0.1.0/assets/sourcerer.png

40.4 KB
Loading

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

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
#let code(
2+
line-spacing: 5pt,
3+
line-offset: 5pt,
4+
numbering: true,
5+
inset: 5pt,
6+
radius: 3pt,
7+
number-align: left,
8+
stroke: 1pt + luma(180),
9+
fill: luma(250),
10+
text-style: (),
11+
width: auto,
12+
lines: auto,
13+
lang: none,
14+
lang-box: (
15+
radius: 3pt,
16+
outset: 1.75pt,
17+
fill: rgb("#ffbfbf"),
18+
stroke: 1pt + rgb("#ff8a8a")
19+
),
20+
source
21+
) = {
22+
show raw.line: set text(..text-style)
23+
show raw: set text(..text-style)
24+
25+
set par(justify: false, leading: line-spacing)
26+
27+
let label-regex = regex("<((\w|_|-)+)>[ \t\r\f]*(\n|$)")
28+
29+
let labels = source
30+
.text
31+
.split("\n")
32+
.map(line => {
33+
let match = line.match(label-regex)
34+
35+
if match != none {
36+
match.captures.at(0)
37+
} else {
38+
none
39+
}
40+
})
41+
42+
let unlabelled-source = source.text.replace(
43+
label-regex,
44+
"\n"
45+
)
46+
47+
show raw.where(block: true): it => {
48+
let lines = if lines == auto {
49+
(0, it.lines.len())
50+
} else {
51+
(lines.at(0) - 1, lines.at(1))
52+
}
53+
54+
block(
55+
inset: inset,
56+
radius: radius,
57+
stroke: stroke,
58+
fill: fill,
59+
width: width,
60+
{
61+
table(
62+
columns: (auto, auto, 1fr),
63+
inset: 0pt,
64+
stroke: none,
65+
column-gutter: (if numbering { line-offset } else { 0pt }, 0pt),
66+
row-gutter: line-spacing,
67+
align: (number-align, left, auto),
68+
..it
69+
.lines
70+
.slice(..lines)
71+
.map(line => (
72+
if numbering {
73+
text(
74+
fill: stroke.paint,
75+
size: 1.25em,
76+
raw(str(line.number))
77+
)
78+
},
79+
{
80+
let line-label = labels.at(line.number - 1)
81+
82+
if line-label != none {
83+
show figure: it => it.body
84+
85+
counter(figure.where(kind: "sourcerer")).update(line.number - 1)
86+
[
87+
#figure(supplement: "Line", kind: "sourcerer", outlined: false, line)
88+
#label(line-label)
89+
]
90+
} else {
91+
line
92+
}
93+
},
94+
if line.number - 1 == lines.at(0) {
95+
place(
96+
right + top,
97+
rect(
98+
fill: lang-box.fill,
99+
stroke: lang-box.stroke,
100+
inset: 0pt,
101+
outset: lang-box.outset,
102+
radius: radius,
103+
raw(lang)
104+
)
105+
)
106+
}
107+
))
108+
.sum()
109+
)
110+
}
111+
)
112+
}
113+
114+
raw(block: true, lang: source.lang, unlabelled-source)
115+
}

‎packages/preview/sourcerer/0.1.0/typst.toml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[package]
2+
name = "sourcerer"
3+
version = "0.1.0"
4+
authors = ["Yoav Grimland <[email protected]>"]
5+
license = "MIT"
6+
description = "Show code in a flexible, customizable way."
7+
repository = "https://github.com/miestrode/sourcerer"
8+
9+
keywords = ["code", "sourcecode", "listing", "listings"]
10+
11+
entrypoint = "src/lib.typ"
12+
compiler = "0.9.0"
13+
14+
exclude = ["assets/*"]

0 commit comments

Comments
 (0)