pyrecli 0.1.0__tar.gz

pyrecli-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.1
+Name: pyrecli
+Version: 0.1.0
+Summary: Command line utilities for DiamondFire templates
+Home-page: https://github.com/Amp63/pyrecli
+License: MIT
+Keywords: diamondfire,minecraft,template,cli
+Author: Amp
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Project-URL: Repository, https://github.com/Amp63/pyrecli
+Description-Content-Type: text/markdown
+
+# pyrecli
+
+Command line utilities for DiamondFire templates
+
+## 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
+
+
+## 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 Usage
+
+These two commands will scan your plot, convert each template into a python script, then place the scripts into a directory called `myplot`.
+
+```sh
+pyrecli scan templates.dfts
+pyrecli script templates.dfts myplot
+```
+
+If you prefer the templates to be outputted to a single file, use the `--onefile` flag:
+
+```sh
+pyrecli scan templates.dfts
+pyrecli script templates.dfts myplot.py --onefile
+```
+
+For more information about generating scripts, run `pyrecli script -h`.
+

pyrecli-0.1.0/README.md

@@ -0,0 +1,40 @@
+# pyrecli
+
+Command line utilities for DiamondFire templates
+
+## 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
+
+
+## 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 Usage
+
+These two commands will scan your plot, convert each template into a python script, then place the scripts into a directory called `myplot`.
+
+```sh
+pyrecli scan templates.dfts
+pyrecli script templates.dfts myplot
+```
+
+If you prefer the templates to be outputted to a single file, use the `--onefile` flag:
+
+```sh
+pyrecli scan templates.dfts
+pyrecli script templates.dfts myplot.py --onefile
+```
+
+For more information about generating scripts, run `pyrecli script -h`.

pyrecli-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "pyrecli"
+version = "0.1.0"
+description = "Command line utilities for DiamondFire templates"
+authors = ["Amp"]
+readme = "README.md"
+license = "MIT"
+repository = "https://github.com/Amp63/pyrecli"
+keywords = ["diamondfire", "minecraft", "template", "cli"]
+
+
+[tool.poetry.dependencies]
+python = "^3.10"
+
+
+[tool.poetry.scripts]
+pyrecli = "pyrecli.pyrecli:main"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

pyrecli-0.1.0/pyrecli/command/docs.py

@@ -0,0 +1,120 @@
+from typing import Literal, TypedDict
+from result import Result, Ok, Err
+from dfpyre import DFTemplate, Item, Parameter
+from mcitemlib.itemlib import MCItemlibException
+from pyrecli.util import parse_templates_from_file
+
+
+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) -> Result[None, str]:
+    templates_result = parse_templates_from_file(input_path)
+    if templates_result.is_err():
+        return Err(templates_result.err_value)
+    templates = templates_result.ok_value
+
+    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 MCItemlibException:
+                    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('')
+    
+    with open(output_path, 'w') as f:
+        f.write('\n'.join(output_lines))
+    
+    return Ok(None)

pyrecli-0.1.0/pyrecli/command/grabinv.py

@@ -0,0 +1,49 @@
+import json
+from result import Result, Ok, Err
+import amulet_nbt
+from amulet_nbt import CompoundTag, StringTag
+from pyrecli.util import connect_to_codeclient
+
+
+def grabinv_command(output_path: str) -> Result[None, str]:
+    ws_result = connect_to_codeclient('inventory')
+    if ws_result.is_err():
+        return Err(ws_result.err_value)
+    ws = ws_result.ok_value
+
+    ws.send('inv')
+    inventory = ws.recv()
+    inventory_nbt = amulet_nbt.from_snbt(inventory)
+
+    template_codes: list[str] = []
+    for tag in inventory_nbt:
+        components: CompoundTag = tag.get('components')
+        if components is None:
+            continue
+
+        custom_data: CompoundTag = components.get('minecraft:custom_data')
+        if custom_data is None:
+            continue
+            
+        pbv_tag: CompoundTag = custom_data.get('PublicBukkitValues')
+        if pbv_tag is None:
+            continue
+        
+        code_template_data: StringTag = pbv_tag.get('hypercube:codetemplatedata')
+        if code_template_data is None:
+            continue
+        
+        code_template_json = json.loads(str(code_template_data))
+        
+        template_code = code_template_json.get('code')
+        if template_code:
+            template_codes.append(template_code)
+
+    if not template_codes:
+        return Err('Could not find any templates in the inventory.')
+
+    with open(output_path, 'w') as f:
+        f.write('\n'.join(template_codes))
+    
+    print(f'Saved {len(template_codes)} template{"s" if len(template_codes) != 1 else ''} to "{output_path}".')
+    return Ok(None)

pyrecli-0.1.0/pyrecli/command/rename.py

@@ -0,0 +1,54 @@
+from typing import Literal
+import re
+from result import Result, Ok, Err
+from dfpyre import Variable, Number, String, Text
+from pyrecli.util import parse_templates_from_file
+
+
+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|None,
+                   var_to_rename: str, new_var_name: str,
+                   renamed_var_scope: Literal['game', 'saved', 'local', 'line']|None) -> Result[None, str]:
+    templates_result = parse_templates_from_file(input_path)
+    if templates_result.is_err():
+        return Err(templates_result.err_value)
+    templates = templates_result.ok_value
+
+    for template in templates:
+        for codeblock in template.codeblocks:
+            for argument in codeblock.args:
+                if isinstance(argument, Variable):
+                    if argument.name == var_to_rename:
+                        if renamed_var_scope is None:
+                            argument.name = new_var_name
+                        elif argument.scope != renamed_var_scope:
+                            argument.name = new_var_name
+                    argument.name = rename_var_in_text_code(argument.name, var_to_rename, new_var_name)
+                
+                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)
+            
+            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_path = output_path if output_path else input_path
+    with open(write_path, 'w') as f:
+        f.write(new_file_content)
+    
+    return Ok(None)

pyrecli-0.1.0/pyrecli/command/scan.py

@@ -0,0 +1,24 @@
+from result import Result, Ok, Err
+from pyrecli.util import connect_to_codeclient
+
+
+def scan_command(output_path: str) -> Result[None, str]:
+    ws_result = connect_to_codeclient('read_plot')
+    if ws_result.is_err():
+        return Err(ws_result.err_value)
+    ws = ws_result.ok_value
+
+    print('Scanning plot...')
+    ws.send('scan')
+
+    scan_results = ws.recv()
+    print('Done.')
+    ws.close()
+
+    with open(output_path, 'w') as f:
+        f.write(scan_results)
+
+    amount_templates = scan_results.count('\n')
+    print(f'Scanned {amount_templates} template{"s" if amount_templates != 1 else ''} successfully.')
+    
+    return Ok(None)

pyrecli-0.1.0/pyrecli/command/script.py

@@ -0,0 +1,42 @@
+import os
+from result import Result, Ok, Err
+from dfpyre import DFTemplate
+from pyrecli.util import parse_templates_from_file
+
+
+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)
+
+    with open(file_path, 'w') as f:
+        f.write('\n\n'.join(file_content))
+
+
+def script_command(input_path: str, output_path: str, one_file: bool, flags: dict[str, int|bool]) -> Result[None, str]:
+    templates_result = parse_templates_from_file(input_path)
+    if templates_result.is_err():
+        return Err(templates_result.err_value)
+    templates = templates_result.ok_value
+    
+    if one_file:
+        write_to_single_file(output_path, templates, flags)
+    else:
+        write_to_directory(output_path, templates, flags)
+
+    return Ok(None)

pyrecli-0.1.0/pyrecli/command/send.py

@@ -0,0 +1,22 @@
+from result import Result, Ok, Err
+from pyrecli.util import connect_to_codeclient, parse_templates_from_file
+
+
+def send_command(input_path: str) -> Result[None, str]:
+    templates_result = parse_templates_from_file(input_path)
+    if templates_result.is_err():
+        return Err(templates_result.err_value)
+    templates = templates_result.ok_value
+
+    ws_result = connect_to_codeclient()
+    if ws_result.is_err():
+        return Err(ws_result.err_value)
+    ws = ws_result.ok_value
+
+    for template in templates:
+        item = template.generate_template_item()
+        ws.send(f'give {item.get_snbt()}')
+    
+    ws.close()
+    print(f'Sent {len(templates)} template{"s" if len(templates) != 1 else ''} successfully.')
+    return Ok(None)

pyrecli-0.1.0/pyrecli/pyrecli.py

@@ -0,0 +1,90 @@
+import sys
+import argparse
+
+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
+
+
+def main():
+    parser = argparse.ArgumentParser(prog='pyrecli', description='Command line utilities for DiamondFire templates')
+    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_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 a variable')
+    parser_rename.add_argument('input_path', help='The file containing template data', 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_to_rename_scope', '-s', help='The scope to match', type=str, default=None)
+    parser_rename.add_argument('--output_path', '-o', help='The file or directory to output to', type=str, 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_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 or directory to output to', type=str)
+    parser_docs.add_argument('title', help='The title for the docs', type=str)
+    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')
+
+    parsed_args = parser.parse_args()
+
+    match parsed_args.command:
+        case 'scan':
+            command_result = scan_command(parsed_args.output_path)
+        
+        case 'send':
+            command_result = 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
+            }
+            command_result = script_command(parsed_args.input_path, parsed_args.output_path, parsed_args.onefile, scriptgen_flags)
+        
+        case 'rename':
+            command_result = rename_command(
+                parsed_args.input_path, parsed_args.output_path,
+                parsed_args.var_to_rename, parsed_args.new_var_name, parsed_args.var_to_rename_scope
+            )
+        
+        case 'grabinv':
+            command_result = grabinv_command(parsed_args.output_path)
+        
+        case 'docs':
+            command_result = docs_command(
+                parsed_args.input_path, parsed_args.output_path,
+                parsed_args.title, parsed_args.include_hidden, parsed_args.notoc
+            )
+    
+    if command_result.is_err():
+        print(command_result.err_value)
+        sys.exit(1)
+    
+    sys.exit(0)
+
+if __name__ == '__main__':
+    main()

pyrecli-0.1.0/pyrecli/util.py

@@ -0,0 +1,48 @@
+import os
+import re
+from result import Result, Ok, Err
+import websocket
+from dfpyre import DFTemplate
+
+
+CODECLIENT_URL = 'ws://localhost:31375'
+
+BASE64_REGEX = re.compile(r'^[A-Za-z0-9+/]+={0,2}$')
+
+
+def connect_to_codeclient(scopes: str|None=None) -> Result[websocket.WebSocket, str]:
+    ws = websocket.WebSocket()
+    try:
+        ws.connect(CODECLIENT_URL)
+    except ConnectionRefusedError:
+        return Err('Failed to connect to CodeClient.')
+    
+    print('Connected to CodeClient.')
+
+    if scopes:
+        print('Please run /auth in game.')
+        ws.send(f'scopes {scopes}')
+        auth_message = ws.recv()
+
+        if auth_message != 'auth':
+            return Err('Failed to authenticate.')
+        print('Authentication received.')
+    
+    return Ok(ws)
+
+
+def parse_templates_from_file(path: str) -> Result[list[DFTemplate], str]:
+    if not os.path.isfile(path):
+        return Err(f'"{path}" is not a file.')
+    
+    with open(path, 'r') as f:
+        template_codes = f.read().split('\n')
+    
+    for i, template_code in enumerate(template_codes):
+        if not BASE64_REGEX.match(template_code):
+            return Err(f'Template code at line {i+1} is not a base64 string.')
+    
+    try:
+        return Ok([DFTemplate.from_code(c) for c in template_codes])
+    except Exception as e:
+        return Err(str(e))