minecraft-datapack-language 15.4.8__tar.gz → 15.4.9__tar.gz

{minecraft_datapack_language-15.4.8/minecraft_datapack_language.egg-info → minecraft_datapack_language-15.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minecraft-datapack-language
-Version: 15.4.8
+Version: 15.4.9
 Summary: Compile JavaScript-style MDL language or Python API into a Minecraft datapack (1.21+ ready). Features variables, control flow, error handling, and VS Code extension.
 Project-URL: Homepage, https://www.mcmdl.com
 Project-URL: Documentation, https://www.mcmdl.com/docs

minecraft_datapack_language-15.4.9/docs/_data/version.yml

@@ -0,0 +1,3 @@
+current: "15.4.8"
+tag: "v15.4.8"
+updated_at: "2025-09-02T03:01:58Z"

{minecraft_datapack_language-15.4.8 → minecraft_datapack_language-15.4.9}/minecraft_datapack_language/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '15.4.8'
-__version_tuple__ = version_tuple = (15, 4, 8)
+__version__ = version = '15.4.9'
+__version_tuple__ = version_tuple = (15, 4, 9)
 
-__commit_id__ = commit_id = 'g4c6f03513'
+__commit_id__ = commit_id = 'g01b2b393b'

{minecraft_datapack_language-15.4.8 → minecraft_datapack_language-15.4.9}/minecraft_datapack_language/cli_build.py

@@ -13,7 +13,7 @@ from .mdl_parser_js import parse_mdl_js
 from .expression_processor import ExpressionProcessor
 from .dir_map import get_dir_map
 from .pack import Pack, Namespace, Function, Tag, Recipe, Advancement, LootTable, Predicate, ItemModifier, Structure
-from .mdl_errors import MDLErrorCollector, create_error, MDLFileError, MDLSyntaxError, MDLParserError, MDLLexerError
+from .mdl_errors import MDLErrorCollector, create_error, MDLBuildError, MDLFileError, MDLCompilationError, MDLSyntaxError, MDLParserError, MDLLexerError
 from .cli_utils import ensure_dir, write_json, _process_variable_substitutions, _convert_condition_to_minecraft_syntax, _find_mdl_files, _validate_selector, _resolve_selector, _extract_base_variable_name, _slugify
 from .cli_colors import (
     print_success, print_warning, print_error, print_info,
@@ -70,7 +70,7 @@ def _merge_mdl_files(files: List[Path], verbose: bool = False, error_collector:
     except Exception as e:
         if error_collector:
             error_collector.add_error(create_error(
-                MDLSyntaxError,
+                MDLCompilationError,
                 f"Failed to parse {files[0]}: {str(e)}",
                 file_path=str(files[0]),
                 suggestion="Check the file syntax and ensure it's a valid MDL file."
@@ -142,12 +142,12 @@ def _merge_mdl_files(files: List[Path], verbose: bool = False, error_collector:
             return None
         except Exception as e:
             if error_collector:
-                            error_collector.add_error(create_error(
-                MDLSyntaxError,
-                f"Failed to parse {file_path}: {str(e)}",
-                file_path=str(file_path),
-                suggestion="Check the file syntax and ensure it's a valid MDL file."
-            ))
+                error_collector.add_error(create_error(
+                    MDLCompilationError,
+                    f"Failed to parse {file_path}: {str(e)}",
+                    file_path=str(file_path),
+                    suggestion="Check the file syntax and ensure it's a valid MDL file."
+                ))
             else:
                 raise
             return None
@@ -1058,7 +1058,7 @@ def build_mdl(input_path: str, output_path: str, verbose: bool = False, pack_for
         error_collector.add_error(e)
         error_collector.print_errors(verbose=True, ignore_warnings=ignore_warnings)
         error_collector.raise_if_errors()
-    except MDLFileError as e:
+    except MDLBuildError as e:
         error_collector.add_error(e)
         error_collector.print_errors(verbose=True, ignore_warnings=ignore_warnings)
         error_collector.raise_if_errors()
@@ -1066,13 +1066,13 @@ def build_mdl(input_path: str, output_path: str, verbose: bool = False, pack_for
         error_collector.add_error(e)
         error_collector.print_errors(verbose=True, ignore_warnings=ignore_warnings)
         error_collector.raise_if_errors()
-    except MDLSyntaxError as e:
+    except MDLCompilationError as e:
         error_collector.add_error(e)
         error_collector.print_errors(verbose=True, ignore_warnings=ignore_warnings)
         error_collector.raise_if_errors()
     except Exception as e:
         error_collector.add_error(create_error(
-            MDLFileError,
+            MDLBuildError,
             f"Unexpected error during build: {str(e)}",
             suggestion="Check the input files and try again. If the problem persists, report this as a bug."
         ))

minecraft_datapack_language-15.4.9/minecraft_datapack_language/cli_help.py

@@ -0,0 +1,431 @@
+"""
+CLI Help System - Comprehensive help documentation for MDL CLI
+"""
+
+
+def show_main_help():
+    """Display the main help message for the MDL CLI."""
+    try:
+        from . import __version__
+        version = __version__
+    except ImportError:
+        version = "unknown"
+    
+    print(f"""
+[GAME] MDL (Minecraft Datapack Language) CLI - v{version}
+====================================================
+
+MDL is a simplified language for creating Minecraft datapacks with variables, 
+control structures, and easy syntax. This CLI tool compiles MDL files into 
+standard Minecraft datapacks.
+
+[CMD] Available Commands:
+=====================
+
+[BUILD] build    - Compile MDL files into a Minecraft datapack
+[CHECK] check    - Validate MDL files for syntax and semantic errors  
+[NEW] new      - Create a new MDL project with template files
+
+[DOC] Detailed Help:
+================
+
+For detailed information about any command, use:
+  mdl <command> --help
+
+Examples:
+  mdl build --help    - Show build command options
+  mdl check --help    - Show check command options
+  mdl new --help      - Show new project options
+
+[NEXT] Quick Start:
+==============
+
+1. Create a new project:
+   mdl new my_project
+
+2. Build your datapack:
+   mdl build --mdl my_project.mdl -o dist
+
+3. Check for errors:
+   mdl check my_project.mdl
+
+[INFO] Documentation:
+================
+
+• Language Reference: https://www.mcmdl.com/docs/language-reference
+• CLI Reference: https://www.mcmdl.com/docs/cli-reference
+• Examples: https://www.mcmdl.com/docs/examples
+
+🐛 Error Reporting:
+==================
+
+MDL provides detailed error messages with:
+• Exact file location (line, column)
+• Context lines showing the problematic code
+• Helpful suggestions for fixing issues
+• Multiple error collection and reporting
+
+For support and bug reports, visit: https://github.com/aaron777collins/MinecraftDatapackLanguage
+""")
+
+
+def show_build_help():
+    """Display detailed help for the build command."""
+    print("""
+[BUILD] MDL Build Command - Compile MDL Files to Minecraft Datapacks
+===============================================================
+
+The build command compiles MDL files into standard Minecraft datapacks that can 
+be loaded directly into Minecraft.
+
+[CMD] Usage:
+========
+
+  mdl build --mdl <input> -o <output> [options]
+
+[DIR] Arguments:
+============
+
+  --mdl, -m <input>     Input MDL file or directory containing .mdl files
+                        Examples: --mdl project.mdl, --mdl src/, --mdl .
+
+  -o, --output <output> Output directory for the generated datapack
+                        Example: -o dist, -o build/my_pack
+
+[OPT] Options:
+==========
+
+  --verbose, -v         Enable verbose output with detailed build information
+                        Shows file parsing, function generation, and progress
+
+  --pack-format <num>   Override the pack format number in pack.mcmeta
+                        Default: 82 (Minecraft 1.20+)
+                        Example: --pack-format 15 (for older versions)
+
+  --wrapper <name>      Create a zip file with the specified name
+                        Example: --wrapper my_awesome_pack
+
+  --ignore-warnings     Suppress warning messages during build
+                        Only show errors, hide all warnings
+
+[EX] Examples:
+===========
+
+1. Build a single MDL file:
+   mdl build --mdl hello_world.mdl -o dist
+
+2. Build all MDL files in a directory:
+   mdl build --mdl src/ -o build/my_pack
+
+3. Build current directory with verbose output:
+   mdl build --mdl . -o dist --verbose
+
+4. Build with custom pack format and zip wrapper:
+   mdl build --mdl project.mdl -o dist --pack-format 15 --wrapper my_pack
+
+5. Build multiple files in a directory:
+   mdl build --mdl examples/ -o output --verbose
+
+[OUT] Output Structure:
+===================
+
+The build command creates a standard Minecraft datapack structure:
+
+  output/
+  ├── pack.mcmeta              # Datapack metadata
+  └── data/
+      ├── <namespace>/         # Your datapack namespace
+      │   └── function/        # Generated functions
+      │       ├── load.mcfunction
+      │       └── *.mcfunction
+      └── minecraft/
+          └── tags/
+              └── function/    # Load/tick tags
+                  ├── load.json
+                  └── tick.json
+
+[FEAT] Features:
+===========
+
+• Multi-file compilation - Merge multiple .mdl files into one datapack
+• Variable system - Automatic scoreboard objective creation
+• Control structures - If/else statements and while loops
+• Function calls - Call other functions within your datapack
+• Raw commands - Use native Minecraft commands with $variable$ substitution
+• Error handling - Detailed error reporting with suggestions
+• Progress tracking - Verbose mode shows build progress
+
+[CHECK] Error Handling:
+=================
+
+The build command provides comprehensive error reporting:
+• Syntax errors with exact line and column numbers
+• Context lines showing the problematic code
+• Helpful suggestions for fixing issues
+• Multiple error collection (won't stop on first error)
+
+For more information, visit: https://www.mcmdl.com/docs/cli-reference#build
+""")
+
+
+def show_check_help():
+    """Display detailed help for the check command."""
+    print("""
+[CHECK] MDL Check Command - Validate MDL Files for Errors
+====================================================
+
+The check command validates MDL files for syntax errors, semantic issues, and 
+potential problems without generating any output files.
+
+[CMD] Usage:
+========
+
+  mdl check <input> [options]
+
+[DIR] Arguments:
+============
+
+  <input>               Input MDL file or directory containing .mdl files
+                        Examples: project.mdl, src/, .
+
+[OPT] Options:
+==========
+
+  --verbose, -v         Enable verbose output with detailed validation information
+                        Shows parsing steps, token analysis, and detailed error context
+
+  --ignore-warnings     Suppress warning messages during check
+                        Only show errors, hide all warnings
+
+[EX] Examples:
+===========
+
+1. Check a single MDL file:
+   mdl check hello_world.mdl
+
+2. Check all MDL files in a directory:
+   mdl check src/
+
+3. Check current directory with verbose output:
+   mdl check . --verbose
+
+4. Check multiple files:
+   mdl check examples/ --verbose
+
+[CHECK] Validation Types:
+===================
+
+The check command performs comprehensive validation:
+
+[EX] Syntax Validation:
+• Lexical analysis - Token recognition and validation
+• Parsing - AST construction and syntax structure
+• Grammar validation - Language rule compliance
+
+[OPT] Semantic Validation:
+• Variable declarations - Proper variable naming and scope
+• Function definitions - Valid function signatures
+• Control structures - Proper if/else and while loop syntax
+• Command validation - Minecraft command syntax checking
+
+[WARN] Error Detection:
+• Missing semicolons and braces
+• Invalid variable names or references
+• Unclosed strings and comments
+• Malformed control structures
+• Invalid selector syntax
+• Undefined function calls
+
+[REP] Error Reporting:
+==================
+
+The check command provides detailed error information:
+
+[FEAT] Error Details:
+• File path and exact location (line, column)
+• Error type and description
+• Context lines showing the problematic code
+• Helpful suggestions for fixing issues
+
+[CMD] Error Types:
+• MDLSyntaxError - Basic syntax violations
+• MDLLexerError - Token recognition issues
+• MDLParserError - Parsing and structure problems
+• MDLValidationError - Semantic validation failures
+• MDLFileError - File access and I/O issues
+
+[TIP] Example Error Output:
+========================
+
+  Error 1: MDLSyntaxError in test.mdl:15:8
+  Missing closing brace for if statement
+  Context:
+    13:   if (score > 10) {
+    14:     say "High score!"
+    15:     score = 0
+    16:   }
+  
+  Suggestion: Add closing brace '}' after line 15
+
+[CHECK] Advanced Features:
+====================
+
+• Multi-file validation - Check entire projects at once
+• Directory support - Recursively check all .mdl files
+• Error collection - Report all errors, not just the first one
+• Context preservation - Show surrounding code for better debugging
+• Suggestion system - Provide helpful fix recommendations
+
+[NEXT] Integration:
+==============
+
+The check command is perfect for:
+• CI/CD pipelines - Automated validation
+• Development workflows - Pre-commit checks
+• Learning MDL - Understand syntax requirements
+• Debugging - Identify and fix issues quickly
+
+For more information, visit: https://www.mcmdl.com/docs/cli-reference#check
+""")
+
+
+def show_new_help():
+    """Display detailed help for the new command."""
+    print("""
+[NEW] MDL New Command - Create New MDL Projects
+============================================
+
+The new command creates a new MDL project with template files and proper 
+structure to get you started quickly.
+
+[CMD] Usage:
+========
+
+  mdl new <project_name> [options]
+
+[DIR] Arguments:
+============
+
+  <project_name>        Name for your new MDL project
+                        This will be used for the project directory and pack name
+                        Example: my_awesome_pack, hello_world, magic_system
+
+[OPT] Options:
+==========
+
+  --pack-name <name>    Custom name for the datapack (defaults to project name)
+                        This appears in the pack.mcmeta description
+                        Example: --pack-name "My Awesome Magic Pack"
+
+  --pack-format <num>   Pack format number for Minecraft version compatibility
+                        Default: 82 (Minecraft 1.20+)
+                        Example: --pack-format 15 (for older versions)
+
+[EX] Examples:
+===========
+
+1. Create a basic project:
+   mdl new hello_world
+
+2. Create project with custom pack name:
+   mdl new magic_system --pack-name "Epic Magic Pack"
+
+3. Create project for older Minecraft version:
+   mdl new retro_pack --pack-format 15
+
+4. Create project with all custom options:
+   mdl new my_project --pack-name "My Project" --pack-format 82
+
+[OUT] Generated Structure:
+======================
+
+The new command creates a complete project structure:
+
+  <project_name>/
+  ├── README.md                    # Project documentation
+  └── <project_name>.mdl          # Main MDL file with template code
+
+[FILE] Template Content:
+===================
+
+The generated MDL file includes:
+
+[CMD] Pack Declaration:
+```mdl
+pack {
+  name: "project_name"
+  format: 82
+  description: "Generated by MDL CLI"
+}
+```
+
+[OPT] Example Functions:
+```mdl
+function main {
+  say "Hello from MDL!"
+  
+  // Variable example
+  score = 10
+  say "Score: $score$"
+  
+  // Conditional example
+  if (score > 5) {
+    say "High score!"
+  } else {
+    say "Try again!"
+  }
+}
+
+function load {
+  // This function runs when the datapack loads
+  say "Datapack loaded successfully!"
+}
+```
+
+[FEAT] Features:
+===========
+
+• Complete project setup - Ready-to-use structure
+• Template code - Working examples to learn from
+• Proper pack metadata - Correct pack.mcmeta configuration
+• Documentation - README with usage instructions
+• Best practices - Follows MDL conventions
+
+[NEXT] Getting Started:
+==================
+
+After creating a new project:
+
+1. Navigate to the project directory:
+   cd <project_name>
+
+2. Edit the MDL file:
+   # Edit <project_name>.mdl with your code
+
+3. Build the datapack:
+   mdl build --mdl <project_name>.mdl -o dist
+
+4. Check for errors:
+   mdl check <project_name>.mdl
+
+5. Load in Minecraft:
+   # Copy the dist folder to your world's datapacks directory
+
+[TIP] Tips:
+========
+
+• Use descriptive project names - They become your namespace
+• Start with the template code - It demonstrates key MDL features
+• Check your code regularly - Use `mdl check` during development
+• Use version control - Git is great for tracking changes
+• Read the documentation - Learn about all available features
+
+[INFO] Next Steps:
+=============
+
+• Language Reference: https://www.mcmdl.com/docs/language-reference
+• Examples: https://www.mcmdl.com/docs/examples
+• CLI Reference: https://www.mcmdl.com/docs/cli-reference
+
+For more information, visit: https://www.mcmdl.com/docs/cli-reference#new
+""")