added test and documentation

Author: epinzur

.gitignore

@@ -2,3 +2,5 @@
 *.pdf
 *_files/
 /.luarc.json
+
+/.quarto/

README.md

@@ -3,7 +3,7 @@
 Filter to include code from source files.
 
 The filter is largely inspired by
-[pandoc-include-code](https://github.com/owickstrom/pandoc-include-code).
+[pandoc-include-code](https://github.com/owickstrom/pandoc-include-code) and [sphinx-literalinclude](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude).
 
 ## Installing
 
@@ -41,18 +41,47 @@ You can still use other attributes, and classes, to control the code blocks:
     ```{.python include="script.py" code-line-numbers="true"}
     ```
 
+### 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
+in the dedent area).
+
+    ```{.python include="script.py" dedent=4}
+    ```
+
 ### Ranges
 
 If you want to include a specific range of lines, use `start-line` and `end-line`:
 
     ```{.python include="script.py" start-line=35 end-line=80}
     ```
 
-### Dedent
+#### New in Version 1.1
 
-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
-in the dedent area).
+`include-code-files` now supports additional attributes to specify ranges:
 
-    ```{.python include="script.py" dedent=4}
+* `start-after`: Start immediately after the specified line
+* `end-before`: End immediately before the specified line
+
+Furthermore, all range attributes (including `start-line` and `end-line`) now support both numeric and string values.
+
+Using string comments in code, in combination with the `start-after` and `end-before` range attributes allows for
+editing of the include file without requiring you to re-determine the proper numeric values after the changes are complete.
+
+For example, in this python file:
+
+    ```python
+    # [my_method start]
+    def my_method():
+        print("do work")
+    # [my_method end]
     ```
 
+To include just the method in your code block, you can do the following:
+
+    ```{.python include="script.py" start-after="[my_method start]" end-after="[my_method end]"}
+    ```
+
+Then as you edit your method, only the lines between `[my_method start]` and `[my_method end]` will be included in the output.
+
+Note that any combination of start and end attributes is supported. See the test setup in `index.qmd` for more examples.

_extensions/include-code-files/_extension.yml

@@ -1,9 +1,7 @@
 title: Include Code Files
 author: Bruno Beaufils
-version: 1.0.0
+version: 1.1.0
 quarto-required: ">=1.2"
 contributes:
   filters:
     - include-code-files.lua
-
-

_extensions/include-code-files/include-code-files.lua

@@ -62,8 +62,6 @@ local function transclude (cb)
       start = 1
     end
 
-    quarto.log.output("start: " .. start)
-
     -- set finish and skipLast based on end params
     if cb.attributes.endLine then
       finish = tonumber(cb.attributes.endLine)
@@ -80,18 +78,14 @@ local function transclude (cb)
       -- if no end specified, end at the last line
     end
 
-    quarto.log.output("finish: " .. finish)
-
     for line in fh:lines ("L")
     do
       number = number + 1
       -- if start or finish is a string, check if it exists on the current line
       if type(start) == "string" and string.find(line, start, 1, true) then
         start = number
-        quarto.log.output("convererted start to : " .. start)
       elseif type(finish) == "string" and string.find(line, finish, 1 , true) then
         finish = number
-        quarto.log.output("convererted finish to : " .. finish)
       end
 
       -- if haven't found start yet, then continue

_quarto.yml

@@ -0,0 +1,9 @@
+project:
+  type: website
+  output-dir: .quarto
+  preview:
+    browser: true
+    watch-inputs: true
+
+website:
+  title: "Quarto + Include-Code-Files"

index.qmd

@@ -0,0 +1,67 @@
+---
+title: Test of Include-Code-Files Quarto Extension
+filters:
+   - include-code-files
+---
+
+**In this post, we will show a simple implementation of `Tic-Tac-Toe` generated by ChatGPT4**
+
+Here is the initial class definition:
+
+```{.python include="tic_tac_toe.py" end-before="[TicTacToe init start]"}
+```
+
+
+Here is a short description of each method within the TicTacToe class in the provided Python file.
+
+
+1. `__init__(self)`: The constructor for the TicTacToe class. It initializes the game board as a 3x3 grid of spaces and sets the current player to 'X'.
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-after="[TicTacToe init start]" end-before="[TicTacToe init end]"}
+    ```
+
+1. `print_board(self)`: Prints the current state of the game board to the console, including the grid lines.
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-line="def print_board(self)" end-line=13}
+    ```
+
+1. `is_valid_move(self, row, col)`: Checks whether the specified move (by row and column indices) is valid; that is, if the chosen cell on the board is empty (' ').
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-line=15 end-line=16}
+    ```
+
+1. `place_mark(self, row, col)`: Places the current player's mark ('X' or 'O') on the board at the specified location if the move is valid, and returns False if the move is invalid (i.e., if the spot is already taken).
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-line=18 end-before=23}
+    ```
+
+1. `switch_player(self)`: Switches the current player from 'X' to 'O' or 'O' to 'X', toggling back and forth after each valid move.
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-after=23 end-line=25}
+    ```
+
+1. `check_winner(self)`: Checks all possible winning combinations (rows, columns, and diagonals) to see if either player has won the game. It returns the winning player's mark ('X' or 'O') if there is a winner, or None if there isn't one yet.
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-line=27 end-line="return None"}
+    ```
+
+1. `is_board_full(self)`: Checks whether the board is completely filled with players' marks; returns True if full, indicating a tie if there's no winner, or False if there are still empty spaces.
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-line=40 end-line=41}
+    ```
+
+1. `play_game(self)`: The main game loop that repeatedly asks the current player for their move, checks for a win or a tie, and switches players. This method controls the game flow, displaying the board and prompting the players until the game ends with a winner or a tie.
+
+    ```{.python include="tic_tac_toe.py" dedent=4 start-line="def play_game(self)" end-before="# Main game execution"}
+    ```
+
+Here is the main game execution:
+
+```{.python include="tic_tac_toe.py" start-after="# Main game execution"}
+```
+
+
+Finally, here is the full implementation:
+
+```{.python include="tic_tac_toe.py" code-line-numbers="true"}
+```

tic_tac_toe.py

@@ -0,0 +1,78 @@
+# tic_tac_toe.py
+
+class TicTacToe:
+    # [TicTacToe init start]
+    def __init__(self):
+        self.board = [[' ' for _ in range(3)] for _ in range(3)]
+        self.current_turn = 'X'
+    # [TicTacToe init end]
+
+    def print_board(self):
+        for row in self.board:
+            print('|'.join(row))
+            print('-'*5)
+
+    def is_valid_move(self, row, col):
+        return self.board[row][col] == ' '
+
+    def place_mark(self, row, col):
+        if not self.is_valid_move(row, col):
+            return False
+        self.board[row][col] = self.current_turn
+        return True
+
+    def switch_player(self):
+        self.current_turn = 'O' if self.current_turn == 'X' else 'X'
+
+    def check_winner(self):
+        # Check rows, columns and diagonals
+        for i in range(3):
+            if self.board[i][0] == self.board[i][1] == self.board[i][2] != ' ':
+                return self.board[i][0]
+            if self.board[0][i] == self.board[1][i] == self.board[2][i] != ' ':
+                return self.board[0][i]
+        if self.board[0][0] == self.board[1][1] == self.board[2][2] != ' ':
+            return self.board[0][0]
+        if self.board[0][2] == self.board[1][1] == self.board[2][0] != ' ':
+            return self.board[0][2]
+        return None
+
+    def is_board_full(self):
+        return all(self.board[row][col] != ' ' for row in range(3) for col in range(3))
+
+    def play_game(self):
+        while True:
+            self.print_board()
+
+            # Try to place a mark, if the move is invalid, retry.
+            try:
+                row = int(input(f"Player {self.current_turn}, enter your move row (0-2): "))
+                col = int(input(f"Player {self.current_turn}, enter your move column (0-2): "))
+            except ValueError:
+                print("Please enter numbers between 0 and 2.")
+                continue
+
+            if row < 0 or row > 2 or col < 0 or col > 2:
+                print("Invalid move. Try again.")
+                continue
+
+            if not self.place_mark(row, col):
+                print("This spot is taken. Try another spot.")
+                continue
+
+            winner = self.check_winner()
+            if winner:
+                self.print_board()
+                print(f"Player {winner} wins!")
+                break
+            elif self.is_board_full():
+                self.print_board()
+                print("It's a tie!")
+                break
+
+            self.switch_player()
+
+# Main game execution
+if __name__ == "__main__":
+    game = TicTacToe()
+    game.play_game()