{#-
Code Block Formatting Macros

Provides consistent code formatting across all documentation types with
syntax highlighting, error handling, and proper escaping.
-#}

{% from 'macros/safe_macros.md.jinja2' import safe_attr, debug_info %}

{#- Main code block macro -#}
{% macro code_block(code, language="python", title=None, show_line_numbers=false) %}
{% if code %}
{% if title %}**{{ title }}:**{% endif %}

```{{ language }}{% if show_line_numbers %} {linenos}{% endif %}

{{ code.strip() }}
```
{% endif %}
{% endmacro %}

{#- Signature block for functions/methods -#}
{% macro signature_block(signature, element_type="function", language="python") %}
{% if signature %}
```{{ language }}
{{ signature }}
```
{% else %}
:::{warning}
{{ element_type | title }} signature unavailable
:::
{% endif %}
{% endmacro %}

{#- Usage example block -#}
{% macro usage_block(usage, title="Usage", language="bash") %}
{% if usage %}
**{{ title }}:**

```{{ language }}
{{ usage.strip() }}
```
{% endif %}
{% endmacro %}

{#- Multiple code examples with tabs -#}
{% macro code_examples(examples, title="Examples") %}
{% if examples and examples|length > 0 %}

**{{ title }}:**

{% if examples|length == 1 %}
{#- Single example - no tabs needed -#}
{% set example = examples[0] %}
{{ format_single_example(example) }}
{% else %}
{#- Multiple examples - use tabs -#}
{% for example in examples %}
### Example {{ loop.index }}{% if example.title %}: {{ example.title }}{% endif %}

{{ format_single_example(example) }}

{% endfor %}
{% endif %}

{% endif %}
{% endmacro %}

{#- Format a single code example -#}
{% macro format_single_example(example) %}
{% if example is string %}
{#- Simple string example -#}
```python
{{ example.strip() }}
```
{% else %}
{#- Structured example with metadata -#}
{% if safe_attr(example, 'description', '') %}
{{ example.description }}

{% endif %}
{% set lang = safe_attr(example, 'language', 'python') %}
{% set code = safe_attr(example, 'code', '') or safe_attr(example, 'content', '') %}
{% if code %}
```{{ lang }}
{{ code.strip() }}
```
{% endif %}
{% if safe_attr(example, 'output', '') %}

**Output:**
```
{{ example.output.strip() }}
```
{% endif %}
{% endif %}
{% endmacro %}

{#- CLI command examples -#}
{% macro cli_examples(examples, title="Examples") %}
{% if examples and examples|length > 0 %}

**{{ title }}:**

{% for example in examples %}
{% if example is string %}
```bash
{{ example.strip() }}
```
{% else %}
{% if safe_attr(example, 'description', '') %}
{{ example.description }}

{% endif %}
```bash
{{ safe_attr(example, 'command', example) }}
```
{% if safe_attr(example, 'output', '') %}

**Output:**
```
{{ example.output.strip() }}
```
{% endif %}
{% endif %}

{% if not loop.last %}

{% endif %}
{% endfor %}

{% endif %}
{% endmacro %}

{#- HTTP request/response examples -#}
{% macro http_examples(examples, title="Examples") %}
{% if examples and examples|length > 0 %}

**{{ title }}:**

{% for example in examples %}
{% if safe_attr(example, 'description', '') %}
{{ example.description }}

{% endif %}

{% if safe_attr(example, 'request', '') %}
**Request:**
```http
{{ example.request.strip() }}
```
{% endif %}

{% if safe_attr(example, 'response', '') %}
**Response:**
```json
{{ example.response.strip() }}
```
{% endif %}

{% if not loop.last %}

---

{% endif %}
{% endfor %}

{% endif %}
{% endmacro %}

{#- Inline code formatting -#}
{% macro inline_code(text) %}
{%- if text -%}
`{{ text }}`
{%- else -%}
-
{%- endif -%}
{% endmacro %}

{#- Code or dash (for table cells) -#}
{% macro code_or_dash(value) %}
{%- if value and str(value) not in ['-', 'None', '', 'null'] -%}
`{{ value }}`
{%- else -%}
-
{%- endif -%}
{% endmacro %}

{#- Safe code block that handles errors -#}
{% macro safe_code_block(code, language="python", fallback_text="Code unavailable") %}
{% if code %}
```{{ language }}
{{ code.strip() }}
```
{% else %}
*{{ fallback_text }}*
{% endif %}
{% endmacro %}

{#- Syntax highlighting for different languages -#}
{% macro highlight_code(code, language="auto") %}
{% if not code %}
*No code provided*
{% else %}
{#- Auto-detect language if needed -#}
{% if language == "auto" %}
{% set detected_lang = detect_language(code) %}
{% else %}
{% set detected_lang = language %}
{% endif %}

```{{ detected_lang }}
{{ code.strip() }}
```
{% endif %}
{% endmacro %}

{#- Simple language detection -#}
{% macro detect_language(code) %}
{%- if 'def ' in code or 'import ' in code or 'class ' in code -%}
python
{%- elif 'function ' in code or 'const ' in code or 'let ' in code -%}
javascript
{%- elif '#!/bin/bash' in code or 'echo ' in code -%}
bash
{%- elif 'curl ' in code or 'GET ' in code or 'POST ' in code -%}
bash
{%- else -%}
text
{%- endif -%}
{% endmacro %}
