diff --git a/LICENSE b/LICENSE index ebbf1ee39fcffb51e890d86acd58a9e8d8f663b9..136ea649d19a1b9c1f4af5377a92e1b5353b04a1 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright © 2020–2022 Bruno BEAUFILS, 2022 Sam Edwardes. +Copyright © 2020–2022 Bruno BEAUFILS. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/Makefile b/Makefile index 0f363ffed297d337ac5f8b75ce07b46b8feadc54..fd16158525cbf23a43f4d162df7b23525a58d89b 100644 --- a/Makefile +++ b/Makefile @@ -13,16 +13,13 @@ FILTER_FILE := include-code-files.lua # Name of the filter, *without* `.lua` file extension FILTER_NAME = $(patsubst %.lua,%,$(FILTER_FILE)) -# Directory containing the Quarto extension -QUARTO_EXT_DIR = _extensions/$(FILTER_NAME) - -# Current version (the latest tag). Used for quarto extension +# Current version (the latest tag). VERSION = $(shell git tag --sort=-version:refname --merged | head -n1 | \ sed -e 's/^v//' | tr -d "\n") ## Show available targets -# Comments preceding "simple" targets (those which do not user macro -# name) and introduced by two dashes are used as their describtion. +# Comments preceding "simple" targets (those which do not use macro +# name) and introduced by two dashes are used as their description. .PHONY: help help: @tabs 22 ; $(SED) -ne \ @@ -46,23 +43,9 @@ test/expected.native: $(FILTER_FILE) test/input.md test/test.yml test/output.html: $(FILTER_FILE) test/input.md $(PANDOC) -s --lua-filter=$< test/input.md --output=$@ -## Creates or updates the quarto extension -.PHONY: quarto-extension -quarto-extension: $(QUARTO_EXT_DIR)/_extension.yml \ - $(QUARTO_EXT_DIR)/$(FILTER_FILE) - -$(QUARTO_EXT_DIR): - mkdir -p $@ - -# This may change, so re-create the file every time -.PHONY: $(QUARTO_EXT_DIR)/_extension.yml -$(QUARTO_EXT_DIR)/_extension.yml: _extensions/$(FILTER_NAME) - @printf 'Updating %s\n' $@ - @sed -i -e 's/^version:.*$$/version: $(VERSION)/' $@ - ## Sets a new release using VERSION .PHONY: release -release: quarto-extension +release: git commit -am "Release $(FILTER_NAME) $(VERSION)" git tag v$(VERSION) -m "$(FILTER_NAME) $(VERSION)" diff --git a/README.md b/README.md index a915530f2c9d147049663f2b599302ea65a79b27..891ce3b34bd374095a34e471bfb9143ac9d4a3c7 100644 --- a/README.md +++ b/README.md @@ -11,15 +11,14 @@ This repository exists thanks to the work of [Albert KREWINKEL](https://github.com/tarleb/) among other things in [pandoc/lua-filters](https://github.com/pandoc/lua-filters/issues/207). -## Quick Start - -The `include-code-files` filter supports pandoc and quarto. +If you are a Quarto user, please use the official extension from the Quarto team: +<https://github.com/quarto-ext/include-code-files>. -### Pandoc +## Quick Start Install the extension whether by simply downloading the -[include-code-files.lua](_extensions/include-code-files/include-code-files.lua) -file somewhere on your computer or by cloning this repository: +[include-code-files.lua](include-code-files.lua) file somewhere on +your computer or by cloning this repository: ```bash git clone https://github.com/b3/include-code-files.git @@ -38,35 +37,9 @@ When rendering include the path to `include-code-files.lua` pandoc -s --lua-filter=include-code-files.lua test/input.md --output test/output.html ``` -For complete details see the [Lua filter for pandoc](#lua-filter-for-pandoc) section below. - -### Quarto - -Install the extension: - -```bash -quarto add b3/include-code-files@quarto -``` - -Use the extension in any `.qmd` file by including the filter in the YAML front matter. - -``````markdown ---- -filters: - - include-code-files ---- - -```{.python include="_snippets/hello_world.py"} -``` -`````` - -For complete details see the [Extension for Quarto](#extension-for-quarto) section below. - - - -## Lua filter for pandoc +For complete details see following sections below. -### Installing +## Installing The filter can be used without special installation, just by passing the `include-code-files.lua` file path to pandoc via @@ -77,12 +50,12 @@ filters directory of pandoc's user data directory. This allows to use the filter just by using the filename, without having to specify the full file path. -### Using +## Using The filter recognizes code blocks with the `include` attribute present. It swaps the content of the code block with contents from a file. -#### Including Files +### Including Files The simplest way to use this filter is to include an entire file: @@ -94,7 +67,7 @@ You can still use other attributes, and classes, to control the code blocks: ```{.c include="hello.c" numberLines} ``` -#### Ranges +### Ranges If you want to include a specific range of lines, use `startLine` and `endLine`: @@ -103,7 +76,7 @@ If you want to include a specific range of lines, use `startLine` and `endLine`: `start-line` and `end-line` alternatives are also recognized. -#### Dedent +### Dedent Using the `dedent` attribute, you can have whitespaces removed on each line, where possible (non-whitespace character will not be removed even if they occur @@ -121,69 +94,9 @@ location in the source file. ```{include="hello.c" startLine=35 endLine=80 .numberLines} ``` -### Example +## Example An HTML version of [input.md](test/input.md) can be produced as [output.html](test/output.html) with this command: pandoc -s --lua-filter=include-code-files.lua test/input.md --output test/output.html - - -## Extension for Quarto - - - - -### Installing - -```bash -quarto add b3/include-code-files -``` - -This will install the extension under the `_extensions` -subdirectory. You will want to check in this directory if you're using -version control. - -### Using - -To use the include-code-files filter, add it to your documents YAML -front matter: - -```yaml ---- -title: "My doc" -filters: - - include-code-files ---- -``` - -With the include-code-files filter, you can include code snippets -directly from a file using `include`. For example, you may have a -python script like this: - -```python -# _snippets/hello_world.py -for name in ["Sam", "Jake"]: - print(f"Hello {name}!") -``` - -To render this file in a code chunk, use the `include` attribute: - -``````markdown -```{.python include="_snippets/hello_world.py"} -``` -`````` - -You can combine this with other quarto attributes like `filename` or `code-line-numbers`: - -``````markdown -```{.python include="_snippets/hello_world.py" filename="hello_world.py" code-line-numbers="true"} -``` -`````` - -### Example - -Here is the source code for a minimal example: -[examples/quarto/index.qmd](examples/quarto/index.qmd). See a rendered sample here: -<https://samedwardes.quarto.pub/example-for-include-code-files-filter/>. - diff --git a/_extensions/include-code-files/_extension.yml b/_extensions/include-code-files/_extension.yml deleted file mode 100644 index 94b2271a097fabd0afa1a95e5e7c41768d416563..0000000000000000000000000000000000000000 --- a/_extensions/include-code-files/_extension.yml +++ /dev/null @@ -1,7 +0,0 @@ -name: include-code-files -author: Bruno Beaufils, Sam Edwardes -version: 1.0.0 -quarto-required: ">=1.2.0" -contributes: - filters: - - include-code-files.lua diff --git a/_extensions/include-code-files/include-code-files.lua b/_extensions/include-code-files/include-code-files.lua deleted file mode 100644 index 5a5269ca0686a0c3e66f3a20907a12bc5a75ce7d..0000000000000000000000000000000000000000 --- a/_extensions/include-code-files/include-code-files.lua +++ /dev/null @@ -1,62 +0,0 @@ ---- include-code-files.lua – filter to include code from source files ---- ---- Copyright: © 2020 Bruno BEAUFILS ---- License: MIT – see LICENSE file for details - ---- Dedent a line -local function dedent (line, n) - return line:sub(1,n):gsub(" ","") .. line:sub(n+1) -end - ---- Filter function for code blocks -local function transclude (cb) - if cb.attributes.include then - local content = "" - local fh = io.open(cb.attributes.include) - if not fh then - io.stderr:write("Cannot open file " .. cb.attributes.include .. " | Skipping includes\n") - else - local number = 1 - local start = 1 - - -- change hyphenated attributes to PascalCase - for i,pascal in pairs({"startLine", "endLine"}) - do - local hyphen = pascal:gsub("%u", "-%0"):lower() - if cb.attributes[hyphen] then - cb.attributes[pascal] = cb.attributes[hyphen] - cb.attributes[hyphen] = nil - end - end - - if cb.attributes.startLine then - cb.attributes.startFrom = cb.attributes.startLine - start = tonumber(cb.attributes.startLine) - end - for line in fh:lines ("L") - do - if cb.attributes.dedent then - line = dedent(line, cb.attributes.dedent) - end - if number >= start then - if not cb.attributes.endLine or number <= tonumber(cb.attributes.endLine) then - content = content .. line - end - end - number = number + 1 - end - fh:close() - end - -- remove key-value pair for used keys - cb.attributes.include = nil - cb.attributes.startLine = nil - cb.attributes.endLine = nil - cb.attributes.dedent = nil - -- return final code block - return pandoc.CodeBlock(content, cb.attr) - end -end - -return { - { CodeBlock = transclude } -} diff --git a/examples/quarto/.gitignore b/examples/quarto/.gitignore deleted file mode 100644 index 1d07bcfcd3aa2d11832ebcee9c36647274d9f3b2..0000000000000000000000000000000000000000 --- a/examples/quarto/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -index.html -index_files/* diff --git a/examples/quarto/_extensions/b3/include-code-files/_extension.yml b/examples/quarto/_extensions/b3/include-code-files/_extension.yml deleted file mode 100644 index 787b412b960f6cd9ff1b719b5e593fe4b86d58fe..0000000000000000000000000000000000000000 --- a/examples/quarto/_extensions/b3/include-code-files/_extension.yml +++ /dev/null @@ -1,7 +0,0 @@ -name: include-code-files -author: Sam Edwardes -version: 1.0.0 -quarto-required: ">=1.2.0" -contributes: - filters: - - include-code-files.lua diff --git a/examples/quarto/_extensions/b3/include-code-files/include-code-files.lua b/examples/quarto/_extensions/b3/include-code-files/include-code-files.lua deleted file mode 100644 index 5a5269ca0686a0c3e66f3a20907a12bc5a75ce7d..0000000000000000000000000000000000000000 --- a/examples/quarto/_extensions/b3/include-code-files/include-code-files.lua +++ /dev/null @@ -1,62 +0,0 @@ ---- include-code-files.lua – filter to include code from source files ---- ---- Copyright: © 2020 Bruno BEAUFILS ---- License: MIT – see LICENSE file for details - ---- Dedent a line -local function dedent (line, n) - return line:sub(1,n):gsub(" ","") .. line:sub(n+1) -end - ---- Filter function for code blocks -local function transclude (cb) - if cb.attributes.include then - local content = "" - local fh = io.open(cb.attributes.include) - if not fh then - io.stderr:write("Cannot open file " .. cb.attributes.include .. " | Skipping includes\n") - else - local number = 1 - local start = 1 - - -- change hyphenated attributes to PascalCase - for i,pascal in pairs({"startLine", "endLine"}) - do - local hyphen = pascal:gsub("%u", "-%0"):lower() - if cb.attributes[hyphen] then - cb.attributes[pascal] = cb.attributes[hyphen] - cb.attributes[hyphen] = nil - end - end - - if cb.attributes.startLine then - cb.attributes.startFrom = cb.attributes.startLine - start = tonumber(cb.attributes.startLine) - end - for line in fh:lines ("L") - do - if cb.attributes.dedent then - line = dedent(line, cb.attributes.dedent) - end - if number >= start then - if not cb.attributes.endLine or number <= tonumber(cb.attributes.endLine) then - content = content .. line - end - end - number = number + 1 - end - fh:close() - end - -- remove key-value pair for used keys - cb.attributes.include = nil - cb.attributes.startLine = nil - cb.attributes.endLine = nil - cb.attributes.dedent = nil - -- return final code block - return pandoc.CodeBlock(content, cb.attr) - end -end - -return { - { CodeBlock = transclude } -} diff --git a/examples/quarto/_publish.yml b/examples/quarto/_publish.yml deleted file mode 100644 index a4f8a3f21450820d53953d31cecf1cc15963df04..0000000000000000000000000000000000000000 --- a/examples/quarto/_publish.yml +++ /dev/null @@ -1,4 +0,0 @@ -- source: index.qmd - quarto-pub: - - id: 509ab2f5-de97-45f6-b5e8-bb1304c1797d - url: 'https://quartopub.com/sites/samedwardes/example-for-include-code-files-filter' diff --git a/examples/quarto/_snippets/hello_world.py b/examples/quarto/_snippets/hello_world.py deleted file mode 100644 index db02c4a37db502b20bf466ef236bc7d95821b1ba..0000000000000000000000000000000000000000 --- a/examples/quarto/_snippets/hello_world.py +++ /dev/null @@ -1,2 +0,0 @@ -for name in ["Sam", "Jake"]: - print(f"Hello {name}!") \ No newline at end of file diff --git a/examples/quarto/index.qmd b/examples/quarto/index.qmd deleted file mode 100644 index 4cc4cec7aa4ec668eb19a6e4861669ac8199f535..0000000000000000000000000000000000000000 --- a/examples/quarto/index.qmd +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Example for include-code-files filter" -filters: - - include-code-files ---- - -With the include-code-files filter, you can include code snippets directly from a file using the `include` attribute. - -```{.python include="_snippets/hello_world.py"} -``` - -You can combine this with other quarto attributes like `filename` or `code-line-numbers`: - -```{.python include="_snippets/hello_world.py" filename="hello_world.py" code-line-numbers="true"} -``` \ No newline at end of file diff --git a/examples/quarto/screenshot.png b/examples/quarto/screenshot.png deleted file mode 100644 index ab1ae76e57c379d73a06259241f3a358c1f0a3d5..0000000000000000000000000000000000000000 Binary files a/examples/quarto/screenshot.png and /dev/null differ diff --git a/include-code-files.lua b/include-code-files.lua deleted file mode 120000 index 79c5f32e9c9090b90257b96dfc662e577a592134..0000000000000000000000000000000000000000 --- a/include-code-files.lua +++ /dev/null @@ -1 +0,0 @@ -_extensions/include-code-files/include-code-files.lua \ No newline at end of file diff --git a/include-code-files.lua b/include-code-files.lua new file mode 100644 index 0000000000000000000000000000000000000000..5a5269ca0686a0c3e66f3a20907a12bc5a75ce7d --- /dev/null +++ b/include-code-files.lua @@ -0,0 +1,62 @@ +--- include-code-files.lua – filter to include code from source files +--- +--- Copyright: © 2020 Bruno BEAUFILS +--- License: MIT – see LICENSE file for details + +--- Dedent a line +local function dedent (line, n) + return line:sub(1,n):gsub(" ","") .. line:sub(n+1) +end + +--- Filter function for code blocks +local function transclude (cb) + if cb.attributes.include then + local content = "" + local fh = io.open(cb.attributes.include) + if not fh then + io.stderr:write("Cannot open file " .. cb.attributes.include .. " | Skipping includes\n") + else + local number = 1 + local start = 1 + + -- change hyphenated attributes to PascalCase + for i,pascal in pairs({"startLine", "endLine"}) + do + local hyphen = pascal:gsub("%u", "-%0"):lower() + if cb.attributes[hyphen] then + cb.attributes[pascal] = cb.attributes[hyphen] + cb.attributes[hyphen] = nil + end + end + + if cb.attributes.startLine then + cb.attributes.startFrom = cb.attributes.startLine + start = tonumber(cb.attributes.startLine) + end + for line in fh:lines ("L") + do + if cb.attributes.dedent then + line = dedent(line, cb.attributes.dedent) + end + if number >= start then + if not cb.attributes.endLine or number <= tonumber(cb.attributes.endLine) then + content = content .. line + end + end + number = number + 1 + end + fh:close() + end + -- remove key-value pair for used keys + cb.attributes.include = nil + cb.attributes.startLine = nil + cb.attributes.endLine = nil + cb.attributes.dedent = nil + -- return final code block + return pandoc.CodeBlock(content, cb.attr) + end +end + +return { + { CodeBlock = transclude } +}