### YAPL Installation and Getting Started

Source: https://yapl-language.github.io/documentation/index

Provides guidance on how to begin using YAPL, directing users to the installation guide and offering a quick start option to see YAPL in action. It also mentions a browser-based playground for immediate experimentation.

```yapl
## Next Steps

Ready to get started? Check out the [Installation](https://yapl-language.github.io/installation/) guide to set up YAPL, or jump straight to the [Quick Start](https://yapl-language.github.io/quick-start/) to see YAPL in action.

Want to experiment with YAPL right away? Visit the [YAPL Playground](https://yapl-language.github.io/#playground) to try examples in your browser without installing anything.
```

--------------------------------

### YAPL Installation and Quick Start

Source: https://yapl-language.github.io/documentation/index

Guides for getting started with YAPL, including installation procedures and a quick start tutorial to help users begin using the language for AI prompt engineering.

```typescript
// Installation and Quick Start examples would typically be found here.
// For example, a command-line installation or a basic YAPL template usage.
```

--------------------------------

### Basic YAPL Template Example

Source: https://yapl-language.github.io/documentation/quick-start

A sample YAPL template file ('system.md.yapl') demonstrating variable usage with defaults, conditional inclusion of content based on a variable, and specifying output format.

```markdown
# System Prompt

## Persona

You are {{ agent_name| default("a helpful AI assistant") }}.

## Guidelines

- Be helpful and accurate
- Provide clear explanations
- Ask clarifying questions when needed

{% if expertise %}

## Expertise

You specialize in {{ expertise }}.


{% endif %}

## Output Format

Respond in {{ format| default("markdown") }} format.

```

--------------------------------

### YAPL Include Example

Source: https://yapl-language.github.io/documentation/quick-start

Shows how to use the `include` directive in YAPL to incorporate content from other template files, promoting modularity and reusability. This example includes a code review checklist from a separate file.

```yapl
{% extends"base/agent.md.yapl" %}


{% block guidelines %}

{{ super() }}


{% include"components/code-review-checklist.md.yapl" %}


{% endblock %}
```

--------------------------------

### Rendering YAPL Templates with Context (JavaScript)

Source: https://yapl-language.github.io/documentation/quick-start

Illustrates how to render YAPL templates using a JavaScript client, passing context variables to customize the output. Examples show rendering for both 'beginner' and 'expert' user levels.

```javascript
// For a beginner

const beginnerResult = await yapl.render("coding-assistant.md.yapl", {

name: "TeachBot",

user_level: "beginner",

include_tests: true,

});

// For an expert

const expertResult = await yapl.render("coding-assistant.md.yapl", {

name: "ExpertBot",

user_level: "expert",

include_tests: false,

});
```

--------------------------------

### YAPL Mixin Example

Source: https://yapl-language.github.io/documentation/quick-start

This YAPL template demonstrates the use of mixins for composition. It includes reusable content from `friendly.md.yapl` and `safety.md.yapl` using the `{% mixin ... %}` tag, allowing for modular template design.

```yapl
{% extends"base/agent.md.yapl" %}

{% mixin"mixins/friendly.md.yapl", "mixins/safety.md.yapl" %}

{% block persona %}


You are {{ name| default("CodeBot") }}, an expert programming assistant.

You have deep knowledge of multiple programming languages and best practices.

{% endblock %}

{% block capabilities %}

{{ super() }}

- Write and review code
- Debug issues
- Explain programming concepts
- Suggest optimizations

{% endblock %}
```

--------------------------------

### YAPL Conditional Logic Example

Source: https://yapl-language.github.io/documentation/quick-start

Demonstrates how to use conditional logic within YAPL templates to adapt output based on context variables like 'user_level'. This allows for dynamic content generation tailored to different user types.

```yapl
{% extends"base/agent.md.yapl" %}


{% mixin"mixins/friendly.md.yapl", "mixins/safety.md.yapl" %}


{% block persona %}

You are {{ name| default("CodeBot") }}, an expert programming assistant.


{% if user_level == "beginner" %}

You excel at explaining complex concepts in simple terms and providing step-by-step guidance.

{% else %}

You can discuss advanced topics and assume familiarity with programming fundamentals.

{% endif %}


{% endblock %}


{% block guidelines %}

{{ super() }}


{% if user_level == "beginner" %}

- Use simple language and avoid jargon
- Provide detailed explanations
- Include plenty of examples

{% else %}

- You can use technical terminology
- Focus on efficiency and best practices
- Provide concise, expert-level advice

{% endif %}


{% if include_tests %}

- Always include unit tests with code examples

{% endif %}


{% endblock %}
```

--------------------------------

### Basic YAPL Setup Example

Source: https://yapl-language.github.io/documentation/reference/api

Provides a basic JavaScript example for setting up and initializing the NodeYAPL instance with various configuration options, including base directory, caching, path strictness, maximum depth, and whitespace handling.

```typescript
import { NodeYAPL } from"@yapl-language/yapl.ts";

const yapl = newNodeYAPL({
  baseDir: "./prompts",
  cache: true,
  strictPaths: true,
  maxDepth: 10,
  whitespace: {
    trimBlocks: true,
    lstripBlocks: true,
    dedentBlocks: true,
  },
});
```

--------------------------------

### YAPL Installation and Setup

Source: https://yapl-language.github.io/documentation/installation

Instructions for installing YAPL, a TypeScript/JavaScript library, for use in Node.js and browser environments. It outlines the necessary prerequisites and basic configuration steps.

```markdown
## Prerequisites
  * Node.js 18 or higher
  * npm, yarn, or pnpm
```

--------------------------------

### Basic Setup for Browser Environment

Source: https://yapl-language.github.io/documentation/installation

Illustrates how to set up YAPL in a browser environment or when file system access is not needed. It shows how to initialize YAPL and render template strings directly.

```javascript
import { YAPL } from"@yapl-language/yapl.ts";

const yapl = newYAPL({
  baseDir: "/virtual", // Virtual base directory, is necessary to tell YAPL it's running in a Browser environment.
});

// Render template strings directly
const templateSource = `
Hello, {{ name | default("World") }}!
{% if greeting %}{{ greeting }}{% endif %}
`;

const result = await yapl.renderString(templateSource, {
  name: "YAPL User",
  greeting: "Welcome to YAPL!",
});

console.log(result.content);
```

--------------------------------

### Create YAPL Template Directory and File

Source: https://yapl-language.github.io/documentation/quick-start

This snippet shows how to create a directory for YAPL prompts and then create a basic template file named 'system.md.yapl'. This template includes variables, conditional logic, and default values.

```bash
mkdir my-prompts
cd my-prompts
```

--------------------------------

### Basic Setup for Node.js Environment

Source: https://yapl-language.github.io/documentation/installation

Demonstrates how to set up YAPL in a Node.js environment for applications that require file system access. It shows how to initialize NodeYAPL and render a template file.

```typescript
import { NodeYAPL } from"@yapl-language/yapl.ts";

const yapl = newNodeYAPL({
  baseDir: "./prompts", // Directory containing your .yapl files
});

// Render a template file and pass your variables.
const result = await yapl.render("agent.md.yapl", {
  variable1: "Assistant",
  variable2: "customer support",
});

console.log(result.content);
```

--------------------------------

### YAPL Usage Examples

Source: https://yapl-language.github.io/documentation/reference/api

Provides practical examples of how to use the YAPL templating engine, covering basic setup, rendering templates, error handling, dynamic configuration, browser usage, advanced variable handling, file caching, and path security.

```APIDOC
Basic Setup:
  const yapl = new YAPL({ template: 'Hello, {{ name }}!' });
  const output = yapl.render({ name: 'World' });
  // Output: 'Hello, World!'

Rendering Templates:
  const yapl = new YAPL({ template: './views/index.yapl' });
  const html = yapl.render(data);

Error Handling:
  try {
    const yapl = new YAPL({ template: '{{ invalid_syntax' });
    yapl.render();
  } catch (error) {
    console.error('Template Error:', error.message);
  }

Dynamic Configuration:
  const config = { ...defaultConfig, ...userConfig };
  const yapl = new YAPL({ template: '...', vars: config });

Browser Usage:
  // Assuming YAPL is loaded via a script tag
  const yapl = new YAPL({ template: '{{ message }}' });
  document.getElementById('output').innerHTML = yapl.render({ message: 'Hello from browser!' });

Advanced Variable Handling:
  // Using filters or custom functions for variables
  // {{ user.name | capitalize }}

File Caching:
  // YAPL automatically caches compiled templates for performance.

Path Security:
  // YAPL includes measures to prevent directory traversal attacks.
```

--------------------------------

### YAPL Troubleshooting Guide

Source: https://yapl-language.github.io/documentation/troubleshooting

This section outlines common issues and their solutions for the YAPL templating language. It covers a wide range of problems from installation and syntax errors to runtime exceptions and performance bottlenecks.

```APIDOC
Installation Issues:
  Package Not Found: Ensure the YAPL package is correctly installed and accessible in your project's dependencies.
  Import Errors: Verify that the YAPL module is imported with the correct path and syntax.

Template Syntax Errors:
  Missing File Extensions: Ensure all template files have the expected file extension (e.g., .yapl).
  Mismatched Block Tags: Check that all opening and closing block tags (e.g., {% block %}, {% endblock %}) are correctly paired and named.
  Invalid Block Names: Ensure block names adhere to YAPL's naming conventions.

Runtime Errors:
  Path Traversal Blocked: YAPL may block path traversal for security. Ensure your include paths are relative and within the expected directory.
  Maximum Depth Exceeded: If templates include each other recursively, a maximum depth limit might be reached. Review your template structure for infinite loops.
  For Loop Type Errors: Ensure the iterable passed to a for loop is of a compatible type (e.g., an array or list).

File System Issues:
  File Not Found: Verify that the file path specified in include or import statements is correct and the file exists.
  Permission Denied: Ensure the YAPL process has the necessary read permissions for the template files and directories.

Variable Issues:
  Undefined Variables: Check that variables are defined before being used, or provide default values.
  Nested Property Access: Ensure the path to nested properties is correct and that intermediate properties exist.

Browser-Specific Issues:
  File Loading Not Available: In some browser environments, direct file loading might be restricted. Consider using a build process or alternative methods for loading templates.

Performance Issues:
  Slow Template Rendering: Optimize complex logic within templates, reduce deep nesting, and consider caching compiled templates.
  Memory Leaks: Monitor template rendering processes for excessive memory usage, which might indicate inefficient loops or large data structures.

Debugging Techniques:
  Enable Verbose Logging: Activate YAPL's verbose logging to get detailed information about template processing.
  Inspect Rendered Output: Examine the final HTML or output to identify unexpected content or structure.
  Test Templates in Isolation: Render individual templates with sample data to pinpoint specific issues.
  Validate Data Structures: Ensure the data passed to templates is well-formed and matches expected structures.
```

--------------------------------

### YAPL Mixin - Friendly Personality

Source: https://yapl-language.github.io/documentation/quick-start

A YAPL mixin template that adds a friendly and encouraging personality to an AI assistant's persona.

```yapl
{% block persona %}

{{ super() }}

You have a friendly, encouraging personality and enjoy helping users learn.

{% endblock %}
```

--------------------------------

### YAPL Template Inheritance Example

Source: https://yapl-language.github.io/documentation/quick-start

This YAPL template extends a base template and overrides specific content blocks. It utilizes the `super()` function to incorporate content from the parent template's blocks while adding new information.

```yapl
{% extends"base/agent.md.yapl" %}

{% block persona %}


You are {{ name| default("CodeBot") }}, an expert programming assistant.

You have deep knowledge of multiple programming languages and best practices.

{% endblock %}

{% block capabilities %}

{{ super() }}

- Write and review code
- Debug issues
- Explain programming concepts
- Suggest optimizations

{% endblock %}

{% block guidelines %}

{{ super() }}

- Always include code examples when relevant
- Explain your reasoning
- Consider security and performance implications

{% endblock %}
```

--------------------------------

### YAPL Base Template

Source: https://yapl-language.github.io/documentation/quick-start

Defines a base YAPL template with several blocks for persona, capabilities, guidelines, and output format. These blocks can be extended and overridden by other templates.

```yapl
# {{ title| default("AI Agent") }}

{% block persona %}

You are a helpful AI assistant.

{% endblock %}

{% block capabilities %}

## Capabilities
- Answer questions
- Provide explanations
- Help with tasks

{% endblock %}

{% block guidelines %}

## Guidelines
- Be accurate and helpful
- Ask for clarification when needed
- Provide step-by-step guidance

{% endblock %}

{% block output_format %}

## Output Format
Respond clearly and concisely.

{% endblock %}
```

--------------------------------

### Render YAPL Template with Variables (Node.js)

Source: https://yapl-language.github.io/documentation/quick-start

This snippet shows how to initialize the NodeYAPL library and render a YAPL template file with dynamic variables. It demonstrates passing a context object to the render function and logging the output content.

```javascript
import { NodeYAPL } from"@yapl-language/yapl.ts";



const yapl = newNodeYAPL({ baseDir: "./my-prompts" });



// Render with variables



const result = await yapl.render("system.md.yapl", {



agent_name: "CodeBot",



expertise: "software development",



format: "markdown",



});



console.log(result.content);
```

--------------------------------

### YAPL Mixin - Safety Guidelines

Source: https://yapl-language.github.io/documentation/quick-start

A YAPL mixin template that incorporates safety guidelines, emphasizing the importance of not providing harmful information and declining inappropriate requests.

```yapl
{% block guidelines %}

{{ super() }}

- Never provide harmful or dangerous information
- Decline inappropriate requests politely
- Prioritize user safety and well-being

{% endblock %}
```

--------------------------------

### Best Practice: Use Meaningful Parameters

Source: https://yapl-language.github.io/documentation/features/includes

Provides examples of YAPL includes demonstrating the best practice of using clear and descriptive parameter names, contrasting them with examples using unclear or abbreviated names.

```yapl
<!-- Good - clear parameter names -->



{% include"components/feature-toggle.md.yapl"with {

"feature_name": "advanced_search",

"is_enabled": true,

"fallback_message": "Basic search is available"

} %}
<!-- Avoid - unclear parameters -->



{% include"components/feature-toggle.md.yapl"with {

"name": "search",

"flag": true,

"msg": "fallback"

} %}
```

--------------------------------

### YAPL Path Resolution Example

Source: https://yapl-language.github.io/documentation/reference/syntax

Provides an example of a template directory structure and how YAPL extends templates from different locations.

```yapl
prompts/

├── base/

│   └── system.yapl

├── agents/

│   └── coder.yapl          <!-- extends "../base/system.yapl" -->

└── components/

└── header.yapl
```

--------------------------------

### baseDir Configuration Example

Source: https://yapl-language.github.io/documentation/reference/configuration

Demonstrates how to configure the `baseDir` option for YAPL, showing examples for both absolute and relative paths.

```javascript
// Absolute path



const yapl = newNodeYAPL({



baseDir: '/home/user/prompts'



});



// Relative path



const yapl = newNodeYAPL({



baseDir: './src/prompts'



});
```

--------------------------------

### Install YAPL using npm, yarn, or pnpm

Source: https://yapl-language.github.io/documentation/installation

Instructions for installing the YAPL package using different package managers. This is the first step to using YAPL in your project.

```bash
npm install @yapl-language/yapl.ts
```

```bash
yarn add @yapl-language/yapl.ts
```

```bash
pnpm add @yapl-language/yapl.ts
```

--------------------------------

### Get YAPL Version and Basic Usage Example

Source: https://yapl-language.github.io/documentation/troubleshooting

This snippet shows how to check the YAPL version using npm list and provides a minimal reproduction case for reporting bugs. It demonstrates initializing YAPL, rendering a string, and logging the output.

```bash
npmlist @yapl-language/yapl.ts
```

```javascript
import { NodeYAPL } from"@yapl-language/yapl.ts";

const yapl = newNodeYAPL({ baseDir: "./test" });

const result = await yapl.renderString("{{ test }}", { test: "value" });

console.log(result.content);
```

--------------------------------

### YAPL File Extensions

Source: https://yapl-language.github.io/documentation/installation

Lists the supported file extensions for YAPL templates, indicating the flexibility in how prompts can be structured.

```APIDOC
Supported File Extensions:
  .yapl - Pure YAPL templates
  .md.yapl - Markdown-based prompts with YAPL templating
  .txt.yapl - Plain text prompts with YAPL templating
  .json.yapl - JSON-structured prompts with YAPL templating
```

--------------------------------

### YAPL Browser Rendering Example

Source: https://yapl-language.github.io/documentation/reference/api

Example of rendering a template in a browser environment using custom loaders.

```javascript
const yapl = newYAPL({
  baseDir: "/templates",
  loadFile: async (path) => {
    const response = await fetch(path);
    return response.text();
  },
  resolvePath: (templateRef, fromDir, ensureExt) => {
    return newURL(ensureExt(templateRef), fromDir).href;
  },
});

const result = await yapl.render("template.yapl", { name: "World" });
```

--------------------------------

### Initialize YAPL with Caching

Source: https://yapl-language.github.io/documentation/reference/configuration

Demonstrates how to create a single, cached instance of YAPL. This is the recommended setup for applications, ensuring consistent prompt handling and improved performance through caching.

```javascript
const globalYapl = newNodeYAPL({
  baseDir: './prompts',
  cache: true
});

export default globalYapl;
```

--------------------------------

### YAPL Template Inheritance (Node.js)

Source: https://yapl-language.github.io/documentation/quick-start

Demonstrates template inheritance in YAPL. A child template `coding-assistant.md.yapl` extends a base template `base/agent.md.yapl` and overrides specific blocks like 'persona', 'capabilities', and 'guidelines'. It also shows how to use `super()` to include content from the parent block.

```javascript
const result = await yapl.render("coding-assistant.md.yapl", {



title: "Programming Assistant",



name: "DevBot",



});



console.log(result.content);
```

--------------------------------

### Production Environment Configuration for YAPL

Source: https://yapl-language.github.io/documentation/reference/configuration

Configuration example for a production environment, enabling caching and ensuring strict path and whitespace settings for optimal performance and security.

```javascript
const productionConfig = {
  baseDir: '/app/prompts',
  cache: true,
  strictPaths: true,
  maxDepth: 20,
  whitespace: {
    trimBlocks: true,
    lstripBlocks: true,
    dedentBlocks: true
  }
};
const yapl = newNodeYAPL(productionConfig);
```

--------------------------------

### Development Environment Configuration for YAPL

Source: https://yapl-language.github.io/documentation/reference/configuration

Configuration example for a development environment, disabling caching for live reloading and adjusting whitespace handling for debugging.

```javascript
const developmentConfig = {
  baseDir: './src/prompts',
  cache: false,
  strictPaths: true,
  maxDepth: 10,
  whitespace: {
    trimBlocks: false,
    lstripBlocks: false,
    dedentBlocks: true
  }
};
const yapl = newNodeYAPL(developmentConfig);
```

--------------------------------

### YAPL Configuration Options (YAPLOptions)

Source: https://yapl-language.github.io/documentation/installation

Details the configuration options available for YAPL, including base directory, caching, path strictness, maximum nesting depth, and whitespace control.

```APIDOC
YAPLOptions:
  baseDir: string (Required) - Base directory for template files
  cache: boolean (Default: true) - Enable file caching (Node.js only)
  strictPaths: boolean (Default: true) - Prevent path traversal outside baseDir
  maxDepth: number (Default: 20) - Maximum template nesting depth
  whitespace: WhitespaceOptions - Whitespace control options
```

--------------------------------

### YAPL Mixin Block Merging Example

Source: https://yapl-language.github.io/documentation/features/mixins

Provides a step-by-step example of how YAPL merges blocks from a base template, multiple mixins, and a child template. It shows how `{{ super() }}` is used to progressively build the final content by referencing previously defined blocks.

```yapl
{% extends"base.yapl" %}


{% mixin"mixin1.yapl", "mixin2.yapl" %}


{% block persona %}


{{ super() }}



You specialize in technical support.


{% endblock %}
```

--------------------------------

### Cache Configuration Example

Source: https://yapl-language.github.io/documentation/reference/configuration

Illustrates the usage of the `cache` option in YAPL for Node.js environments, showing how to enable it for performance or disable it for development.

```javascript
// Enable caching (recommended for production)



const yapl = newNodeYAPL({



baseDir: './prompts',



cache: true



});



// Disable caching (useful for development)



const yapl = newNodeYAPL({



baseDir: './prompts',



cache: false



});
```

--------------------------------

### Path Resolution Example

Source: https://yapl-language.github.io/documentation/features/inheritance

Shows how template paths are resolved relative to the current template's directory structure, demonstrating a common project layout.

```yapl
prompts/
╰──base/
│    ─agent.md.yapl
╰─specialized/
│    ─coder.md.yapl      # extends "../base/agent.md.yapl"
╰tasks/
╰review.md.yapl     # extends "../base/agent.md.yapl"
```

--------------------------------

### YAPL renderString Example

Source: https://yapl-language.github.io/documentation/reference/api

An example demonstrating how to use the `renderString` method to render a template with a variable and a default value. It shows how to access the rendered content from the resulting Prompt object.

```typescript
const result = await yapl.renderString(

	'Hello, {{ name | default("World") }}!',

	{ name: "Alice" }

);

console.log(result.content); // "Hello, Alice!"
```

--------------------------------

### Install YAPL Package

Source: https://yapl-language.github.io/documentation/troubleshooting

Resolves 'Package Not Found' errors during installation by specifying the correct package name for npm. This ensures that the YAPL package is correctly downloaded and installed from the npm registry.

```bash
npm install @yapl-language/yapl.ts
```

--------------------------------

### Best Practice: Document Include Interfaces

Source: https://yapl-language.github.io/documentation/features/includes

Illustrates how to document the interface of a YAPL include component using comments, specifying its purpose, parameters (with types and descriptions), and providing a usage example.

```yapl
{#
User greeting component

Parameters:
- user_name (string): Name to display in greeting
- user_role (string): User's role for role-specific messages
- show_last_login (boolean): Whether to show last login time
- custom_message (string, optional): Custom message to append

Example:
{% include "components/user-greeting.md.yapl" with {
"user_name": "Alice",
"user_role": "admin",
"show_last_login": true
}
}
#}
```

--------------------------------

### YAPL Whitespace Control Options

Source: https://yapl-language.github.io/documentation/installation

Explains the whitespace control options for YAPL, which allow fine-tuning of how whitespace is handled within template blocks.

```APIDOC
WhitespaceOptions:
  trimBlocks: boolean (Default: true) - Remove newlines after block tags
  lstripBlocks: boolean (Default: true) - Remove leading whitespace before block tags
  dedentBlocks: boolean (Default: true) - Remove common indentation from block content
```

--------------------------------

### Best Practice: Keep Includes Focused

Source: https://yapl-language.github.io/documentation/features/includes

Shows examples of YAPL includes that adhere to the best practice of having a single responsibility, contrasting them with includes that attempt to handle multiple functionalities.

```yapl
<!-- Good - single responsibility -->



{% include"components/error-handling.md.yapl" %}




{% include"components/user-permissions.md.yapl" %}



<!-- Avoid - multiple responsibilities -->



{% include"components/everything.md.yapl" %}
```

--------------------------------

### Browser Usage with Custom Loaders

Source: https://yapl-language.github.io/documentation/reference/api

Provides an example of how to use YAPL in a browser environment. It includes setting up a YAPL instance with custom `resolvePath` and `loadFile` functions to handle virtual file systems or remote fetching.

```javascript
import { YAPL } from"@yapl-language/yapl.ts";

const yapl = newYAPL({
baseDir: "/virtual",
resolvePath: (templateRef, fromDir, ensureExt) => {
return newURL(ensureExt(templateRef), fromDir).href;
},
loadFile: async (absolutePath) => {
const response = await fetch(absolutePath);
return response.text();
},
});

// Render with custom loaders
const result = await yapl.render("template.yapl", variables);
```

--------------------------------

### YAPL Template Syntax: Loops

Source: https://yapl-language.github.io/documentation/reference/api

Shows how to iterate over arrays or lists in YAPL using for loops, including examples with predefined arrays.

```yapl
{% for item in array %}
  {{ item }}
{% endfor %}

{% for item in [1, 2, 3] %}
  {{ item }}
{% endfor %}
```

--------------------------------

### Enabling YAPL Template Caching for Performance

Source: https://yapl-language.github.io/documentation/troubleshooting

Shows how to enable caching in YAPL for Node.js environments to improve template rendering performance. It includes an example of initializing YAPL with the `cache` option set to true.

```javascript
const yapl = newNodeYAPL({
  baseDir: "./prompts",
  cache: true, // Enable file caching
});
```

--------------------------------

### Strategic Use of super() in YAPL

Source: https://yapl-language.github.io/documentation/features/inheritance

Illustrates effective strategies for using the `super()` function in YAPL, showing examples of extending parent content and replacing it when necessary.

```yapl
<!-- Good - extends parent content -->
{% block guidelines %}

{{ super() }}

- Additional specific guideline

{% endblock %}

<!-- Good - replaces when needed -->
{% block persona %}

You are a completely different type of assistant.

{% endblock %}
```

--------------------------------

### Parent Template Example

Source: https://yapl-language.github.io/documentation/features/inheritance

Defines a base template with several blocks for persona, output format, and guidance. This serves as a foundation for child templates.

```yapl
# System Prompt

{% block persona %}

You are a helpful AI assistant.

{% endblock %}



{% block output_format %}

Respond in markdown format.

{% endblock %}



{% block guidance %}

Be concise and accurate.

{% endblock %}
```

--------------------------------

### Super Function Usage in YAPL

Source: https://yapl-language.github.io/documentation/reference/syntax

Demonstrates how to use the `super()` function to access parent block content in YAPL templates, including examples with and without whitespace control.

```yapl
{% block content %}


{{ super() }}


Additional content


{% endblock %}

{# Whitespace control with super #}


{%- block content -%}


{{- super() -}}


Additional content


{%- endblock -%}
```

--------------------------------

### YAPL Block Naming Best Practices

Source: https://yapl-language.github.io/documentation/features/inheritance

Provides examples of good and bad practices for naming blocks in YAPL templates, emphasizing the use of meaningful and descriptive names for better maintainability.

```yapl
<!-- Good -->

{% block interaction_guidelines %}
{% block error_handling %}
{% block output_formatting %}

<!-- Avoid -->

{% block stuff %}
{% block content %}
{% block misc %}
```

--------------------------------

### Debugging Undefined Variables in YAPL

Source: https://yapl-language.github.io/documentation/troubleshooting

Provides JavaScript code examples for debugging undefined variables in YAPL. It shows how to render a template with a missing variable and how to inspect available variables using YAPL's debugging features.

```javascript
const result = await yapl.renderString("{{ missing_var }}", {});

console.log(result.content); // Empty string
```

```javascript
{# Debug output #}
Available variables: {{ . }}

User name: {{ user.name }}
```

--------------------------------

### Best Practice: Graceful Handling of Empty Arrays in YAPL

Source: https://yapl-language.github.io/documentation/features/loops

Provides an example of best practice in YAPL for handling empty arrays gracefully by using conditional checks before iterating, ensuring a fallback message when no data is available.

```YAPL
{% if techniques %}

{% for technique in techniques %}

- {{ technique.name }}

{% endfor %}

{% else %}
No techniques available.
{% endif %}
```

--------------------------------

### YAPL Syntax Errors: Invalid variable names

Source: https://yapl-language.github.io/documentation/reference/syntax

Provides examples of invalid variable names in YAPL, including those starting with numbers, containing hyphens, or having properties that start with numbers.

```yapl
{{ 123invalid }}     {# Error: can't start with number #}



{{ invalid-name }}   {# Error: hyphens not allowed in variable names #}



{{ invalid.123 }}    {# Error: property names can't start with numbers #}
```

--------------------------------

### YAPL API Reference

Source: https://yapl-language.github.io/documentation/introduction

This section provides a reference for the YAPL API, detailing its syntax, available features, and configuration options.

```APIDOC
YAPL API Reference:

Syntax Reference:
  Provides detailed information on the YAPL language syntax, including variable declaration, control flow statements, and template structure.

API Reference:
  Details the available functions and methods within the YAPL library for programmatic use.

Configuration:
  Explains how to configure YAPL, including options for template loading, caching, and error handling.
```

--------------------------------

### Configure YAPL Instance and Whitespace

Source: https://yapl-language.github.io/documentation/reference/api

Shows how to create a YAPL instance with a base directory and how to dynamically update the base directory. It also demonstrates configuring custom whitespace handling (trimming, stripping, dedenting) for specific rendering tasks.

```javascript
// Create with minimal config
const yapl = newNodeYAPL({ baseDir: "./prompts" });

// Update base directory
yapl.setBaseDir("./different-prompts");

// Render with custom whitespace for specific template
const customRenderer = newNodeYAPL({
baseDir: "./prompts",
whitespace: {
trimBlocks: false,
lstripBlocks: false,
dedentBlocks: true,
},
});
```

--------------------------------

### YAPL Naming Conventions: Files

Source: https://yapl-language.github.io/documentation/reference/syntax

Provides YAPL file naming conventions, emphasizing descriptive names, organization in directories, and using mixins.

```yapl
{% extends"base/agent.md.yapl" %}        <!-- descriptive names -->



{% include"components/header.yapl" %}    <!-- organized in directories -->



{% mixin"mixins/safety-guidelines.yapl" %}
```

--------------------------------

### YAPL Environment-Specific Configurations

Source: https://yapl-language.github.io/documentation/reference/configuration

Provides guidance on setting up YAPL configurations for different environments, such as development and production, and highlights best practices for managing these configurations.

```APIDOC
Environment-Specific Configurations:

Development Environment:
  - Typically involves disabling caching for immediate feedback during development.
  - May use more verbose logging.

Production Environment:
  - Caching should be enabled for performance.
  - Strict path checking is recommended to catch errors early.
  - Consider using environment variables for configuration values.

Best Practices:
  1. Use Environment Variables: Store configuration settings like base directories or API keys in environment variables.
  2. Single Instance with Caching (recommended): Initialize YAPL once with appropriate configurations and reuse the instance throughout the application, ensuring caching is enabled for optimal performance.
```

--------------------------------

### YAPL Variable Types: Strings

Source: https://yapl-language.github.io/documentation/features/variables

Shows examples of using string variables in YAPL. Strings can be enclosed in double quotes.

```YAPL
greeting = "Hello, World!"

{{ greeting }}
```

--------------------------------

### YAPL Truthiness Examples

Source: https://yapl-language.github.io/documentation/features/conditionals

Illustrates how YAPL evaluates variables for truthiness in conditional statements, including checking for the existence of elements in lists.

```YAPL
{% if skills %}



Your skills: {{ skills.0 }}{% if skills.1 %}, {{ skills.1 }}{% endif %}


{% else %}


No skills listed.

{% endif %}



{% if error_message %}



Error: {{ error_message }}


{% endif %}
```

--------------------------------

### YAPL Multiple Conditions with AND/OR

Source: https://yapl-language.github.io/documentation/features/conditionals

Provides examples of combining multiple conditions using logical AND and OR operators, including nested and sequential checks.

```YAPL
{# AND operator #}


{% if user_type == "premium" and region == "US" %}


US Premium features available.

{% endif %}



{# OR operator #}


{% if user_type == "premium" or user_type == "admin" %}


Special content for privileged users.

{% endif %}



{# Complex combinations #}


{% if user.age >= 18 and user.verified and user.country == "US" %}


You can access age-restricted US content.

{% elseif user.age >= 16 and user.country == "UK" %}


You can access UK content for your age group.

{% endif %}
```

--------------------------------

### YAPL Naming Conventions: Blocks

Source: https://yapl-language.github.io/documentation/reference/syntax

Details YAPL naming conventions for blocks, recommending snake_case, kebab-case, and the use of colons for namespacing.

```yapl
{% block main_content %}     <!-- snake_case -->



{% block user-profile %}     <!-- kebab-case -->



{% block nav:primary %}      <!-- namespace with colon -->
```

--------------------------------

### YAPL Features and Solutions

Source: https://yapl-language.github.io/documentation/introduction

Details the solutions YAPL offers to common prompt engineering problems, such as template inheritance, mixins for composition, variable management, conditional logic, and include directives for modularity.

```yapl
Features:
- Template Inheritance: Define base templates and extend them.
- Mixins: Compose prompts from reusable components.
- Variables: Use placeholders with default values.
- Conditionals: Include or exclude content based on runtime conditions.
- Includes: Break large prompts into manageable pieces.
```

--------------------------------

### YAPL Variable Types: Strings and Numbers

Source: https://yapl-language.github.io/documentation/features/variables

Demonstrates the usage of string and number variable types in YAPL templates. Includes examples with and without default values.

```yap
Name: {{ name }}

Description: {{ description| default("No description provided") }}

Age: {{ age }}

Score: {{ score| default(0) }}

Price: ${{ price| default(9.99) }}
```

--------------------------------

### YAPL Core Concepts Overview

Source: https://yapl-language.github.io/documentation/introduction

This section outlines the fundamental principles of YAPL, including how templates are stored, the concept of inheritance hierarchies, composition through mixins, and runtime flexibility using variables and conditionals.

```yapl
Templates are stored as .yapl files, supporting various formats like JSON, Markdown, or plain text.
YAPL supports inheritance, allowing child templates to extend parent templates.
Composition is achieved through mixins for combining behaviors.
Runtime flexibility is enabled by variables and conditionals for context-aware prompt generation.
```

--------------------------------

### Converting String to Array in YAPL Data

Source: https://yapl-language.github.io/documentation/troubleshooting

Provides a JavaScript example for converting a string into an array of characters, which can then be used in YAPL 'for' loops to resolve type errors.

```javascript
const data = {
  characters: "hello".split(""), 
};
```

--------------------------------

### Using Environment Variables for YAPL Configuration

Source: https://yapl-language.github.io/documentation/reference/configuration

Demonstrates how to configure YAPL using environment variables for flexibility, allowing settings like base directory, caching, strict paths, and max depth to be dynamically controlled.

```javascript
const config = {
  baseDir: process.env.YAPL_BASE_DIR || './prompts',
  cache: process.env.NODE_ENV === 'production',
  strictPaths: process.env.YAPL_STRICT_PATHS !== 'false',
  maxDepth: parseInt(process.env.YAPL_MAX_DEPTH) || 20
};
```

--------------------------------

### Simple Include Syntax in YAPL

Source: https://yapl-language.github.io/documentation/features/includes

Demonstrates the basic syntax for including other template files within a YAPL template. This allows for modularity and code reuse by referencing components like headers and footers.

```yapl
{% include"components/header.md.yapl" %}


Main content goes here.


{% include"components/footer.md.yapl" %}
```

--------------------------------

### YAPL Use Cases

Source: https://yapl-language.github.io/documentation/index

Highlights the practical applications of YAPL, emphasizing its utility in AI agent systems for consistent personalities, multi-modal prompts for adapting to different AI capabilities, and workflow automation for building prompt libraries.

```yapl
## Use Cases

YAPL is particularly useful for:
  * **AI Agent Systems** : Creating consistent agent personalities with customizable behaviors
  * **Multi-modal Prompts** : Adapting prompts for different AI models or capabilities
  * **Workflow Automation** : Building prompt libraries for automated AI workflows
```

--------------------------------

### Correcting Variable Name Casing in YAPL

Source: https://yapl-language.github.io/documentation/troubleshooting

Illustrates the importance of matching variable casing between the data context and the YAPL template. It shows an example of a JavaScript object with camelCase and how it should be accessed in YAPL.

```javascript
const data = {
  userName: "Alice", // camelCase
};

// This won't work:
// {{ user_name }}
// This will work:
// {{ userName }}
```

--------------------------------

### Basic Variable Syntax in YAPL

Source: https://yapl-language.github.io/documentation/features/variables

Demonstrates the fundamental syntax for declaring and using variables in YAPL. This includes how to assign values and reference them within templates.

```YAPL
variable_name = "some value"

{{ variable_name }}
```

--------------------------------

### YAPL Variables and Interpolation

Source: https://yapl-language.github.io/documentation/reference/syntax

Demonstrates basic variable declaration and interpolation in YAPL, including how to provide default values.

```YAPL
/* Basic Variable Interpolation */
let name = "World";
let greeting = "Hello, {{ name }}!";

/* Default Values */
let user = "Guest";
let welcome_message = "Welcome, {{ user | default: 'Guest' }}!";
```

--------------------------------

### YAPL String Syntax

Source: https://yapl-language.github.io/documentation/reference/syntax

Illustrates the different ways to define strings in YAPL, including double quotes, single quotes, and using variables.

```yapl
{{ "double quotes" }}



{{ 'single quotes' }}



{{ variable_containing_string }}
```

--------------------------------

### YAPL Core Concepts and Features

Source: https://yapl-language.github.io/documentation/index

Explains the fundamental concepts of YAPL, including how templates are structured as files, the inheritance hierarchy, the emphasis on composition over inheritance, and runtime flexibility through variables and conditionals.

```yapl
## Core Concepts

### Templates as Files
YAPL templates are stored as `.yapl` files (often with additional extensions like `.md.yapl` for Markdown-based prompts). This makes them easy to organize, version control, and collaborate on. You can use any text based format, like JSON, Markdown or just plain text.

### Inheritance Hierarchy
Like object-oriented programming, YAPL supports inheritance where child templates can extend parent templates, overriding specific blocks while inheriting the overall structure.

### Composition over Inheritance
While inheritance is powerful, YAPL also supports mixins for composition, allowing you to combine multiple behaviors without deep inheritance hierarchies.

### Runtime Flexibility
Variables and conditionals allow the same template to generate different outputs based on the context in which it’s rendered.
```

--------------------------------

### Include Variable Scope Example

Source: https://yapl-language.github.io/documentation/features/includes

Illustrates how variables from the parent template and the 'with' clause interact within an included YAPL template. It shows that variables passed via 'with' override parent variables of the same name.

```yapl
{# Parent has: name="Bob", role="user", company="ACME" #}


{% include"greeting.md.yapl"with {"name": "Alice"} %}
```

```yapl

Hello {{ name }}! {# Uses "Alice" from with clause #}



You work at {{ company }}. {# Uses "ACME" from parent scope #}



Your role is {{ role }}. {# Uses "user" from parent scope #}

```

--------------------------------

### YAPL Configuration Options

Source: https://yapl-language.github.io/documentation/reference/configuration

Details the various configuration options available for YAPL, including their purpose and usage. These options control aspects like base directory, caching, path strictness, and whitespace handling.

```APIDOC
Configuration Options:

baseDir:
  - Description: Specifies the base directory for resolving template paths.
  - Type: string
  - Default: process.cwd() (Node.js) or document.baseURI (Browser)

cache:
  - Description: Enables or disables the template cache. Caching improves performance by storing compiled templates.
  - Type: boolean
  - Default: true

strictPaths:
  - Description: If true, YAPL will throw an error if a template path does not exist.
  - Type: boolean
  - Default: false

maxDepth:
  - Description: Sets the maximum recursion depth for template includes.
  - Type: number
  - Default: 10

whitespace:
  - Description: Controls whitespace handling in templates. Can be 'off', 'all', or 'sensitive'.
  - Type: 'off' | 'all' | 'sensitive'
  - Default: 'all'

resolvePath:
  - Description: A custom function to resolve template paths. Receives the current path and the path to resolve.
  - Type: (currentPath: string, pathToResolve: string) => string

loadFile:
  - Description: A custom function to load template content. Receives the resolved template path.
```

--------------------------------

### YAPL Number Syntax

Source: https://yapl-language.github.io/documentation/reference/syntax

Demonstrates the syntax for representing numbers in YAPL, including integers, floating-point numbers, and variables.

```yapl
{{ 42 }}



{{ 3.14159 }}



{{ variable_containing_number }}
```

--------------------------------

### Debugging Nested Property Access in YAPL

Source: https://yapl-language.github.io/documentation/troubleshooting

Demonstrates how to debug issues with accessing nested properties in YAPL. It includes examples of accessing nested properties, logging the data structure using `JSON.stringify`, and common pitfalls like null values or typos.

```javascript
{{ user.profile.email }}  {# Returns empty #}
```

```javascript
const data = {
  user: {
    profile: {
      email: "alice@example.com",
    },
  },
};

// Check data structure
console.log(JSON.stringify(data, null, 2));
```

```javascript
const data = {
  user: null, // This breaks user.profile.email
};
```

```javascript
const data = {
  user: {
    profil: {
      // Typo: should be "profile"
      email: "alice@example.com",
    },
  },
};
```