pyrecli 0.3.5__tar.gz

pyrecli-0.3.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Amp63
+
+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.

pyrecli-0.3.5/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: pyrecli
+Version: 0.3.5
+Summary: Command line utilities for DiamondFire templates
+License-Expression: MIT
+License-File: LICENSE
+Keywords: diamondfire,minecraft,template,cli,tools
+Author: Amp
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: dev
+Requires-Dist: dfpyre (>=0.10.6)
+Requires-Dist: pytest (>=9.0.2) ; extra == "dev"
+Requires-Dist: rapidnbt (>=1.3.5)
+Requires-Dist: twine (>=6.2.0) ; extra == "dev"
+Project-URL: Repository, https://github.com/Amp63/pyrecli
+Description-Content-Type: text/markdown
+
+# pyrecli
+
+Command line utilities for DiamondFire templates
+
+## Installation
+
+Run the following command in a terminal:
+
+```sh
+pip install pyrecli
+```
+
+## Commands
+
+- `scan`: Scan all templates on the plot and dump them to a text file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `send`: Send template items to DiamondFire (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `rename`: Rename all occurences of a variable (including text codes)
+- `script`: Generate python scripts from template data
+- `grabinv`: Save all templates in your Minecraft inventory to a file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `docs`: Generate markdown documentation from template data
+- `slice`: Slice a template into multiple smaller templates
+- `cctoken`: Get a reusable CodeClient authentication token
+
+
+## What is this useful for?
+
+- Backing up a plot
+- Getting an accurate text representation of DF code
+- Open sourcing
+- Version control
+- Large scale refactoring
+
+
+## Example Command Usages
+
+### Scan
+
+**[Requires CodeClient]**
+
+Grabs all of the templates on your current plot and saves them to a file.
+You will need to run `/auth` in-game to authorize this action.
+
+Example:
+```sh
+# Dumps all template data into templates.dfts
+pyrecli scan templates.dfts
+```
+
+### Send
+
+**[Requires CodeClient]**
+
+Sends all templates in a file back to your inventory.
+
+Example:
+```sh
+pyrecli send templates.dfts
+```
+
+### Rename
+
+Renames all occurences of a variable in a list of templates.
+You can run this command on a single template, or on an entire plot if a variable is used in many places.
+
+This command still requires thorough testing, so make sure you have a backup of your plot before using this command on a large scale.
+
+Example:
+```sh
+# Changes all variables named `foo` to `bar`, then saves the new templates to 'renamed.dfts'.
+pyrecli rename templates.dfts renamed.dfts foo bar
+
+# You can also target a specific scope.
+# This changes all occurences of the game variable `plotData` to `gameData`.
+pyrecli rename templates.dfts renamed.dfts plotData gameData -s game
+```
+
+### Script
+
+Generates Python scripts from template data.
+
+Example:
+```sh
+# Convert templates into individual scripts and store them in directory `plot_templates`
+pyrecli script templates.dfts plot_templates
+
+# Convert templates into scripts and put them into a single file `plot_templates.py`
+pyrecli script templates.dfts plot_templates.py --onefile
+```
+
+
+### Grabinv
+
+**[Requires CodeClient]**
+
+Scans your inventory for templates and saves them to a file.
+
+Example:
+```sh
+# Save inventory templates to `templates.dfts`
+pyrecli grabinv templates.dfts
+```
+
+
+### Docs
+
+Generates a Markdown documentation file for a list of templates.
+
+Example:
+```sh
+# Generate documentation and save it to `plot_docs.md`
+pyrecli docs templates.dfts plot_docs.md "My Plot Docs"
+```
+
+
+### Slice
+
+Slices a single template into multiple smaller templates.
+This is useful for resizing templates to fit on a smaller plot.
+
+If multiple templates are passed, only the first one will be used.
+
+**NOTE: This feature is not fully implemented yet. Any templates with Control::Return blocks may not work properly if sliced.**
+
+Example:
+```sh
+# Slices the first template in `templates.dfts` with a target length of 50 and stores them in `sliced_templates.dfts`
+pyrecli slice templates.dfts sliced_templates.dfts 50
+```
+
+
+### CCToken
+
+Returns a CodeClient authentication token that can be used in commands that require CodeClient authorization.
+This is useful for reducing the amount of times you need to run `/auth`.
+
+Example:
+```sh
+# Get a token with the read_plot and inventory scopes
+pyrecli cctoken mytoken.txt "read_plot inventory"
+```
+
+
+### Command Chaining
+
+You can combine the pipe operator (`|`) with hyphen (`-`) file paths to chain multiple commands together.
+
+Example:
+```sh
+# Scans the plot, renames a variable, then sends renamed templates back to DiamondFire
+pyrecli scan - | pyrecli rename - foo bar | pyrecli send -
+
+```

pyrecli-0.3.5/README.md

@@ -0,0 +1,152 @@
+# pyrecli
+
+Command line utilities for DiamondFire templates
+
+## Installation
+
+Run the following command in a terminal:
+
+```sh
+pip install pyrecli
+```
+
+## Commands
+
+- `scan`: Scan all templates on the plot and dump them to a text file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `send`: Send template items to DiamondFire (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `rename`: Rename all occurences of a variable (including text codes)
+- `script`: Generate python scripts from template data
+- `grabinv`: Save all templates in your Minecraft inventory to a file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `docs`: Generate markdown documentation from template data
+- `slice`: Slice a template into multiple smaller templates
+- `cctoken`: Get a reusable CodeClient authentication token
+
+
+## What is this useful for?
+
+- Backing up a plot
+- Getting an accurate text representation of DF code
+- Open sourcing
+- Version control
+- Large scale refactoring
+
+
+## Example Command Usages
+
+### Scan
+
+**[Requires CodeClient]**
+
+Grabs all of the templates on your current plot and saves them to a file.
+You will need to run `/auth` in-game to authorize this action.
+
+Example:
+```sh
+# Dumps all template data into templates.dfts
+pyrecli scan templates.dfts
+```
+
+### Send
+
+**[Requires CodeClient]**
+
+Sends all templates in a file back to your inventory.
+
+Example:
+```sh
+pyrecli send templates.dfts
+```
+
+### Rename
+
+Renames all occurences of a variable in a list of templates.
+You can run this command on a single template, or on an entire plot if a variable is used in many places.
+
+This command still requires thorough testing, so make sure you have a backup of your plot before using this command on a large scale.
+
+Example:
+```sh
+# Changes all variables named `foo` to `bar`, then saves the new templates to 'renamed.dfts'.
+pyrecli rename templates.dfts renamed.dfts foo bar
+
+# You can also target a specific scope.
+# This changes all occurences of the game variable `plotData` to `gameData`.
+pyrecli rename templates.dfts renamed.dfts plotData gameData -s game
+```
+
+### Script
+
+Generates Python scripts from template data.
+
+Example:
+```sh
+# Convert templates into individual scripts and store them in directory `plot_templates`
+pyrecli script templates.dfts plot_templates
+
+# Convert templates into scripts and put them into a single file `plot_templates.py`
+pyrecli script templates.dfts plot_templates.py --onefile
+```
+
+
+### Grabinv
+
+**[Requires CodeClient]**
+
+Scans your inventory for templates and saves them to a file.
+
+Example:
+```sh
+# Save inventory templates to `templates.dfts`
+pyrecli grabinv templates.dfts
+```
+
+
+### Docs
+
+Generates a Markdown documentation file for a list of templates.
+
+Example:
+```sh
+# Generate documentation and save it to `plot_docs.md`
+pyrecli docs templates.dfts plot_docs.md "My Plot Docs"
+```
+
+
+### Slice
+
+Slices a single template into multiple smaller templates.
+This is useful for resizing templates to fit on a smaller plot.
+
+If multiple templates are passed, only the first one will be used.
+
+**NOTE: This feature is not fully implemented yet. Any templates with Control::Return blocks may not work properly if sliced.**
+
+Example:
+```sh
+# Slices the first template in `templates.dfts` with a target length of 50 and stores them in `sliced_templates.dfts`
+pyrecli slice templates.dfts sliced_templates.dfts 50
+```
+
+
+### CCToken
+
+Returns a CodeClient authentication token that can be used in commands that require CodeClient authorization.
+This is useful for reducing the amount of times you need to run `/auth`.
+
+Example:
+```sh
+# Get a token with the read_plot and inventory scopes
+pyrecli cctoken mytoken.txt "read_plot inventory"
+```
+
+
+### Command Chaining
+
+You can combine the pipe operator (`|`) with hyphen (`-`) file paths to chain multiple commands together.
+
+Example:
+```sh
+# Scans the plot, renames a variable, then sends renamed templates back to DiamondFire
+pyrecli scan - | pyrecli rename - foo bar | pyrecli send -
+
+```

pyrecli-0.3.5/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "pyrecli"
+version = "0.3.5"
+description = "Command line utilities for DiamondFire templates"
+authors = [
+    {name = "Amp"}
+]
+license = "MIT"
+readme = "README.md"
+keywords = ["diamondfire", "minecraft", "template", "cli", "tools"]
+
+requires-python = ">=3.10"
+dependencies = [
+    "dfpyre>=0.10.6",
+    "rapidnbt>=1.3.5"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.2",
+    "twine>=6.2.0"
+]
+
+[project.urls]
+Repository = "https://github.com/Amp63/pyrecli"
+
+
+[tool.poetry.scripts]
+pyrecli = "pyrecli.pyrecli:main"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

pyrecli-0.3.5/pyrecli/command/cctoken.py

@@ -0,0 +1,10 @@
+from pyrecli.util import connect_to_codeclient, write_output_file
+
+
+def cctoken_command(output_path: str, scopes: str):
+    ws = connect_to_codeclient(scopes)
+
+    ws.send('token')
+    token = ws.recv().replace('token ', '')
+
+    write_output_file(output_path, token)

pyrecli-0.3.5/pyrecli/command/docs.py

@@ -0,0 +1,115 @@
+from typing import Literal, TypedDict
+from dfpyre import DFTemplate, Item, Parameter
+from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string
+
+
+STARTER_BLOCK_LOOKUP = {
+    'func': 'Function',
+    'process': 'Process'
+}
+
+
+def escape_md(s: str) -> str:
+    MD_CHARS = r'*`$#!&^~'
+    for char in MD_CHARS:
+        s = s.replace(char, rf'\{char}')
+    return s
+
+
+class TemplateDocData(TypedDict):
+    template_type: Literal['Function', 'Process']
+    function_name: str
+    doc_lines: list[str]
+
+
+def docs_command(input_path: str, output_path: str, title: str, include_hidden: bool, omit_toc: bool):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
+
+    def get_function_name(template: DFTemplate) -> str:
+        first_block = template.codeblocks[0]
+        function_name = first_block.data.get('data')
+        return escape_md(function_name)
+
+    block_type_order = list(STARTER_BLOCK_LOOKUP.keys())
+    templates = [t for t in templates if t.codeblocks[0].action_name == 'dynamic']
+    templates.sort(key=get_function_name)
+    templates.sort(key=lambda t: block_type_order.index(t.codeblocks[0].type))
+
+    output_lines: list[str] = [
+        f'# {title}',
+        ''
+    ]
+
+    template_docs: list[TemplateDocData] = []
+    for template in templates:
+        first_block = template.codeblocks[0]
+
+        # Skip if hidden
+        if first_block.tags.get('Is Hidden') == 'True' and not include_hidden:
+            continue
+
+        # Add function / process name
+        template_type = STARTER_BLOCK_LOOKUP[first_block.type]
+        template_name = get_function_name(template)
+        template_doc_lines: list[str] = []      
+
+        template_doc_lines.append(f'## {template_type}: {template_name}')
+
+        # Parse description
+        if first_block.args:
+            first_arg = first_block.args[0]
+            if isinstance(first_arg, Item):
+                try:
+                    lore_text = [escape_md(l.to_string()) for l in first_arg.get_lore()]
+                    if lore_text:
+                        template_doc_lines.extend(lore_text)
+                except:
+                    # There are so many things that can go wrong here due to various legacy
+                    # item formats and weird MC string edge cases, so we can just skip
+                    # if there's a problem.
+                    pass
+            
+        # Parse parameters
+        parameter_lines: list[str] = []
+        for arg in first_block.args:
+            if isinstance(arg, Parameter):
+                optional_text = "*" if arg.optional else ""
+                default_value_text = f'= `{escape_md(arg.default_value.__repr__())}`' if arg.default_value else ''
+                parameter_lines.append(f'- *`{escape_md(arg.name)}{optional_text}`*: `{arg.param_type.get_string_value()}` {default_value_text}')
+                if arg.description:
+                    parameter_lines.append(f'  - {escape_md(arg.description)}')
+                if arg.note:
+                    parameter_lines.append(f'  - {escape_md(arg.note)}')
+        if parameter_lines:
+            template_doc_lines.append('')
+            template_doc_lines.append('### Parameters:')
+            template_doc_lines.extend(parameter_lines)
+        
+        doc_data = TemplateDocData(template_type=template_type, function_name=template_name, doc_lines=template_doc_lines)
+        template_docs.append(doc_data)
+    
+
+    # Add table of contents
+    def add_toc_group(doc_data_list: list[TemplateDocData], group_title: str):
+        if doc_data_list:
+            output_lines.append(f'### {group_title}')
+            for doc_data in doc_data_list:
+                link = f'#{doc_data["template_type"]}-{doc_data["function_name"]}'.lower().replace(' ', '-')
+                output_lines.append(f'- [{doc_data["function_name"]}]({link})')
+    
+    if not omit_toc:
+        output_lines.append('## Contents')
+        function_templates = [d for d in template_docs if d['template_type'] == 'Function']
+        add_toc_group(function_templates, 'Functions')
+        output_lines.append('')
+        process_templates = [d for d in template_docs if d['template_type'] == 'Process']
+        add_toc_group(process_templates, 'Processes')
+        output_lines.append('\n')
+
+    # Add template docs to output lines
+    for doc_data in template_docs:
+        output_lines.extend(doc_data['doc_lines'])
+        output_lines.append('')
+    
+    write_output_file(output_path, '\n'.join(output_lines))

pyrecli-0.3.5/pyrecli/command/grabinv.py

@@ -0,0 +1,44 @@
+import json
+from rapidnbt import nbtio, CompoundTagVariant
+from pyrecli.util import write_output_file, connect_to_codeclient, print_status
+
+
+def grabinv_command(output_path: str, token: str|None=None):
+    ws = connect_to_codeclient('inventory', token)
+
+    ws.send('inv')
+    inventory = ws.recv()
+    ws.close()
+
+    inventory = f'{{inventory:{inventory}}}'
+    inventory_nbt = nbtio.loads_snbt(inventory)
+
+    template_codes: list[str] = []
+    for tag in inventory_nbt['inventory']:
+        tag: CompoundTagVariant
+        components = tag['components']
+        if components.is_null():
+            continue
+
+        custom_data = components['minecraft:custom_data']
+        if custom_data.is_null():
+            continue
+            
+        pbv_tag = custom_data['PublicBukkitValues']
+        if pbv_tag.is_null():
+            continue
+        
+        code_template_data = pbv_tag['hypercube:codetemplatedata']
+        if code_template_data.is_null():
+            continue
+        
+        code_template_json = json.loads(code_template_data.get_string())
+        
+        template_code = code_template_json.get('code')
+        if template_code:
+            template_codes.append(template_code)
+
+    if not template_codes:
+        print_status('Could not find any templates in the inventory.')
+
+    write_output_file(output_path, '\n'.join(template_codes))

pyrecli-0.3.5/pyrecli/command/rename.py

@@ -0,0 +1,53 @@
+from typing import Literal
+import re
+from dfpyre import Variable, Number, String, Text, Parameter
+from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string
+
+
+TEXT_CODE_PATTERNS = [
+    re.compile(r"%var\(([a-zA-Z0-9!@#$%^&*~`\-_=+\\|;':\",.\/<>? ]+)\)"),
+    re.compile(r"%index\(([a-zA-Z0-9!@#$%^&*~`\-_=+\\|;':\",.\/<>? ]+),\d+\)"),
+    re.compile(r"%entry\(([a-zA-Z0-9!@#$%^&*~`\-_=+\\|;':\",.\/<>? ]+),[a-zA-Z0-9!@#$%^&*~`\-_=+\\|;':\",.\/<>? ]+\)")
+]
+
+
+def rename_var_in_text_code(s: str, var_to_rename: str, new_var_name: str):
+    for pattern in TEXT_CODE_PATTERNS:
+        match = pattern.search(s)
+        if match and match.group(1) == var_to_rename:
+            s = s.replace(match.group(1), new_var_name)
+    return s
+
+
+def rename_command(input_path: str, output_path: str,
+                   var_to_rename: str, new_var_name: str,
+                   var_to_rename_scope: Literal['game', 'saved', 'local', 'line']|None):
+    
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
+
+    for template in templates:
+        for codeblock in template.codeblocks:
+            for argument in codeblock.args:
+                # Try to rename variable
+                if isinstance(argument, Variable):
+                    if argument.name == var_to_rename and (var_to_rename_scope is None or argument.scope == var_to_rename_scope):
+                        argument.name = new_var_name
+                    argument.name = rename_var_in_text_code(argument.name, var_to_rename, new_var_name)
+                
+                # Try to rename parameter
+                elif isinstance(argument, Parameter) and var_to_rename_scope == 'line':
+                    if argument.name == var_to_rename:
+                        argument.name = new_var_name
+                
+                # Check for occurrences of the variable in text codes
+                elif isinstance(argument, (Number, String, Text)) and isinstance(argument.value, str):
+                    argument.value = rename_var_in_text_code(argument.value, var_to_rename, new_var_name)
+            
+            # Check for text codes in function calls
+            if codeblock.type in {'call_func', 'start_process'}:
+                new_data = rename_var_in_text_code(codeblock.data.get('data'), var_to_rename, new_var_name)
+                codeblock.data['data'] = new_data
+    
+    new_file_content = '\n'.join(t.build() for t in templates)
+    write_output_file(output_path, new_file_content)

pyrecli-0.3.5/pyrecli/command/scan.py

@@ -0,0 +1,14 @@
+from pyrecli.util import write_output_file, connect_to_codeclient, print_status
+
+
+def scan_command(output_path: str, token: str|None=None):
+    ws = connect_to_codeclient('read_plot', token)
+
+    print_status('Scanning plot...')
+    ws.send('scan')
+
+    scan_results = ws.recv()
+    print_status('Done.')
+    ws.close()
+
+    write_output_file(output_path, scan_results)

pyrecli-0.3.5/pyrecli/command/script.py

@@ -0,0 +1,36 @@
+import os
+from dfpyre import DFTemplate
+from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string
+
+
+def write_to_directory(dir_name: str, templates: list[DFTemplate], flags: dict[str, int|bool]):
+    if not os.path.isdir(dir_name):
+        os.mkdir(dir_name)
+    
+    for template in templates:
+        script_path = f'{dir_name}/{template.get_template_name()}.py'
+        script_string = template.generate_script(**flags)
+        with open(script_path, 'w') as f:
+            f.write(script_string)
+
+
+def write_to_single_file(file_path: str, templates: list[DFTemplate], flags: dict[str, int|bool]):
+    file_content = []
+    for i, template in enumerate(templates):
+        if i == 0:
+            template_script = template.generate_script(include_import=True, assign_variable=True, **flags)
+        else:
+            template_script = template.generate_script(include_import=False, assign_variable=True, **flags)
+        file_content.append(template_script)
+    
+    write_output_file(file_path, '\n\n'.join(file_content))
+
+
+def script_command(input_path: str, output_path: str, one_file: bool, flags: dict[str, int|bool]):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
+    
+    if one_file or output_path == '-':
+        return write_to_single_file(output_path, templates, flags)
+    
+    return write_to_directory(output_path, templates, flags)

pyrecli-0.3.5/pyrecli/command/send.py

@@ -0,0 +1,16 @@
+from pyrecli.util import connect_to_codeclient, read_input_file, parse_templates_from_string, print_status
+
+
+def send_command(input_path: str):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
+
+    ws = connect_to_codeclient()
+
+    for template in templates:
+        item = template.generate_template_item()
+        ws.send(f'give {item.get_snbt()}')
+    
+    ws.close()
+    
+    print_status(f'Sent {len(templates)} template{"s" if len(templates) != 1 else ''} successfully.')

pyrecli-0.3.5/pyrecli/command/slice.py

@@ -0,0 +1,15 @@
+from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string, NoTemplatesError
+
+
+def slice_command(input_path: str, output_path: str, target_length: int):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
+
+    if not templates:
+        raise NoTemplatesError(f'Could not find any templates in {input_path}')
+    
+    first_template = templates[0]
+    sliced_templates = first_template.slice(target_length)
+    built_templates = [t.build() for t in sliced_templates]
+
+    write_output_file(output_path, '\n'.join(built_templates))

pyrecli-0.3.5/pyrecli/pyrecli.py

@@ -0,0 +1,132 @@
+import sys
+import argparse
+import importlib.metadata
+
+from pyrecli.command.scan import scan_command
+from pyrecli.command.send import send_command
+from pyrecli.command.script import script_command
+from pyrecli.command.rename import rename_command
+from pyrecli.command.grabinv import grabinv_command
+from pyrecli.command.docs import docs_command
+from pyrecli.command.slice import slice_command
+from pyrecli.command.cctoken import cctoken_command
+from pyrecli.util import print_status
+
+
+def rename_target_scope(value):
+    SCOPES = {'game', 'saved', 'local', 'line'}
+    if value not in SCOPES:
+        raise argparse.ArgumentTypeError(f'Expected one of {SCOPES} for rename target scope')
+    return value
+
+
+def slice_target_length(value):
+    MINIMUM_LENGTH = 5
+    ivalue = int(value)
+    if ivalue < MINIMUM_LENGTH:
+        raise argparse.ArgumentTypeError(f'Target length must be at least {MINIMUM_LENGTH} codeblocks')
+    return ivalue
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog='pyrecli', description='Command line utilities for DiamondFire templates')
+    parser.add_argument('--version', '-v', action='version', version=f'pyrecli {importlib.metadata.version('pyrecli')}')
+    subparsers = parser.add_subparsers(dest='command', help='Available commands:', required=True, metavar='<command>')
+
+    parser_scan = subparsers.add_parser('scan', help='Scan the current plot templates with CodeClient')
+    parser_scan.add_argument('output_path', help='The file to output template data to', type=str)
+    parser_scan.add_argument('--token', '-t', help='The CodeClient authentication token to use', type=str, default=None)
+
+    parser_send = subparsers.add_parser('send', help='Send templates to DiamondFire with CodeClient')
+    parser_send.add_argument('input_path', help='The file containing template data', type=str)
+
+    parser_script = subparsers.add_parser('script', help='Create python scripts from template data')
+    parser_script.add_argument('input_path', help='The file containing template data', type=str)
+    parser_script.add_argument('output_path', help='The file or directory to output to', type=str)
+    parser_script.add_argument('--onefile', help='Output template data as a single script', action='store_true')
+    parser_script.add_argument('--indent_size', '-i', help='The multiple of spaces to add when indenting lines', type=int, default=4)
+    parser_script.add_argument('--literal_shorthand', '-ls', help='Output Text and Number items as strings and ints respectively', action='store_false')
+    parser_script.add_argument('--var_shorthand', '-vs', help='Write all variables using variable shorthand', action='store_true')
+    parser_script.add_argument('--preserve_slots', '-s', help='Save the positions of items within chests', action='store_true')
+    parser_script.add_argument('--build_and_send', '-b', help='Add `.build_and_send()` to the end of the generated template(s)', action='store_true')
+
+    parser_rename = subparsers.add_parser('rename', help='Rename all occurrences of a variable')
+    parser_rename.add_argument('input_path', help='The file containing template data', type=str)
+    parser_rename.add_argument('output_path', help='The file to output to', type=str)
+    parser_rename.add_argument('var_to_rename', help='The variable to rename', type=str)
+    parser_rename.add_argument('new_var_name', help='The new name for the variable', type=str)
+    parser_rename.add_argument('--var_scope', '-s', help='The scope to match', type=rename_target_scope, default=None)
+
+    parser_grabinv = subparsers.add_parser('grabinv', help='Save all templates in the inventory to a file with CodeClient')
+    parser_grabinv.add_argument('output_path', help='The file to output template data to', type=str)
+    parser_grabinv.add_argument('--token', '-t', help='The CodeClient authentication token to use', type=str, default=None)
+
+    parser_docs = subparsers.add_parser('docs', help='Generate markdown documentation from template data')
+    parser_docs.add_argument('input_path', help='The file containing template data', type=str)
+    parser_docs.add_argument('output_path', help='The file to output to', type=str)
+    parser_docs.add_argument('--title', '-t', help='The title for the docs', type=str, default='Template Docs')
+    parser_docs.add_argument('--include_hidden', '-ih', help='Include hidden functions and processes', action='store_true')
+    parser_docs.add_argument('--notoc', help='Omit the table of contents', action='store_true')
+
+    parser_slice = subparsers.add_parser('slice', help='Slice a template into multiple smaller templates')
+    parser_slice.add_argument('input_path', help='The file containing template data', type=str)
+    parser_slice.add_argument('output_path', help='The file to output template data to', type=str)
+    parser_slice.add_argument('target_length', help='The maximum length of each sliced template', type=slice_target_length)
+
+    parser_cctoken = subparsers.add_parser('cctoken', help='Request a CodeClient token with the specified scopes')
+    parser_cctoken.add_argument('output_path', help='The file to output the token to', type=str)
+    parser_cctoken.add_argument('scopes', help='The scopes to request', type=str)
+
+
+    parsed_args = parser.parse_args()
+
+    try:
+        match parsed_args.command:
+            case 'scan':
+                scan_command(parsed_args.output_path, parsed_args.token)
+            
+            case 'send':
+                send_command(parsed_args.input_path)
+            
+            case 'script':
+                scriptgen_flags = {
+                    'indent_size': parsed_args.indent_size, 
+                    'literal_shorthand': parsed_args.literal_shorthand,
+                    'var_shorthand': parsed_args.var_shorthand,
+                    'preserve_slots': parsed_args.preserve_slots,
+                    'build_and_send': parsed_args.build_and_send
+                }
+                script_command(parsed_args.input_path, parsed_args.output_path, parsed_args.onefile, scriptgen_flags)
+            
+            case 'rename':
+                rename_command(
+                    parsed_args.input_path, parsed_args.output_path,
+                    parsed_args.var_to_rename, parsed_args.new_var_name, parsed_args.var_scope
+                )
+            
+            case 'grabinv':
+                grabinv_command(parsed_args.output_path, parsed_args.token)
+            
+            case 'docs':
+                docs_command(
+                    parsed_args.input_path, parsed_args.output_path,
+                    parsed_args.title, parsed_args.include_hidden, parsed_args.notoc
+                )
+            
+            case 'slice':
+                slice_command(
+                    parsed_args.input_path, parsed_args.output_path,
+                    parsed_args.target_length
+                )
+            
+            case 'cctoken':
+                cctoken_command(parsed_args.output_path, parsed_args.scopes)
+    
+    except Exception as e:
+        print_status(e)
+        return 1
+    
+    return 0
+
+if __name__ == '__main__':
+    sys.exit(main())

pyrecli-0.3.5/pyrecli/util.py

@@ -0,0 +1,132 @@
+import os
+import re
+import sys
+import websocket
+from dfpyre import DFTemplate
+
+
+CODECLIENT_URL = 'ws://localhost:31375'
+
+BASE64_REGEX = re.compile(r'^[A-Za-z0-9+/]+={0,2}$')
+
+class TemplateParsingError(Exception):
+    """Exception class for DFTemplate parsing errors"""
+
+class NoTemplatesError(Exception):
+    """Exception class for empty template list"""
+
+
+def print_status(*args, **kwargs):
+    """Prints a message to stderr"""
+    print(*args, **kwargs, file=sys.stderr)
+
+
+def connect_to_codeclient(scopes: str|None=None, token: str|None=None) -> websocket.WebSocket:
+    """
+    Tries to connect to the CodeClient websocket server with the specified scopes.
+
+    Args:
+        scopes: The scopes to request
+        token: The CodeClient authentication token to use
+
+    Returns:
+        The connected websocket
+
+    Raises:
+        ConnectionRefusedError: If connection to the server could not be established
+        PermissionError: If scope authentication fails
+    """
+    ws = websocket.WebSocket()
+    ws.connect(CODECLIENT_URL)
+    
+    print_status('Connected to CodeClient.')
+
+    if token:
+        ws.send(f'token {token}')
+        auth_message = ws.recv()
+    elif scopes:
+        print_status('Please run /auth in game.')
+        ws.send(f'scopes {scopes}')
+        auth_message = ws.recv()
+    
+    if (token or scopes):
+        if auth_message != 'auth':
+            raise PermissionError('Failed to authenticate.')
+        else:
+            print_status('Authentication successful.')
+    
+    return ws
+
+
+def parse_templates_from_string(templates: str) -> list[DFTemplate]:
+    """
+    Parses a newline-delimited string of template codes into a list of templates.
+    
+    Args:
+        templates: The string of templates to parse
+    
+    Returns:
+        The list of parsed templates
+    
+    Raises:
+        ValueError: If a template code is not a valid base64 string
+        TemplateParsingError: If a template failed to parse
+    """
+    template_codes = templates.split('\n')
+    
+    for i, template_code in enumerate(template_codes):
+        if not BASE64_REGEX.match(template_code):
+            raise ValueError(f'Template code at line {i+1} is not a base64 string.')
+    
+    try:
+        return [DFTemplate.from_code(c) for c in template_codes]
+    except Exception as e:
+        raise TemplateParsingError(f'Error while parsing template: {e}') from None
+
+
+def read_input_file(path: str) -> str:
+    """
+    Returns the string content of the file at a specified path.
+    If the path is a hyphen ('-'), then input will be read from stdin.
+
+    Args:
+        path: The file path to read
+    
+    Returns:
+        The file content or input from stdin
+    
+    Raises:
+        FileNotFoundError: If the path is not a file or the file doesn't exist
+        OSError: If the file was unable to be opened or read
+    """
+    if path == '-':
+        try:
+            input_string = sys.stdin.read()
+        except EOFError:
+            pass
+        return input_string.strip()
+    
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f'"{path}" is not a file.')
+    
+    with open(path, 'r') as f:
+        return f.read()
+
+
+def write_output_file(path: str, content: str):
+    """
+    Writes string content to a specified file.
+    If the file path is a hyphen ('-') then the content will be printed to stdout.
+
+    Args:
+        path: The file path to write to
+        content: The string content to write
+    
+    Raises:
+        OSError: If the file was unable to be accessed
+    """
+    if path == '-':
+        print(content, end='')
+    else:
+        with open(path, 'w') as f:
+            f.write(content)