diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml new file mode 100644 index 0000000..cf3b7af --- /dev/null +++ b/.github/workflows/deploy_docs.yml @@ -0,0 +1,43 @@ +name: "Deploy Documentation" +run-name: "Deploy Documentation (@${{ github.actor }})" + +on: + workflow_call: + secrets: + RAILWAY_PROJECT_TOKEN: + required: true + RAILWAY_SERVICE: + required: true + push: + branches: + - main + paths: + - 'docs/**' + +jobs: + deploy_docs: + env: + RAILWAY_TOKEN: ${{ secrets.RAILWAY_PROJECT_TOKEN }} + runs-on: ubuntu-latest + + steps: + - name: Check out code + uses: actions/checkout@v3 + + - name: Install Node.js + uses: actions/setup-node@v3 + with: + node-version: '16' + + - name: Install Documentation Dependencies + run: | + cd docs/docs_project + npm install + + - name: Install Railway CLI + run: npm install -g @railway/cli + + - name: Deploy Documentation + run: | + cp -r django_cotton docs/docs_project + railway up --service=${{ secrets.RAILWAY_SERVICE }} \ No newline at end of file diff --git a/.github/workflows/publish_to_pypi.yml b/.github/workflows/publish_to_pypi.yml new file mode 100644 index 0000000..a7a8025 --- /dev/null +++ b/.github/workflows/publish_to_pypi.yml @@ -0,0 +1,48 @@ +name: "Publish to PyPI" +run-name: "Publish to PyPI (@${{ github.actor }})" + +on: + push: + branches: + - main + paths: + - '**' + - '!docs/**' + +jobs: + publish_pypi: + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + - name: Install required libraries + run: python3 -m pip install toml + + - name: Update Version in pyproject.toml + run: | + git fetch origin main + git reset --hard origin/main + python -c "import toml; f = open('./pyproject.toml', 'r'); c = toml.load(f); f.close(); v = list(map(int, c['tool']['poetry']['version'].split('.'))); v[-1] += 1; c['tool']['poetry']['version'] = '.'.join(map(str, v)); f = open('./pyproject.toml', 'w'); toml.dump(c, f); f.close();" + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + git add -A + git commit -m "Automatic version bump" --allow-empty + git push origin main + + - name: Build and publish to PyPI + uses: JRubics/poetry-publish@v1.17 + with: + pypi_token: ${{ secrets.PYPI_TOKEN }} + + trigger_deploy_docs: + needs: publish_pypi + uses: ./.github/workflows/deploy_docs.yml + secrets: + RAILWAY_PROJECT_TOKEN: ${{ secrets.RAILWAY_PROJECT_TOKEN }} + RAILWAY_SERVICE: ${{ secrets.RAILWAY_SERVICE }} \ No newline at end of file diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..a220059 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,30 @@ +name: Test + +on: + workflow_dispatch: + + pull_request: + branches: + - "main" + +jobs: + run_tests: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Build + run: | + docker build -f dev/docker/Dockerfile -t cotton-test-app dev/example_project + + - name: Start Container + run: | + docker-compose -f dev/docker/docker-compose.yaml up -d + + - name: Run Tests + run: docker exec -t cotton-dev-app python manage.py test + + - name: Stop and Remove Services + run: docker-compose -f dev/docker/docker-compose.yaml down \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..52e38e2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,115 @@ +# Django # +*.log +*.pot +*.pyc +__pycache__ +db.sqlite3 +media +**/static/app.css + +# Backup files # +*.bak + +# File-based project format +*.iws + +# IntelliJ +out/ +.idea/ + +# JIRA plugin +atlassian-ide-plugin.xml + +# Python # +*.py[cod] +*$py.class + +# Distribution / packaging +.Python build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +.pytest_cache/ +nosetests.xml +coverage.xml +*.cover +.hypothesis/ + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery +celerybeat-schedule.* + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ + +# Sublime Text # +*.tmlanguage.cache +*.tmPreferences.cache +*.stTheme.cache +*.sublime-workspace +*.sublime-project + +# sftp configuration file +sftp-config.json + +# Package control specific files Package +Control.last-run +Control.ca-list +Control.ca-bundle +Control.system-ca-bundle +GitHub.sublime-settings + +# Visual Studio Code # +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +.history + +.DS_Store + diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b4003bf --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 dyvenia + +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. diff --git a/README.md b/README.md index 90c1dac..7a7cdf7 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,139 @@ -# cotton -Bringing component based design to Django templates +# Cotton + +Bringing component-based design to Django templates. + +Document site + +## Overview +Cotton enhances Django templates by allowing component-based design, making UI composition more efficient and reusable. It integrates seamlessly with Tailwind CSS and retains full compatibility with native Django template features. + +## Key Features +- **Rapid UI Composition:** Efficiently compose and reuse UI components. +- **Tailwind CSS Harmony:** Integrates with Tailwind's utility-first approach. +- **Interoperable with Django:** Enhances Django templates without replacing them. +- **Semantic Syntax:** HTML-like syntax for better code editor support. +- **Minimal Overhead:** Compiles to native Django components with automatic caching. + +## Getting Started + +### Installation +To install Cotton, run the following command: + +```bash +pip install django-cotton +``` + +Then update your `settings.py`: + +```python +INSTALLED_APPS = [ + ... + 'django_cotton', +] + +TEMPLATES = [ + { + 'BACKEND': 'django.template.backends.django.DjangoTemplates', + 'DIRS': ['your_project/templates'], + 'APP_DIRS': False, + 'OPTIONS': { + 'loaders': [ + 'django_cotton.template.loaders.CottonLoader', + # continue with default loaders: + # "django.template.loaders.filesystem.Loader", + # "django.template.loaders.app_directories.Loader", + ], + 'builtins': [ + 'django_cotton.templatetags.cotton', + ], + }, + }, +] +``` + +### Quickstart +Create a new directory in your templates directory called `cotton`. Inside this directory, create a new file called `card.cotton.html` with the following content: + +```html +
+

{{ title }}

+

{{ slot }}

+ +
+``` + +Create a view with a template. Views that contain Cotton components must also use the `.cotton.html` extension: + +```python +# views.py +def dashboard_view(request): + return render(request, "dashboard.cotton.html") +``` + +```html + + + We have the best trees + + + + The best spades in the land + +``` + +### Usage Basics +- **Template Extensions:** View templates including Cotton components should use the `.cotton.html` extension. +- **Component Placement:** Components should be placed in the `templates/cotton` folder. +- **Naming Conventions:** + - Component filenames use snake_case: `my_component.cotton.html` + - Components are called using kebab-case: `` + +### Example +A minimal example using Cotton components: + +```html + +{{ slot }} + + + +

Some content

+
+``` + +### Attributes and Slots +Components can accept attributes and named slots for flexible content and behavior customization: + +```html + +

It's {{ temperature }}{{ unit }} and the condition is {{ condition }}.

+ + + +``` + +#### Passing Variables +To pass a variable from the parent's context, prepend the attribute with a `:`. + +```html + + +``` + +#### Named Slots +```html + +
+

{{ day }}:

{{ icon }} {{ label }} +
+ + + + + ... + + +

Sunny

+
+
+``` \ No newline at end of file diff --git a/dev/docker/Dockerfile b/dev/docker/Dockerfile new file mode 100644 index 0000000..af762ed --- /dev/null +++ b/dev/docker/Dockerfile @@ -0,0 +1,29 @@ +ARG PLATFORM=linux/amd64 + +# Use an official Python runtime as a base image +FROM python:3.9-slim + +# Keep logs unbuffered +ENV PYTHONUNBUFFERED 1 + +# Set the working directory in the container +WORKDIR /app + +# Install Poetry +RUN pip install --upgrade pip \ + && pip install poetry + +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + chromium \ + chromium-driver \ + && rm -rf /var/lib/apt/lists/* + +# Copy only dependencies definition to the docker image +COPY . /app/ + +# Install project dependencies +RUN poetry config virtualenvs.create false \ + && poetry install + +CMD [ "python", "manage.py", "runserver", "0.0.0.0:8000" ] \ No newline at end of file diff --git a/dev/docker/bin/build.sh b/dev/docker/bin/build.sh new file mode 100755 index 0000000..f4576f1 --- /dev/null +++ b/dev/docker/bin/build.sh @@ -0,0 +1,16 @@ +#!/bin/bash + +# if arg exists 'mac', then build for mac +if [ "$1" = "mac" ]; then + PLATFORM="linux/arm64" +else + PLATFORM="linux/amd64" +fi + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR + +docker build --no-cache --build-arg PLATFORM=$PLATFORM -f ../Dockerfile ../../example_project -t cotton-test-app \ No newline at end of file diff --git a/dev/docker/bin/manage.sh b/dev/docker/bin/manage.sh new file mode 100755 index 0000000..5654dfd --- /dev/null +++ b/dev/docker/bin/manage.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash + +# Start a new login shell to preserve history and execute the Docker command +bash -l -c "docker exec -it cotton-dev-app python manage.py $*" \ No newline at end of file diff --git a/dev/docker/bin/run-dev.sh b/dev/docker/bin/run-dev.sh new file mode 100755 index 0000000..d592c93 --- /dev/null +++ b/dev/docker/bin/run-dev.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR + +docker compose -f ../docker-compose.yaml up "$@" diff --git a/dev/docker/bin/shell.sh b/dev/docker/bin/shell.sh new file mode 100755 index 0000000..2cf7331 --- /dev/null +++ b/dev/docker/bin/shell.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR/.. + +docker exec -it cotton-dev-app python manage.py shell \ No newline at end of file diff --git a/dev/docker/bin/stop.sh b/dev/docker/bin/stop.sh new file mode 100755 index 0000000..4d46178 --- /dev/null +++ b/dev/docker/bin/stop.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR/.. + +docker compose -f etc/docker/docker-compose.yaml -f etc/docker/docker-compose.dev.yaml down $* \ No newline at end of file diff --git a/dev/docker/bin/terminal.sh b/dev/docker/bin/terminal.sh new file mode 100755 index 0000000..f67f975 --- /dev/null +++ b/dev/docker/bin/terminal.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +docker exec -it cotton-dev-app bash \ No newline at end of file diff --git a/dev/docker/bin/test.sh b/dev/docker/bin/test.sh new file mode 100755 index 0000000..e16436b --- /dev/null +++ b/dev/docker/bin/test.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +docker exec -t cotton-dev-app python manage.py test $* diff --git a/dev/docker/docker-compose.yaml b/dev/docker/docker-compose.yaml new file mode 100644 index 0000000..e5fc9b9 --- /dev/null +++ b/dev/docker/docker-compose.yaml @@ -0,0 +1,16 @@ +version: '3' + +services: + web: + container_name: cotton-dev-app + restart: always + image: cotton-test-app + working_dir: /app + command: python manage.py runserver 0.0.0.0:8000 + environment: + - DEBUG=True + volumes: + - ../example_project:/app + - ../../django_cotton:/app/django_cotton + ports: + - 8001:8000 diff --git a/dev/example_project/example_project/__init__.py b/dev/example_project/example_project/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/dev/example_project/example_project/asgi.py b/dev/example_project/example_project/asgi.py new file mode 100644 index 0000000..fa0e5e9 --- /dev/null +++ b/dev/example_project/example_project/asgi.py @@ -0,0 +1,16 @@ +""" +ASGI config for django_cotton project. + +It exposes the ASGI callable as a module-level variable named ``application``. + +For more information on this file, see +https://docs.djangoproject.com/en/4.2/howto/deployment/asgi/ +""" + +import os + +from django.core.asgi import get_asgi_application + +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings") + +application = get_asgi_application() diff --git a/dev/example_project/example_project/settings.py b/dev/example_project/example_project/settings.py new file mode 100644 index 0000000..f9760bd --- /dev/null +++ b/dev/example_project/example_project/settings.py @@ -0,0 +1,136 @@ +""" +Django settings for django_cotton project. + +Generated by 'django-admin startproject' using Django 4.2.8. + +For more information on this file, see +https://docs.djangoproject.com/en/4.2/topics/settings/ + +For the full list of settings and their values, see +https://docs.djangoproject.com/en/4.2/ref/settings/ +""" +from pathlib import Path + +# SETTINGS_PATH = os.path.dirname(os.path.dirname(__file__)) + +# Build paths inside the project like this: BASE_DIR / 'subdir'. +BASE_DIR = Path(__file__).resolve().parent.parent + + +# Quick-start development settings - unsuitable for production +# See https://docs.djangoproject.com/en/4.2/howto/deployment/checklist/ + +# SECURITY WARNING: keep the secret key used in production secret! +SECRET_KEY = "django-insecure-%)7a&zw=le4uey^36*z*9^4#*iii65t)nyt$36mxq70@=(z6^n" + +# SECURITY WARNING: don't run with debug turned on in production! +DEBUG = True + +ALLOWED_HOSTS = ["0.0.0.0"] + + +# Application definition + +INSTALLED_APPS = [ + "django.contrib.admin", + "django.contrib.auth", + "django.contrib.contenttypes", + "django.contrib.sessions", + "django.contrib.messages", + "django.contrib.staticfiles", + "django_cotton", +] + +MIDDLEWARE = [ + "django.middleware.security.SecurityMiddleware", + "django.contrib.sessions.middleware.SessionMiddleware", + "django.middleware.common.CommonMiddleware", + "django.middleware.csrf.CsrfViewMiddleware", + "django.contrib.auth.middleware.AuthenticationMiddleware", + "django.contrib.messages.middleware.MessageMiddleware", + "django.middleware.clickjacking.XFrameOptionsMiddleware", +] + +ROOT_URLCONF = "django_cotton.urls" + +TEMPLATES = [ + { + "BACKEND": "django.template.backends.django.DjangoTemplates", + "DIRS": ["example_project/templates", "django_cotton/templates"], + "APP_DIRS": False, + "OPTIONS": { + "context_processors": [ + "django.template.context_processors.debug", + "django.template.context_processors.request", + "django.contrib.auth.context_processors.auth", + "django.contrib.messages.context_processors.messages", + ], + "loaders": [ + "django_cotton.cotton_loader.Loader", + "django.template.loaders.filesystem.Loader", + "django.template.loaders.app_directories.Loader", + ], + "builtins": [ + "django.templatetags.static", + "django_cotton.templatetags.cotton", + ], + }, + }, +] + +WSGI_APPLICATION = "django_cotton.wsgi.application" + + +# Database +# https://docs.djangoproject.com/en/4.2/ref/settings/#databases + +DATABASES = { + "default": { + "ENGINE": "django.db.backends.sqlite3", + "NAME": BASE_DIR / "db.sqlite3", + } +} + + +# Password validation +# https://docs.djangoproject.com/en/4.2/ref/settings/#auth-password-validators + +AUTH_PASSWORD_VALIDATORS = [ + { + "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator", + }, + { + "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator", + }, + { + "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator", + }, + { + "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator", + }, +] + + +# Internationalization +# https://docs.djangoproject.com/en/4.2/topics/i18n/ + +LANGUAGE_CODE = "en-us" + +TIME_ZONE = "UTC" + +USE_I18N = True + +USE_TZ = True + + +# Static files (CSS, JavaScript, Images) +# https://docs.djangoproject.com/en/4.2/howto/static-files/ + +STATIC_URL = "static/" + +# Default primary key field type +# https://docs.djangoproject.com/en/4.2/ref/settings/#default-auto-field + +DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField" + +COTTON_TEMPLATE_CACHING_ENABLED = False diff --git a/dev/example_project/example_project/templates/child_test.cotton.html b/dev/example_project/example_project/templates/child_test.cotton.html new file mode 100644 index 0000000..ec03be8 --- /dev/null +++ b/dev/example_project/example_project/templates/child_test.cotton.html @@ -0,0 +1,3 @@ + + d + \ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/benchmarks/cotton.cotton.html b/dev/example_project/example_project/templates/cotton/benchmarks/cotton.cotton.html new file mode 100644 index 0000000..57996ab --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/benchmarks/cotton.cotton.html @@ -0,0 +1,9 @@ + + I'm default + + I'm top + + + I'm bottom + + \ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/benchmarks/cotton_compiled.html b/dev/example_project/example_project/templates/cotton/benchmarks/cotton_compiled.html new file mode 100644 index 0000000..fa0c4e3 --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/benchmarks/cotton_compiled.html @@ -0,0 +1,9 @@ +{% cotton_component cotton/benchmarks/partials/main.cotton.html %} + I'm default + {% cotton_slot top %} + I'm top + {% end_cotton_slot %} + {% cotton_slot bottom %} + I'm bottom + {% end_cotton_slot %} +{% end_cotton_component %} \ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/benchmarks/native_extends.html b/dev/example_project/example_project/templates/cotton/benchmarks/native_extends.html new file mode 100644 index 0000000..4c774a7 --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/benchmarks/native_extends.html @@ -0,0 +1,13 @@ +{% extends "cotton/benchmarks/partials/native_main.html" %} + +{% block top %} +I'm top +{% endblock %} + +{% block content %} +I'm default +{% endblock %} + +{% block bottom %} +I'm bottom +{% endblock %} \ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/benchmarks/partials/main.cotton.html b/dev/example_project/example_project/templates/cotton/benchmarks/partials/main.cotton.html new file mode 100644 index 0000000..03e5aaf --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/benchmarks/partials/main.cotton.html @@ -0,0 +1,5 @@ +{{ top }} + +{{ slot }} + +{{ bottom }} \ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/benchmarks/partials/native_main.html b/dev/example_project/example_project/templates/cotton/benchmarks/partials/native_main.html new file mode 100644 index 0000000..b8def10 --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/benchmarks/partials/native_main.html @@ -0,0 +1,5 @@ +{% block top %}{% endblock %} + +{% block content %}{% endblock %} + +{% block bottom %}{% endblock %} \ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/child.cotton.html b/dev/example_project/example_project/templates/cotton/child.cotton.html new file mode 100644 index 0000000..9f989fa --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/child.cotton.html @@ -0,0 +1 @@ +
\ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/named_slot_component.cotton.html b/dev/example_project/example_project/templates/cotton/named_slot_component.cotton.html new file mode 100644 index 0000000..e324e2c --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/named_slot_component.cotton.html @@ -0,0 +1,3 @@ +
+ {{ name }} +
\ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/parent.cotton.html b/dev/example_project/example_project/templates/cotton/parent.cotton.html new file mode 100644 index 0000000..c534580 --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/parent.cotton.html @@ -0,0 +1,3 @@ +
+ {{slot}} +
\ No newline at end of file diff --git a/dev/example_project/example_project/templates/cotton/props_test_component.cotton.html b/dev/example_project/example_project/templates/cotton/props_test_component.cotton.html new file mode 100644 index 0000000..1005946 --- /dev/null +++ b/dev/example_project/example_project/templates/cotton/props_test_component.cotton.html @@ -0,0 +1,12 @@ + + +
+ {{ testy }} +

prop1: '{{ prop1 }}'

+

attr1: '{{ attr1 }}'

+

empty_prop: '{{ empty_prop }}'

+

prop_with_default: '{{ prop_with_default }}'

+

slot: '{{ slot }}'

+

named_slot: '{{ named_slot }}'

+

attrs: '{{ attrs }}'

+
diff --git a/dev/example_project/example_project/templates/form_test.cotton.html b/dev/example_project/example_project/templates/form_test.cotton.html new file mode 100644 index 0000000..6c70273 --- /dev/null +++ b/dev/example_project/example_project/templates/form_test.cotton.html @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/dev/example_project/example_project/templates/named_slot_in_loop.cotton.html b/dev/example_project/example_project/templates/named_slot_in_loop.cotton.html new file mode 100644 index 0000000..136d7c1 --- /dev/null +++ b/dev/example_project/example_project/templates/named_slot_in_loop.cotton.html @@ -0,0 +1,7 @@ +{% for item in items %} + + + item name: {{ item.name }} + + +{% endfor %} \ No newline at end of file diff --git a/dev/example_project/example_project/templates/parent_test.cotton.html b/dev/example_project/example_project/templates/parent_test.cotton.html new file mode 100644 index 0000000..9922300 --- /dev/null +++ b/dev/example_project/example_project/templates/parent_test.cotton.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/dev/example_project/example_project/templates/props_test.cotton.html b/dev/example_project/example_project/templates/props_test.cotton.html new file mode 100644 index 0000000..5f575c6 --- /dev/null +++ b/dev/example_project/example_project/templates/props_test.cotton.html @@ -0,0 +1,3 @@ + + default slot + \ No newline at end of file diff --git a/dev/example_project/example_project/templates/self_closing_test.cotton.html b/dev/example_project/example_project/templates/self_closing_test.cotton.html new file mode 100644 index 0000000..9c99f37 --- /dev/null +++ b/dev/example_project/example_project/templates/self_closing_test.cotton.html @@ -0,0 +1,4 @@ +{% load static %} + + + \ No newline at end of file diff --git a/dev/example_project/manage.py b/dev/example_project/manage.py new file mode 100755 index 0000000..0a41077 --- /dev/null +++ b/dev/example_project/manage.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python +"""Django's command-line utility for administrative tasks.""" +import os +import sys + + +def main(): + """Run administrative tasks.""" + os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings") + try: + from django.core.management import execute_from_command_line + except ImportError as exc: + raise ImportError( + "Couldn't import Django. Are you sure it's installed and " + "available on your PYTHONPATH environment variable? Did you " + "forget to activate a virtual environment?" + ) from exc + execute_from_command_line(sys.argv) + + +if __name__ == "__main__": + main() diff --git a/dev/example_project/pyproject.toml b/dev/example_project/pyproject.toml new file mode 100644 index 0000000..761d3f3 --- /dev/null +++ b/dev/example_project/pyproject.toml @@ -0,0 +1,24 @@ +[project] +name = "cotton-dev-app" +requires-python = ">=3.8, <4" +dependencies = [ + "django~=4.2.6", + "beautifulsoup4~=4.12.2", + "selenium~=4.13.0", + "chromedriver-py~=117.0.5938.92", + "webdriver-manager~=4.0.1" +] + +[tool.poetry] +name = "cotton-dev-app" +version = "0.1" +description = "Development and test app for the django package." +authors = ["Will Abbott "] + +[tool.poetry.dependencies] +python = "^3.8" +Django = "^4.2" +beautifulsoup4 = "~4.12.2" +selenium = "~4.13.0" +chromedriver-py = "~117.0.5938.92" +webdriver-manager = "~4.0.1" \ No newline at end of file diff --git a/dev/example_project/render_load_test.py b/dev/example_project/render_load_test.py new file mode 100644 index 0000000..83e70d3 --- /dev/null +++ b/dev/example_project/render_load_test.py @@ -0,0 +1,71 @@ +from django.conf import settings +import time +from django.template.loader import render_to_string +import django + +# Configure Django settings +settings.configure( + INSTALLED_APPS=[ + "django.contrib.admin", + "django.contrib.auth", + "django.contrib.contenttypes", + "django.contrib.sessions", + "django.contrib.messages", + "django.contrib.staticfiles", + "django_cotton", + ], + TEMPLATES=[ + { + "BACKEND": "django.template.backends.django.DjangoTemplates", + "DIRS": ["example_project/templates"], + "APP_DIRS": False, + "OPTIONS": { + "context_processors": [ + "django.template.context_processors.debug", + "django.template.context_processors.request", + "django.contrib.auth.context_processors.auth", + "django.contrib.messages.context_processors.messages", + ], + "loaders": [ + "django_cotton.cotton_loader.Loader", + "django.template.loaders.filesystem.Loader", + "django.template.loaders.app_directories.Loader", + ], + "builtins": [ + "django.templatetags.static", + "django_cotton.templatetags.cotton", + ], + }, + }, + ], +) + +django.setup() + + +def benchmark_template_rendering(template_name, iterations=1000): + start_time = time.time() + for _ in range(iterations): + render_to_string(template_name) + end_time = time.time() + return end_time - start_time, render_to_string(template_name) + + +# Benchmarking each template +time_native_extends, output_native_extends = benchmark_template_rendering( + "cotton/benchmarks/native_extends.html" +) +# time_native_include, output_native_include = benchmark_template_rendering('cotton/benchmarks/native_include.html') +time_compiled_cotton, output_compiled_cotton = benchmark_template_rendering( + "cotton/benchmarks/cotton_compiled.html" +) +time_cotton, output_cotton = benchmark_template_rendering( + "cotton/benchmarks/cotton.cotton.html" +) + + +# Output results +print(f"Native Django Template using extend: {time_native_extends} seconds") +# print(f"Native Django Template using include: {time_native_include} seconds") +print(f"Compiled Cotton Template: {time_compiled_cotton} seconds") +print(f"Cotton Template: {time_cotton} seconds") diff --git a/django_cotton/__init__.py b/django_cotton/__init__.py new file mode 100644 index 0000000..e262b60 --- /dev/null +++ b/django_cotton/__init__.py @@ -0,0 +1 @@ +_with_prop_prefix = "cotton_with_prop_" diff --git a/django_cotton/cotton_loader.py b/django_cotton/cotton_loader.py new file mode 100755 index 0000000..c192f82 --- /dev/null +++ b/django_cotton/cotton_loader.py @@ -0,0 +1,291 @@ +import os +import re +import hashlib +import warnings + +from django.template.loaders.base import Loader as BaseLoader +from django.core.exceptions import SuspiciousFileOperation +from django.template import TemplateDoesNotExist +from django.utils._os import safe_join +from django.template import Template +from django.core.cache import cache +from django.template import Origin +from django.conf import settings + +from bs4 import BeautifulSoup, MarkupResemblesLocatorWarning + +warnings.filterwarnings("ignore", category=MarkupResemblesLocatorWarning) + + +class Loader(BaseLoader): + is_usable = True + + def __init__(self, engine, dirs=None): + super().__init__(engine) + self.cache_handler = CottonTemplateCacheHandler() + self.dirs = dirs + self.django_syntax_placeholders = [] + + def get_template_from_string(self, template_string): + """Create and return a Template object from a string. Used primarily for testing.""" + return Template(template_string, engine=self.engine) + + def get_contents(self, origin): + # check if file exists, whilst getting the mtime for cache key + try: + mtime = os.path.getmtime(origin.name) + except FileNotFoundError: + raise TemplateDoesNotExist(origin) + + # check and return cached template + cache_key = self.cache_handler.get_cache_key(origin.template_name, mtime) + cached_content = self.cache_handler.get_cached_template(cache_key) + if cached_content is not None: + return cached_content + + # If not cached, process the template + template_string = self._get_template_string(origin.name) + + # We need to provide a key to the current view or component (in this case, view) so that we can namespace + # slot data, preventing bleeding and ensure component's clear only data in the context applicable to itself + # in this case, we're top level, likely in a view so we use the view template name as the key + component_key = ( + origin.template_name.lstrip("cotton/") + .rstrip(".cotton.html") + .replace("/", ".") + ) + + compiled_template = self._compile_template_from_string( + template_string, component_key + ) + + # Cache the processed template + self.cache_handler.cache_template(cache_key, compiled_template) + + return compiled_template + + def _replace_syntax_with_placeholders(self, content): + """# replace {% ... %} and {{ ... }} with placeholders so they dont get touched + or encoded by bs4. Store them to later switch them back in after transformation. + """ + self.django_syntax_placeholders = [] + + # First handle cotton_verbatim blocks, this is designed to preserve and display cotton syntax, + # akin to the verbatim tag in Django. + def replace_cotton_verbatim(match): + inner_content = match.group( + 1 + ) # Get the inner content without the cotton_verbatim tags + self.django_syntax_placeholders.append(inner_content) + return f"__django_syntax__{len(self.django_syntax_placeholders)}__" + + # Replace cotton_verbatim blocks, capturing inner content + content = re.sub( + r"\{% cotton_verbatim %\}(.*?)\{% endcotton_verbatim %\}", + replace_cotton_verbatim, + content, + flags=re.DOTALL, + ) + + content = re.sub( + r"\{%.*?%\}", + lambda x: self.django_syntax_placeholders.append(x.group(0)) + or f"__django_syntax__{len(self.django_syntax_placeholders)}__", + content, + ) + content = re.sub( + r"\{\{.*?\}\}", + lambda x: self.django_syntax_placeholders.append(x.group(0)) + or f"__django_syntax__{len(self.django_syntax_placeholders)}__", + content, + ) + + return content + + def _replace_placeholders_with_syntax(self, content): + """After modifying the content, replace the placeholders with the django template tags and variables.""" + for i, placeholder in enumerate(self.django_syntax_placeholders, 1): + content = content.replace(f"__django_syntax__{i}__", placeholder) + + return content + + def _get_template_string(self, template_name): + try: + with open(template_name, "r") as f: + content = f.read() + except FileNotFoundError: + raise TemplateDoesNotExist(template_name) + + return content + + def _compile_template_from_string(self, content, component_key): + content = self._replace_syntax_with_placeholders(content) + content = self._compile_cotton_to_django(content, component_key) + content = self._replace_placeholders_with_syntax(content) + content = self._revert_bs4_attribute_empty_attribute_fixing(content) + + return content + + def _revert_bs4_attribute_empty_attribute_fixing(self, contents): + """Django's template parser adds ="" to empty attribute-like parts in any html-like node, i.e.
gets + compiled to
Then if 'something' is holding attributes sets, the last attribute value is + not quoted. i.e. model=test not model="test".""" + cleaned_content = re.sub('}}=""', "}}", contents) + return cleaned_content + + def get_dirs(self): + return self.dirs if self.dirs is not None else self.engine.dirs + + def get_template_sources(self, template_name): + """Return an Origin object pointing to an absolute path in each directory + in template_dirs. For security reasons, if a path doesn't lie inside + one of the template_dirs it is excluded from the result set.""" + if template_name.endswith(".cotton.html"): + for template_dir in self.get_dirs(): + try: + name = safe_join(template_dir, template_name) + except SuspiciousFileOperation: + # The joined path was located outside of this template_dir + # (it might be inside another one, so this isn't fatal). + continue + + yield Origin( + name=name, + template_name=template_name, + loader=self, + ) + + def _compile_cotton_to_django(self, html_content, component_key): + """Convert cotton tag with the cotton_props string. + tag.replace_with(cotton_props_str) + + return soup + + def _wrap_with_cotton_props_frame(self, soup): + """Wrap content with {% cotton_props_frame %} to be able to govern props and attributes. In order to recognise + props defined in a component and also have them available in context, we wrap the entire contents in another + component: cotton_props_frame.""" + props_with_defaults = [] + c_props = soup.find("c-props") + + # parse c-props tag to extract properties and defaults + if c_props: + props_with_defaults = [] + for prop, value in c_props.attrs.items(): + if value is None: + props_with_defaults.append(f"{prop}={prop}") + else: + # Assuming value is already a string that represents the default value + props_with_defaults.append(f'{prop}={prop}|default:"{value}"') + + c_props.decompose() + + # Construct the {% with %} opening tag + opening = "{% cotton_props_frame " + " ".join(props_with_defaults) + " %}" + closing = "{% endcotton_props_frame %}" + + # Convert the remaining soup back to a string and wrap it within {% with %} block + wrapped_content = opening + str(soup).strip() + closing + + # Since we can't replace the soup object itself, we create new soup instead + new_soup = BeautifulSoup(wrapped_content, "html.parser") + + return new_soup + + def _transform_named_slot(self, slot_tag, component_key): + """Replace tags with the {% cotton_slot %} template tag""" + # for c_slot in soup.find_all("c-slot"): + slot_name = slot_tag.get("name", "").strip() + inner_html = "".join(str(content) for content in slot_tag.contents) + + # Check and process any components in the slot content + + slot_soup = BeautifulSoup(inner_html, "html.parser") + self._transform_components(slot_soup, component_key) + + cotton_slot_tag = f"{{% cotton_slot {slot_name} {component_key} %}}{str(slot_soup)}{{% end_cotton_slot %}}" + + slot_tag.replace_with(BeautifulSoup(cotton_slot_tag, "html.parser")) + + def _transform_components(self, soup, component_key): + """Replace tags with the {% cotton_component %} template tag""" + for tag in soup.find_all(re.compile("^c-"), recursive=True): + if tag.name == "c-slot": + self._transform_named_slot(tag, component_key) + + continue + + component_name = tag.name[2:] + + # Convert dot notation to path structure and replace hyphens with underscores + path = component_name.replace(".", "/").replace("-", "_") + + # Construct the opening tag + opening_tag = f"{{% cotton_component {'cotton/{}.cotton.html'.format(path)} {component_name} " + for attr, value in tag.attrs.items(): + if attr == "class": + value = " ".join(value) + opening_tag += ' {}="{}"'.format(attr, value) + opening_tag += " %}" + + # Construct the closing tag + closing_tag = "{% end_cotton_component %}" + + if tag.contents: + tag_soup = BeautifulSoup(tag.decode_contents(), "html.parser") + self._transform_components(tag_soup, component_name) + + # Create new content with opening tag, tag content, and closing tag + new_content = opening_tag + str(tag_soup) + closing_tag + + else: + # Create new content with opening tag and closing tag + new_content = opening_tag + closing_tag + + # Replace the original tag with the new content + new_soup = BeautifulSoup(new_content, "html.parser") + tag.replace_with(new_soup) + + return soup + + +class CottonTemplateCacheHandler: + """Handles caching of cotton templates so the html parsing is only done on first load of each view or component.""" + + def __init__(self): + self.enabled = getattr(settings, "TEMPLATE_CACHING_ENABLED", True) + + def get_cache_key(self, template_name, mtime): + template_hash = hashlib.sha256(template_name.encode()).hexdigest() + return f"cotton_cache_{template_hash}_{mtime}" + + def get_cached_template(self, cache_key): + if not self.enabled: + return None + return cache.get(cache_key) + + def cache_template(self, cache_key, content, timeout=None): + if self.enabled: + cache.set(cache_key, content, timeout=timeout) diff --git a/django_cotton/templates/attribute_merging_test.cotton.html b/django_cotton/templates/attribute_merging_test.cotton.html new file mode 100644 index 0000000..ebcf664 --- /dev/null +++ b/django_cotton/templates/attribute_merging_test.cotton.html @@ -0,0 +1,3 @@ + + ss + \ No newline at end of file diff --git a/django_cotton/templates/attribute_passing_test.cotton.html b/django_cotton/templates/attribute_passing_test.cotton.html new file mode 100644 index 0000000..a7bc9fc --- /dev/null +++ b/django_cotton/templates/attribute_passing_test.cotton.html @@ -0,0 +1,3 @@ + + ss + \ No newline at end of file diff --git a/django_cotton/templates/child_test.cotton.html b/django_cotton/templates/child_test.cotton.html new file mode 100644 index 0000000..ec03be8 --- /dev/null +++ b/django_cotton/templates/child_test.cotton.html @@ -0,0 +1,3 @@ + + d + \ No newline at end of file diff --git a/django_cotton/templates/cotton/child.cotton.html b/django_cotton/templates/cotton/child.cotton.html new file mode 100644 index 0000000..9f989fa --- /dev/null +++ b/django_cotton/templates/cotton/child.cotton.html @@ -0,0 +1 @@ +
\ No newline at end of file diff --git a/django_cotton/templates/cotton/container.cotton.html b/django_cotton/templates/cotton/container.cotton.html new file mode 100644 index 0000000..835e5c4 --- /dev/null +++ b/django_cotton/templates/cotton/container.cotton.html @@ -0,0 +1,11 @@ +
+ Header: + {{ header }} +
+ +
+ Content: + {{ slot }} +
+ + diff --git a/django_cotton/templates/cotton/merges_attributes.cotton.html b/django_cotton/templates/cotton/merges_attributes.cotton.html new file mode 100644 index 0000000..ef33d94 --- /dev/null +++ b/django_cotton/templates/cotton/merges_attributes.cotton.html @@ -0,0 +1,3 @@ +
+ +
\ No newline at end of file diff --git a/django_cotton/templates/cotton/named_slot_component.cotton.html b/django_cotton/templates/cotton/named_slot_component.cotton.html new file mode 100644 index 0000000..e324e2c --- /dev/null +++ b/django_cotton/templates/cotton/named_slot_component.cotton.html @@ -0,0 +1,3 @@ +
+ {{ name }} +
\ No newline at end of file diff --git a/django_cotton/templates/cotton/parent.cotton.html b/django_cotton/templates/cotton/parent.cotton.html new file mode 100644 index 0000000..c534580 --- /dev/null +++ b/django_cotton/templates/cotton/parent.cotton.html @@ -0,0 +1,3 @@ +
+ {{slot}} +
\ No newline at end of file diff --git a/django_cotton/templates/cotton/receives_attributes.cotton.html b/django_cotton/templates/cotton/receives_attributes.cotton.html new file mode 100644 index 0000000..8d463b4 --- /dev/null +++ b/django_cotton/templates/cotton/receives_attributes.cotton.html @@ -0,0 +1,3 @@ +
+ +
\ No newline at end of file diff --git a/django_cotton/templates/cotton/test_component.cotton.html b/django_cotton/templates/cotton/test_component.cotton.html new file mode 100644 index 0000000..c1cddfe --- /dev/null +++ b/django_cotton/templates/cotton/test_component.cotton.html @@ -0,0 +1,13 @@ + + +

slot: '{{ slot }}'

+ +

attr1: '{{ attr1 }}'

+

attr2: '{{ attr2 }}'

+ +

prop1: '{{ prop1 }}'

+

default_prop: '{{ default_prop }}'

+ +

named_slot: '{{ named_slot }}'

+ +

attrs: '{{ attrs }}'

diff --git a/django_cotton/templates/django_syntax_decoding_test.cotton.html b/django_cotton/templates/django_syntax_decoding_test.cotton.html new file mode 100644 index 0000000..ee3d784 --- /dev/null +++ b/django_cotton/templates/django_syntax_decoding_test.cotton.html @@ -0,0 +1 @@ +
Hello, World!
\ No newline at end of file diff --git a/django_cotton/templates/form_test.cotton.html b/django_cotton/templates/form_test.cotton.html new file mode 100644 index 0000000..6c70273 --- /dev/null +++ b/django_cotton/templates/form_test.cotton.html @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/django_cotton/templates/named_slot_in_loop.cotton.html b/django_cotton/templates/named_slot_in_loop.cotton.html new file mode 100644 index 0000000..136d7c1 --- /dev/null +++ b/django_cotton/templates/named_slot_in_loop.cotton.html @@ -0,0 +1,7 @@ +{% for item in items %} + + + item name: {{ item.name }} + + +{% endfor %} \ No newline at end of file diff --git a/django_cotton/templates/parent_test.cotton.html b/django_cotton/templates/parent_test.cotton.html new file mode 100644 index 0000000..9922300 --- /dev/null +++ b/django_cotton/templates/parent_test.cotton.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/django_cotton/templates/self_closing_test.cotton.html b/django_cotton/templates/self_closing_test.cotton.html new file mode 100644 index 0000000..9c99f37 --- /dev/null +++ b/django_cotton/templates/self_closing_test.cotton.html @@ -0,0 +1,4 @@ +{% load static %} + + + \ No newline at end of file diff --git a/django_cotton/templates/string_with_spaces.cotton.html b/django_cotton/templates/string_with_spaces.cotton.html new file mode 100644 index 0000000..ab4ddb5 --- /dev/null +++ b/django_cotton/templates/string_with_spaces.cotton.html @@ -0,0 +1,5 @@ + + + named_slot with spaces + + \ No newline at end of file diff --git a/django_cotton/templates/variable_parsing_test.cotton.html b/django_cotton/templates/variable_parsing_test.cotton.html new file mode 100644 index 0000000..8402bd4 --- /dev/null +++ b/django_cotton/templates/variable_parsing_test.cotton.html @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/django_cotton/templatetags/__init__.py b/django_cotton/templatetags/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/django_cotton/templatetags/_component.py b/django_cotton/templatetags/_component.py new file mode 100644 index 0000000..eaf365c --- /dev/null +++ b/django_cotton/templatetags/_component.py @@ -0,0 +1,68 @@ +from django import template +from django.template import Node +from django.template.loader import render_to_string + + +def cotton_component(parser, token): + bits = token.split_contents() + tag_name = bits[0] + template_path = bits[1] + component_key = bits[2] + + kwargs = {} + for bit in bits[3:]: + key, value = bit.split("=") + if key.startswith(":"): # Detect variables + key = key[1:] # Remove ':' prefix + value = value.strip("'\"") # Remove quotes + kwargs[key] = template.Variable(value) # Treat as a variable + else: + kwargs[key] = value.strip("'\"") # Treat as a literal string + + nodelist = parser.parse(("end_cotton_component",)) + parser.delete_first_token() + + return CottonComponentNode(nodelist, template_path, component_key, kwargs) + + +class CottonComponentNode(Node): + def __init__(self, nodelist, template_path, component_key, kwargs): + self.nodelist = nodelist + self.template_path = template_path + self.component_key = component_key + self.kwargs = kwargs + + def render(self, context): + local_context = context.flatten() + + attrs = {} + for key, value in self.kwargs.items(): + if isinstance(value, template.Variable): # Resolve variables + try: + resolved_value = value.resolve(context) + attrs[key] = resolved_value + except template.VariableDoesNotExist: + pass # Handle variable not found, if necessary + else: + attrs[key] = value # Use literal string + + # Add the remainder as the default slot + rendered = self.nodelist.render(context) + local_context.update({"slot": rendered}) + + slots = context.get("cotton_slots", {}) + component_slots = slots.get(self.component_key, {}) + + local_context.update(component_slots) + local_context.update(attrs) + local_context.update({"attrs_dict": attrs}) + + rendered = render_to_string(self.template_path, local_context) + + # Now reset the component's slots in context to prevent bleeding + if self.component_key in slots: + slots[self.component_key] = {} + + context.update({"cotton_slots": slots}) + + return rendered diff --git a/django_cotton/templatetags/_props.py b/django_cotton/templatetags/_props.py new file mode 100644 index 0000000..e5f2961 --- /dev/null +++ b/django_cotton/templatetags/_props.py @@ -0,0 +1,43 @@ +from django import template + +register = template.Library() + + +def cotton_props(parser, token): + # Split the token to get variable assignments + parts = token.split_contents() + cotton_props = {} + for part in parts[1:]: + key, value = part.split("=") + cotton_props[key] = value + + return CottonPropNode(cotton_props) + + +class CottonPropNode(template.Node): + def __init__(self, cotton_props): + self.cotton_props = cotton_props + + def render(self, context): + resolved_props = {} + + # if the same var is already set in context, it's being passed explicitly to override the cotton_var + # if not, then we resolve it from the context + for key, value in self.cotton_props.items(): + # if key in context: + # resolved_props[key] = context[key] + # continue + try: + resolved_props[key] = template.Variable(value).resolve(context) + except (TypeError, template.VariableDoesNotExist): + resolved_props[key] = value + + cotton_props = {"cotton_props": resolved_props} + + # Update the global context directly + context.update(resolved_props) + context.update(cotton_props) + context.update({"cotton_props": resolved_props}) + context["cotton_props"].update(resolved_props) + + return "" diff --git a/django_cotton/templatetags/_props_frame.py b/django_cotton/templatetags/_props_frame.py new file mode 100644 index 0000000..e1c5492 --- /dev/null +++ b/django_cotton/templatetags/_props_frame.py @@ -0,0 +1,64 @@ +from django import template +from django.template.base import token_kwargs +from django.utils.safestring import mark_safe + +register = template.Library() + + +def cotton_props_frame(parser, token): + """The job of the props frame is to filter component kwargs (attributes) against declared props. It has to be + second component because we desire to declare props () inside the component template and therefore the + component can not manipulate its own context from it's own template, instead we declare the props frame + directly inside component""" + bits = token.split_contents()[1:] # Skip the tag name + # Parse token kwargs while maintaining token order + tag_kwargs = token_kwargs(bits, parser) + + nodelist = parser.parse(("endcotton_props_frame",)) + parser.delete_first_token() + return CottonPropsFrameNode(nodelist, tag_kwargs) + + +class CottonPropsFrameNode(template.Node): + def __init__(self, nodelist, kwargs): + self.nodelist = nodelist + self.kwargs = kwargs + + def render(self, context): + # Assume 'attrs' are passed from the parent and are available in the context + parent_attrs = context.get("attrs_dict", {}) + + # Initialize props based on the frame's kwargs and parent attrs + props = {} + for key, value in self.kwargs.items(): + # Attempt to resolve each kwarg value (which may include template variables) + resolved_value = value.resolve(context) + # Check if the prop exists in parent attrs; if so, use it, otherwise use the resolved default + if key in parent_attrs: + props[key] = parent_attrs[key] + else: + props[key] = resolved_value + + # Overwrite 'attrs' in the local context by excluding keys that are identified as props + attrs_without_props = {k: v for k, v in parent_attrs.items() if k not in props} + context["attrs_dict"] = attrs_without_props + + # Provide all of the attrs as a string to pass to the component + def ensure_quoted(value): + if isinstance(value, str) and value.startswith('"') and value.endswith('"'): + return value + else: + return f'"{value}"' + + attrs = " ".join( + [ + f"{key}={ensure_quoted(value)}" + for key, value in attrs_without_props.items() + ] + ) + + context.update({"attrs": mark_safe(attrs)}) + context.update(attrs_without_props) + context.update(props) + + return self.nodelist.render(context) diff --git a/django_cotton/templatetags/_slot.py b/django_cotton/templatetags/_slot.py new file mode 100644 index 0000000..e25ba70 --- /dev/null +++ b/django_cotton/templatetags/_slot.py @@ -0,0 +1,48 @@ +from django import template +from django.utils.safestring import mark_safe + + +def cotton_slot(parser, token): + try: + tag_name, slot_name, component_key = token.split_contents() + except ValueError: + raise template.TemplateSyntaxError("incomplete c-slot %r" % token.contents) + + nodelist = parser.parse(("end_cotton_slot",)) + parser.delete_first_token() + return CottonSlotNode(slot_name, nodelist, component_key) + + +class CottonSlotNode(template.Node): + def __init__(self, slot_name, nodelist, component_key): + self.slot_name = slot_name + self.nodelist = nodelist + self.component_key = component_key + + def render(self, context): + # Add the rendered content to the context. + if "cotton_slots" not in context: + context.update({"cotton_slots": {}}) + + # context["cotton_slots"][self.slot_name] = mark_safe(output) + + output = self.nodelist.render(context) + + # with context.push(): + # Temporarily store the slot's content in the new layer + # if "cotton_slots" not in context: + # context["cotton_slots"] = {} + + if self.component_key not in context["cotton_slots"]: + context["cotton_slots"][self.component_key] = {} + + # if self.slot_name not in context["cotton_slots"][self.component_key]: + # context["cotton_slots"][self.component_key][self.slot_name] = mark_safe(output) + context["cotton_slots"][self.component_key][self.slot_name] = mark_safe(output) + + # context.push() + + # todo add scoping by component + # context["cotton_slots"][self.component_key][self.slot_name] = mark_safe(output) + + return "" diff --git a/django_cotton/templatetags/cotton.py b/django_cotton/templatetags/cotton.py new file mode 100644 index 0000000..43c9b17 --- /dev/null +++ b/django_cotton/templatetags/cotton.py @@ -0,0 +1,26 @@ +from django import template +from django.utils.html import format_html_join + +from django_cotton.templatetags._component import cotton_component +from django_cotton.templatetags._slot import cotton_slot +from django_cotton.templatetags._props import cotton_props +from django_cotton.templatetags._props_frame import cotton_props_frame + +register = template.Library() +register.tag("cotton_component", cotton_component) +register.tag("cotton_slot", cotton_slot) +register.tag("cotton_props", cotton_props) +register.tag("cotton_props_frame", cotton_props_frame) + + +@register.filter +def merge(attrs, args): + # attrs is expected to be a dictionary of existing attributes + # args is a string of additional attributes to merge, e.g., "class:extra-class" + for arg in args.split(","): + key, value = arg.split(":", 1) + if key in attrs: + attrs[key] = value + " " + attrs[key] + else: + attrs[key] = value + return format_html_join(" ", '{0}="{1}"', attrs.items()) diff --git a/django_cotton/tests/__init__.py b/django_cotton/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/django_cotton/tests/test_cotton.py b/django_cotton/tests/test_cotton.py new file mode 100644 index 0000000..aa5bafe --- /dev/null +++ b/django_cotton/tests/test_cotton.py @@ -0,0 +1,111 @@ +from django.test import TestCase + +from django_cotton.tests.utils import get_compiled, get_rendered + + +class CottonTestCase(TestCase): + def test_parent_component_is_rendered(self): + response = self.client.get("/parent") + self.assertContains(response, '
') + + def test_child_is_rendered(self): + response = self.client.get("/child") + self.assertContains(response, '
') + self.assertContains(response, '
') + + def test_self_closing_is_rendered(self): + response = self.client.get("/self-closing") + self.assertContains(response, '
') + + def test_named_slots_correctly_display_in_loop(self): + response = self.client.get("/named-slot-in-loop") + self.assertContains(response, "item name: Item 1") + self.assertContains(response, "item name: Item 2") + self.assertContains(response, "item name: Item 3") + + def test_attribute_passing(self): + response = self.client.get("/attribute-passing") + self.assertContains( + response, '
' + ) + + def test_attribute_merging(self): + response = self.client.get("/attribute-merging") + self.assertContains( + response, 'class="form-group another-class-with:colon extra-class"' + ) + + def test_django_syntax_decoding(self): + response = self.client.get("/django-syntax-decoding") + self.assertContains(response, "some-class") + + def test_props_are_converted_to_props_frame_tags(self): + compiled = get_compiled( + """ + + + content + """ + ) + + self.assertEquals( + compiled, + """{% cotton_props_frame prop1=prop1|default:"string with space" %}content{% endcotton_props_frame %}""", + ) + + def test_attrs_do_not_contain_props(self): + response = self.client.get("/props-test") + self.assertContains(response, "attr1: 'im an attr'") + self.assertContains(response, "prop1: 'im a prop'") + self.assertContains(response, """attrs: 'attr1="im an attr"'""") + + def test_strings_with_spaces_can_be_passed(self): + response = self.client.get("/string-with-spaces") + self.assertContains(response, "attr1: 'I have spaces'") + self.assertContains(response, "prop1: 'string with space'") + self.assertContains(response, "default_prop: 'default prop'") + self.assertContains(response, "named_slot: '") + self.assertContains(response, "named_slot with spaces") + self.assertContains(response, """attrs: 'attr1="I have spaces"'""") + + def test_named_slots_dont_bleed_into_sibling_components(self): + html = """ + + component1 + named slot 1 + + + component2 + + """ + + rendered = get_rendered(html) + + self.assertTrue("named_slot: 'named slot 1'" in rendered) + self.assertTrue("named_slot: ''" in rendered) + + def test_template_variables_are_not_parsed(self): + html = """ + + + test + + + """ + + rendered = get_rendered(html, {"variable": 1}) + + self.assertTrue("attr1: 'variable'" in rendered) + self.assertTrue("attr2: '1'" in rendered) + + def test_int_attributes(self): + pass + + def test_none_attributes(self): + pass + + def test_list_attributes(self): + pass + + def quotes_inside_quotes(self): + pass diff --git a/django_cotton/tests/utils.py b/django_cotton/tests/utils.py new file mode 100644 index 0000000..f7f9d73 --- /dev/null +++ b/django_cotton/tests/utils.py @@ -0,0 +1,18 @@ +from django.template import Context, Template + +from django_cotton.cotton_loader import Loader as CottonLoader + + +def get_compiled(template_string): + return CottonLoader(engine=None)._compile_template_from_string( + template_string, component_key="test_key" + ) + + +def get_rendered(template_string, context: dict = None): + if context is None: + context = {} + + compiled_string = get_compiled(template_string) + + return Template(compiled_string).render(Context(context)) diff --git a/django_cotton/urls.py b/django_cotton/urls.py new file mode 100644 index 0000000..6990478 --- /dev/null +++ b/django_cotton/urls.py @@ -0,0 +1,45 @@ +from django.views.generic import TemplateView +from . import views +from django.urls import path + +app_name = "django_cotton" + + +class NamedSlotInLoop(TemplateView): + template_name = "named_slot_in_loop.cotton.html" + + def get_context_data(self, **kwargs): + return { + "items": [ + {"name": "Item 1"}, + {"name": "Item 2"}, + {"name": "Item 3"}, + ] + } + + +urlpatterns = [ + path("parent", TemplateView.as_view(template_name="parent_test.cotton.html")), + path("child", TemplateView.as_view(template_name="child_test.cotton.html")), + path( + "self-closing", + TemplateView.as_view(template_name="self_closing_test.cotton.html"), + ), + path("include", TemplateView.as_view(template_name="cotton_include.cotton.html")), + path("playground", TemplateView.as_view(template_name="playground.cotton.html")), + path("tag", TemplateView.as_view(template_name="tag.cotton.html")), + path("named-slot-in-loop", NamedSlotInLoop.as_view()), + path("test/compiled-cotton", views.compiled_cotton_test_view), + path("test/cotton", views.cotton_test_view), + path("test/native-extends", views.native_extends_test_view), + path("test/native-include", views.native_include_test_view), + path("attribute-merging", views.attribute_merging_test_view), + path("attribute-passing", views.attribute_passing_test_view), + path("django-syntax-decoding", views.django_syntax_decoding_test_view), + path( + "string-with-spaces", + TemplateView.as_view(template_name="string_with_spaces.cotton.html"), + ), + path("props-test", TemplateView.as_view(template_name="props_test.cotton.html")), + path("variable-parsing", views.variable_parsing_test_view), +] diff --git a/django_cotton/views.py b/django_cotton/views.py new file mode 100644 index 0000000..c6c60ef --- /dev/null +++ b/django_cotton/views.py @@ -0,0 +1,40 @@ +from django.shortcuts import render + +# benchmark tests + + +def compiled_cotton_test_view(request): + return render(request, "compiled_cotton_test.html") + + +def cotton_test_view(request): + return render(request, "cotton_test.cotton.html") + + +def native_extends_test_view(request): + return render(request, "native_extends_test.html") + + +def native_include_test_view(request): + return render(request, "native_include_test.html") + + +# Django tests + + +def attribute_merging_test_view(request): + return render(request, "attribute_merging_test.cotton.html") + + +def attribute_passing_test_view(request): + return render(request, "attribute_passing_test.cotton.html") + + +def django_syntax_decoding_test_view(request): + return render(request, "django_syntax_decoding_test.cotton.html") + + +def variable_parsing_test_view(request): + return render( + request, "variable_parsing_test.cotton.html", {"variable": "some-class"} + ) diff --git a/django_cotton/wsgi.py b/django_cotton/wsgi.py new file mode 100644 index 0000000..6462b4b --- /dev/null +++ b/django_cotton/wsgi.py @@ -0,0 +1,16 @@ +""" +WSGI config for django_cotton project. + +It exposes the WSGI callable as a module-level variable named ``application``. + +For more information on this file, see +https://docs.djangoproject.com/en/4.2/howto/deployment/wsgi/ +""" + +import os + +from django.core.wsgi import get_wsgi_application + +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings") + +application = get_wsgi_application() diff --git a/docs/docker/Dockerfile b/docs/docker/Dockerfile new file mode 100644 index 0000000..44768cc --- /dev/null +++ b/docs/docker/Dockerfile @@ -0,0 +1,39 @@ +ARG PLATFORM=linux/amd64 + +# ---- Tailwind Build Stage (build is quicker like this vs installing npm, node separately) ---- +FROM node:16-slim AS build_tailwind +WORKDIR /css +COPY package*.json ./ +RUN npm install +COPY . . +RUN ["npx", "tailwindcss", "-o", "./docs_project/static/app.css"] + +# Use an official Python runtime as a base image +FROM python:3.9-slim + +# Keep logs unbuffered +ENV PYTHONUNBUFFERED 1 + +# Set the working directory in the container +WORKDIR /app + +# Install Poetry +RUN pip install --upgrade pip \ + && pip install poetry + +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + chromium \ + chromium-driver \ + && rm -rf /var/lib/apt/lists/* + +# Copy only dependencies definition to the docker image +COPY . /app/ + +# Install project dependencies +RUN poetry config virtualenvs.create false \ + && poetry install + +RUN SECRET_KEY=dummy STATIC_URL='/staticfiles/' python manage.py collectstatic --noinput --verbosity 2 + +CMD [ "python", "manage.py", "runserver", "0.0.0.0:8000" ] \ No newline at end of file diff --git a/docs/docker/bin/build.sh b/docs/docker/bin/build.sh new file mode 100755 index 0000000..e2598c8 --- /dev/null +++ b/docs/docker/bin/build.sh @@ -0,0 +1,16 @@ +#!/bin/bash + +# if arg exists 'mac', then build for mac +if [ "$1" = "mac" ]; then + PLATFORM="linux/arm64" +else + PLATFORM="linux/amd64" +fi + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR + +docker build --no-cache --build-arg PLATFORM=$PLATFORM -f ../Dockerfile ../../docs_project -t cotton-docs-app \ No newline at end of file diff --git a/docs/docker/bin/manage.sh b/docs/docker/bin/manage.sh new file mode 100755 index 0000000..bc907b2 --- /dev/null +++ b/docs/docker/bin/manage.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash + +# Start a new login shell to preserve history and execute the Docker command +bash -l -c "docker exec -it cotton-docs-web python manage.py $*" \ No newline at end of file diff --git a/docs/docker/bin/run-dev.sh b/docs/docker/bin/run-dev.sh new file mode 100755 index 0000000..d592c93 --- /dev/null +++ b/docs/docker/bin/run-dev.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR + +docker compose -f ../docker-compose.yaml up "$@" diff --git a/docs/docker/bin/shell.sh b/docs/docker/bin/shell.sh new file mode 100755 index 0000000..98e0e1e --- /dev/null +++ b/docs/docker/bin/shell.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR/.. + +docker exec -it cotton-docs-web python manage.py shell \ No newline at end of file diff --git a/docs/docker/bin/stop.sh b/docs/docker/bin/stop.sh new file mode 100755 index 0000000..4d46178 --- /dev/null +++ b/docs/docker/bin/stop.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +# Determine script directory +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +# Change directory to project directory +cd $SCRIPT_DIR/.. + +docker compose -f etc/docker/docker-compose.yaml -f etc/docker/docker-compose.dev.yaml down $* \ No newline at end of file diff --git a/docs/docker/bin/terminal.sh b/docs/docker/bin/terminal.sh new file mode 100755 index 0000000..0904222 --- /dev/null +++ b/docs/docker/bin/terminal.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +docker exec -it cotton-docs-web bash \ No newline at end of file diff --git a/docs/docker/bin/test.sh b/docs/docker/bin/test.sh new file mode 100755 index 0000000..9af187e --- /dev/null +++ b/docs/docker/bin/test.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +docker exec -t cotton-docs-web python manage.py test $* diff --git a/docs/docker/docker-compose.yaml b/docs/docker/docker-compose.yaml new file mode 100644 index 0000000..f9c5431 --- /dev/null +++ b/docs/docker/docker-compose.yaml @@ -0,0 +1,28 @@ +version: '3' + +services: + cotton-docs-web: + container_name: cotton-docs-web + restart: always + image: cotton-docs-app + working_dir: /app + command: python manage.py runserver 0.0.0.0:8000 + environment: + - DEBUG=True + volumes: + - ../docs_project:/app + - ../../django_cotton:/app/django_cotton + ports: + - 8002:8000 + + cotton-docs-tailwind: + container_name: cotton-docs-tailwind + stop_signal: SIGINT + image: node:16 + working_dir: /app + tty: true + volumes: + - ../docs_project:/app + # call the tailwind build before the watch + # command: /bin/sh -c "npm install && npx tailwindcss -c ./tailwind.config.js -o ./luma/static/app.css && npx tailwindcss -c ./tailwind.config.js -o ./luma/static/app.css --watch" + command: /bin/sh -c "trap 'exit' INT; npm install && npx tailwindcss -c ./tailwind.config.js -o ./docs_project/static/app.css && npx tailwindcss -c ./tailwind.config.js -o ./docs_project/static/app.css --watch" diff --git a/docs/docs_project/DockerfileTmp b/docs/docs_project/DockerfileTmp new file mode 100644 index 0000000..ce62662 --- /dev/null +++ b/docs/docs_project/DockerfileTmp @@ -0,0 +1,45 @@ +ARG PLATFORM=linux/amd64 + +# ---- Tailwind Build Stage (build is quicker like this vs installing npm, node separately) ---- +FROM node:16-slim AS build_tailwind +WORKDIR /css +COPY package*.json ./ +RUN npm install +COPY . . +RUN ["npx", "tailwindcss", "-o", "./docs_project/static/app.css"] + +# Use an official Python runtime as a base image +FROM python:3.9-slim + +# Keep logs unbuffered +ENV PYTHONUNBUFFERED 1 + +# Set the working directory in the container +WORKDIR /app + +# Install Poetry +RUN pip install --upgrade pip \ + && pip install poetry + +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + chromium \ + chromium-driver \ + && rm -rf /var/lib/apt/lists/* + +# Copy only dependencies definition to the docker image +COPY . /app/ + +# Copy static files from the build_tailwind stage +COPY --from=build_tailwind /css/docs_project/static/app.css ./docs_project/static/app.css + +# Install project dependencies +RUN poetry config virtualenvs.create false \ + && poetry install + +RUN SECRET_KEY=dummy STATIC_URL='/staticfiles/' python manage.py collectstatic --noinput --verbosity 2 + +EXPOSE 8000 +ENV PORT 8000 + +CMD ["gunicorn", "docs_project.wsgi:application", "--bind", "0.0.0.0:8000"] \ No newline at end of file diff --git a/docs/docs_project/README.md b/docs/docs_project/README.md new file mode 100644 index 0000000..7a7cdf7 --- /dev/null +++ b/docs/docs_project/README.md @@ -0,0 +1,139 @@ +# Cotton + +Bringing component-based design to Django templates. + +Document site + +## Overview +Cotton enhances Django templates by allowing component-based design, making UI composition more efficient and reusable. It integrates seamlessly with Tailwind CSS and retains full compatibility with native Django template features. + +## Key Features +- **Rapid UI Composition:** Efficiently compose and reuse UI components. +- **Tailwind CSS Harmony:** Integrates with Tailwind's utility-first approach. +- **Interoperable with Django:** Enhances Django templates without replacing them. +- **Semantic Syntax:** HTML-like syntax for better code editor support. +- **Minimal Overhead:** Compiles to native Django components with automatic caching. + +## Getting Started + +### Installation +To install Cotton, run the following command: + +```bash +pip install django-cotton +``` + +Then update your `settings.py`: + +```python +INSTALLED_APPS = [ + ... + 'django_cotton', +] + +TEMPLATES = [ + { + 'BACKEND': 'django.template.backends.django.DjangoTemplates', + 'DIRS': ['your_project/templates'], + 'APP_DIRS': False, + 'OPTIONS': { + 'loaders': [ + 'django_cotton.template.loaders.CottonLoader', + # continue with default loaders: + # "django.template.loaders.filesystem.Loader", + # "django.template.loaders.app_directories.Loader", + ], + 'builtins': [ + 'django_cotton.templatetags.cotton', + ], + }, + }, +] +``` + +### Quickstart +Create a new directory in your templates directory called `cotton`. Inside this directory, create a new file called `card.cotton.html` with the following content: + +```html +
+

{{ title }}

+

{{ slot }}

+ +
+``` + +Create a view with a template. Views that contain Cotton components must also use the `.cotton.html` extension: + +```python +# views.py +def dashboard_view(request): + return render(request, "dashboard.cotton.html") +``` + +```html + + + We have the best trees + + + + The best spades in the land + +``` + +### Usage Basics +- **Template Extensions:** View templates including Cotton components should use the `.cotton.html` extension. +- **Component Placement:** Components should be placed in the `templates/cotton` folder. +- **Naming Conventions:** + - Component filenames use snake_case: `my_component.cotton.html` + - Components are called using kebab-case: `` + +### Example +A minimal example using Cotton components: + +```html + +{{ slot }} + + + +

Some content

+
+``` + +### Attributes and Slots +Components can accept attributes and named slots for flexible content and behavior customization: + +```html + +

It's {{ temperature }}{{ unit }} and the condition is {{ condition }}.

+ + + +``` + +#### Passing Variables +To pass a variable from the parent's context, prepend the attribute with a `:`. + +```html + + +``` + +#### Named Slots +```html + +
+

{{ day }}:

{{ icon }} {{ label }} +
+ + + + + ... + + +

Sunny

+
+
+``` \ No newline at end of file diff --git a/docs/docs_project/django_cotton/__init__.py b/docs/docs_project/django_cotton/__init__.py new file mode 100644 index 0000000..e262b60 --- /dev/null +++ b/docs/docs_project/django_cotton/__init__.py @@ -0,0 +1 @@ +_with_prop_prefix = "cotton_with_prop_" diff --git a/docs/docs_project/django_cotton/apps.py b/docs/docs_project/django_cotton/apps.py new file mode 100644 index 0000000..d90a50d --- /dev/null +++ b/docs/docs_project/django_cotton/apps.py @@ -0,0 +1,60 @@ +from django.apps import AppConfig +from django.conf import settings +from django.template import engines + +# fmt: off +class CottonConfig(AppConfig): + name = "django_cotton" + verbose_name = "Cotton" + + def ready(self): + self._modify_templates_settings() + self._add_builtin_template_tag() + + def _modify_templates_settings(self): + modified = False + for template in settings.TEMPLATES: + if not template.get("APP_DIRS", True): + # If APP_DIRS is explicitly set to False, we assume the user + # has a custom setup and do not modify the settings and provide tutorial instead. + continue + + # Example modification: Set APP_DIRS to False + template["APP_DIRS"] = False + + # Add your custom template loader + if "OPTIONS" not in template: + template["OPTIONS"] = {} + if "loaders" not in template["OPTIONS"]: + template["OPTIONS"]["loaders"] = [] + + # Add django_cotton loader + if "django_cotton.cotton_loader.Loader" not in template["OPTIONS"]["loaders"]: + template["OPTIONS"]["loaders"].insert( + 0, "django_cotton.cotton_loader.Loader" + ) + + # Ensure default loaders are present, then add your custom loader + if "django.template.loaders.filesystem.Loader" not in template["OPTIONS"]["loaders"]: + template["OPTIONS"]["loaders"].append( + "django.template.loaders.filesystem.Loader" + ) + if "django.template.loaders.app_directories.Loader" not in template["OPTIONS"]["loaders"]: + template["OPTIONS"]["loaders"].append( + "django.template.loaders.app_directories.Loader" + ) + + # Specify TEMPLATE_DIRS if necessary + # template['DIRS'] += ['path/to/your/templates'] + + modified = True + + if modified: + print("TEMPLATES setting modified by Django Cotton.") + + def _add_builtin_template_tag(self): + """Add a custom template tag to the built-ins.""" + builtins = engines["django"].engine.builtins + custom_tag_lib = "django_cotton.templatetags.cotton" + if custom_tag_lib not in builtins: + builtins.append(custom_tag_lib) diff --git a/docs/docs_project/django_cotton/cotton_loader.py b/docs/docs_project/django_cotton/cotton_loader.py new file mode 100755 index 0000000..c4d13a7 --- /dev/null +++ b/docs/docs_project/django_cotton/cotton_loader.py @@ -0,0 +1,291 @@ +import os +import re +import hashlib +import warnings + +from django.template.loaders.base import Loader as BaseLoader +from django.core.exceptions import SuspiciousFileOperation +from django.template import TemplateDoesNotExist +from django.utils._os import safe_join +from django.template import Template +from django.core.cache import cache +from django.template import Origin +from django.conf import settings + +from bs4 import BeautifulSoup, MarkupResemblesLocatorWarning + +warnings.filterwarnings("ignore", category=MarkupResemblesLocatorWarning) + + +class Loader(BaseLoader): + is_usable = True + + def __init__(self, engine, dirs=None): + super().__init__(engine) + self.cache_handler = CottonTemplateCacheHandler() + self.dirs = dirs + self.django_syntax_placeholders = [] + + def get_template_from_string(self, template_string): + """Create and return a Template object from a string. Used primarily for testing.""" + return Template(template_string, engine=self.engine) + + def get_contents(self, origin): + # check if file exists, whilst getting the mtime for cache key + try: + mtime = os.path.getmtime(origin.name) + except FileNotFoundError: + raise TemplateDoesNotExist(origin) + + # check and return cached template + cache_key = self.cache_handler.get_cache_key(origin.template_name, mtime) + cached_content = self.cache_handler.get_cached_template(cache_key) + if cached_content is not None: + return cached_content + + # If not cached, process the template + template_string = self._get_template_string(origin.name) + + # We need to provide a key to the current view or component (in this case, view) so that we can namespace + # slot data, preventing bleeding and ensure component's clear only data in the context applicable to itself + # in this case, we're top level, likely in a view so we use the view template name as the key + component_key = ( + origin.template_name.lstrip("cotton/") + .rstrip(".cotton.html") + .replace("/", ".") + ) + + compiled_template = self._compile_template_from_string( + template_string, component_key + ) + + # Cache the processed template + self.cache_handler.cache_template(cache_key, compiled_template) + + return compiled_template + + def _replace_syntax_with_placeholders(self, content): + """# replace {% ... %} and {{ ... }} with placeholders so they dont get touched + or encoded by bs4. Store them to later switch them back in after transformation. + """ + self.django_syntax_placeholders = [] + + # First handle cotton_verbatim blocks, this is designed to preserve and display cotton syntax, + # akin to the verbatim tag in Django. + def replace_cotton_verbatim(match): + inner_content = match.group( + 1 + ) # Get the inner content without the cotton_verbatim tags + self.django_syntax_placeholders.append(inner_content) + return f"__django_syntax__{len(self.django_syntax_placeholders)}__" + + # Replace cotton_verbatim blocks, capturing inner content + content = re.sub( + r"\{% cotton_verbatim %\}(.*?)\{% endcotton_verbatim %\}", + replace_cotton_verbatim, + content, + flags=re.DOTALL, + ) + + content = re.sub( + r"\{%.*?%\}", + lambda x: self.django_syntax_placeholders.append(x.group(0)) + or f"__django_syntax__{len(self.django_syntax_placeholders)}__", + content, + ) + content = re.sub( + r"\{\{.*?\}\}", + lambda x: self.django_syntax_placeholders.append(x.group(0)) + or f"__django_syntax__{len(self.django_syntax_placeholders)}__", + content, + ) + + return content + + def _replace_placeholders_with_syntax(self, content): + """After modifying the content, replace the placeholders with the django template tags and variables.""" + for i, placeholder in enumerate(self.django_syntax_placeholders, 1): + content = content.replace(f"__django_syntax__{i}__", placeholder) + + return content + + def _get_template_string(self, template_name): + try: + with open(template_name, "r") as f: + content = f.read() + except FileNotFoundError: + raise TemplateDoesNotExist(template_name) + + return content + + def _compile_template_from_string(self, content, component_key): + content = self._replace_syntax_with_placeholders(content) + content = self._compile_cotton_to_django(content, component_key) + content = self._replace_placeholders_with_syntax(content) + content = self._revert_bs4_attribute_empty_attribute_fixing(content) + + return content + + def _revert_bs4_attribute_empty_attribute_fixing(self, contents): + """Django's template parser adds ="" to empty attribute-like parts in any html-like node, i.e.
gets + compiled to
Then if 'something' is holding attributes sets, the last attribute value is + not quoted. i.e. model=test not model="test".""" + cleaned_content = re.sub('}}=""', "}}", contents) + return cleaned_content + + def get_dirs(self): + return self.dirs if self.dirs is not None else self.engine.dirs + + def get_template_sources(self, template_name): + """Return an Origin object pointing to an absolute path in each directory + in template_dirs. For security reasons, if a path doesn't lie inside + one of the template_dirs it is excluded from the result set.""" + if template_name.endswith(".cotton.html"): + for template_dir in self.get_dirs(): + try: + name = safe_join(template_dir, template_name) + except SuspiciousFileOperation: + # The joined path was located outside of this template_dir + # (it might be inside another one, so this isn't fatal). + continue + + yield Origin( + name=name, + template_name=template_name, + loader=self, + ) + + def _compile_cotton_to_django(self, html_content, component_key): + """Convert cotton tag with the cotton_props string + tag.replace_with(cotton_props_str) + + return soup + + def _wrap_with_cotton_props_frame(self, soup): + """Wrap content with {% cotton_props_frame %} to be able to govern props and attributes. In order to recognise + props defined in a component and also have them available in context, we wrap the entire contents in another + component: cotton_props_frame.""" + props_with_defaults = [] + c_props = soup.find("c-props") + + # parse c-props tag to extract properties and defaults + if c_props: + props_with_defaults = [] + for prop, value in c_props.attrs.items(): + if value is None: + props_with_defaults.append(f"{prop}={prop}") + else: + # Assuming value is already a string that represents the default value + props_with_defaults.append(f'{prop}={prop}|default:"{value}"') + + c_props.decompose() + + # Construct the {% with %} opening tag + opening = "{% cotton_props_frame " + " ".join(props_with_defaults) + " %}" + closing = "{% endcotton_props_frame %}" + + # Convert the remaining soup back to a string and wrap it within {% with %} block + wrapped_content = opening + str(soup).strip() + closing + + # Since we can't replace the soup object itself, we create new soup instead + new_soup = BeautifulSoup(wrapped_content, "html.parser") + + return new_soup + + def _transform_named_slot(self, slot_tag, component_key): + """Replace tags with the {% cotton_slot %} template tag""" + # for c_slot in soup.find_all("c-slot"): + slot_name = slot_tag.get("name", "").strip() + inner_html = "".join(str(content) for content in slot_tag.contents) + + # Check and process any components in the slot content + + slot_soup = BeautifulSoup(inner_html, "html.parser") + self._transform_components(slot_soup, component_key) + + cotton_slot_tag = f"{{% cotton_slot {slot_name} {component_key} %}}{str(slot_soup)}{{% end_cotton_slot %}}" + + slot_tag.replace_with(BeautifulSoup(cotton_slot_tag, "html.parser")) + + def _transform_components(self, soup, component_key): + """Replace tags with the {% cotton_component %} template tag""" + for tag in soup.find_all(re.compile("^c-"), recursive=True): + if tag.name == "c-slot": + self._transform_named_slot(tag, component_key) + + continue + + component_name = tag.name[2:] + + # Convert dot notation to path structure and replace hyphens with underscores + path = component_name.replace(".", "/").replace("-", "_") + + # Construct the opening tag + opening_tag = f"{{% cotton_component {'cotton/{}.cotton.html'.format(path)} {component_name} " + for attr, value in tag.attrs.items(): + if attr == "class": + value = " ".join(value) + opening_tag += ' {}="{}"'.format(attr, value) + opening_tag += " %}" + + # Construct the closing tag + closing_tag = "{% end_cotton_component %}" + + if tag.contents: + tag_soup = BeautifulSoup(tag.decode_contents(), "html.parser") + self._transform_components(tag_soup, component_name) + + # Create new content with opening tag, tag content, and closing tag + new_content = opening_tag + str(tag_soup) + closing_tag + + else: + # Create new content with opening tag and closing tag + new_content = opening_tag + closing_tag + + # Replace the original tag with the new content + new_soup = BeautifulSoup(new_content, "html.parser") + tag.replace_with(new_soup) + + return soup + + +class CottonTemplateCacheHandler: + """Handles caching of cotton templates so the html parsing is only done on first load of each view or component.""" + + def __init__(self): + self.enabled = getattr(settings, "TEMPLATE_CACHING_ENABLED", True) + + def get_cache_key(self, template_name, mtime): + template_hash = hashlib.sha256(template_name.encode()).hexdigest() + return f"cotton_cache_{template_hash}_{mtime}" + + def get_cached_template(self, cache_key): + if not self.enabled: + return None + return cache.get(cache_key) + + def cache_template(self, cache_key, content, timeout=None): + if self.enabled: + cache.set(cache_key, content, timeout=timeout) diff --git a/docs/docs_project/django_cotton/templates/attribute_merging_test.cotton.html b/docs/docs_project/django_cotton/templates/attribute_merging_test.cotton.html new file mode 100644 index 0000000..ebcf664 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/attribute_merging_test.cotton.html @@ -0,0 +1,3 @@ + + ss + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/attribute_passing_test.cotton.html b/docs/docs_project/django_cotton/templates/attribute_passing_test.cotton.html new file mode 100644 index 0000000..a7bc9fc --- /dev/null +++ b/docs/docs_project/django_cotton/templates/attribute_passing_test.cotton.html @@ -0,0 +1,3 @@ + + ss + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/child_test.cotton.html b/docs/docs_project/django_cotton/templates/child_test.cotton.html new file mode 100644 index 0000000..ec03be8 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/child_test.cotton.html @@ -0,0 +1,3 @@ + + d + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/cotton/child.cotton.html b/docs/docs_project/django_cotton/templates/cotton/child.cotton.html new file mode 100644 index 0000000..9f989fa --- /dev/null +++ b/docs/docs_project/django_cotton/templates/cotton/child.cotton.html @@ -0,0 +1 @@ +
\ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/cotton/container.cotton.html b/docs/docs_project/django_cotton/templates/cotton/container.cotton.html new file mode 100644 index 0000000..835e5c4 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/cotton/container.cotton.html @@ -0,0 +1,11 @@ +
+ Header: + {{ header }} +
+ +
+ Content: + {{ slot }} +
+ + diff --git a/docs/docs_project/django_cotton/templates/cotton/merges_attributes.cotton.html b/docs/docs_project/django_cotton/templates/cotton/merges_attributes.cotton.html new file mode 100644 index 0000000..ef33d94 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/cotton/merges_attributes.cotton.html @@ -0,0 +1,3 @@ +
+ +
\ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/cotton/named_slot_component.cotton.html b/docs/docs_project/django_cotton/templates/cotton/named_slot_component.cotton.html new file mode 100644 index 0000000..e324e2c --- /dev/null +++ b/docs/docs_project/django_cotton/templates/cotton/named_slot_component.cotton.html @@ -0,0 +1,3 @@ +
+ {{ name }} +
\ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/cotton/parent.cotton.html b/docs/docs_project/django_cotton/templates/cotton/parent.cotton.html new file mode 100644 index 0000000..c534580 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/cotton/parent.cotton.html @@ -0,0 +1,3 @@ +
+ {{slot}} +
\ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/cotton/receives_attributes.cotton.html b/docs/docs_project/django_cotton/templates/cotton/receives_attributes.cotton.html new file mode 100644 index 0000000..8d463b4 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/cotton/receives_attributes.cotton.html @@ -0,0 +1,3 @@ +
+ +
\ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/cotton/test_component.cotton.html b/docs/docs_project/django_cotton/templates/cotton/test_component.cotton.html new file mode 100644 index 0000000..c1cddfe --- /dev/null +++ b/docs/docs_project/django_cotton/templates/cotton/test_component.cotton.html @@ -0,0 +1,13 @@ + + +

slot: '{{ slot }}'

+ +

attr1: '{{ attr1 }}'

+

attr2: '{{ attr2 }}'

+ +

prop1: '{{ prop1 }}'

+

default_prop: '{{ default_prop }}'

+ +

named_slot: '{{ named_slot }}'

+ +

attrs: '{{ attrs }}'

diff --git a/docs/docs_project/django_cotton/templates/django_syntax_decoding_test.cotton.html b/docs/docs_project/django_cotton/templates/django_syntax_decoding_test.cotton.html new file mode 100644 index 0000000..ee3d784 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/django_syntax_decoding_test.cotton.html @@ -0,0 +1 @@ +
Hello, World!
\ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/form_test.cotton.html b/docs/docs_project/django_cotton/templates/form_test.cotton.html new file mode 100644 index 0000000..6c70273 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/form_test.cotton.html @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/named_slot_in_loop.cotton.html b/docs/docs_project/django_cotton/templates/named_slot_in_loop.cotton.html new file mode 100644 index 0000000..136d7c1 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/named_slot_in_loop.cotton.html @@ -0,0 +1,7 @@ +{% for item in items %} + + + item name: {{ item.name }} + + +{% endfor %} \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/parent_test.cotton.html b/docs/docs_project/django_cotton/templates/parent_test.cotton.html new file mode 100644 index 0000000..9922300 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/parent_test.cotton.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/self_closing_test.cotton.html b/docs/docs_project/django_cotton/templates/self_closing_test.cotton.html new file mode 100644 index 0000000..9c99f37 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/self_closing_test.cotton.html @@ -0,0 +1,4 @@ +{% load static %} + + + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/string_with_spaces.cotton.html b/docs/docs_project/django_cotton/templates/string_with_spaces.cotton.html new file mode 100644 index 0000000..ab4ddb5 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/string_with_spaces.cotton.html @@ -0,0 +1,5 @@ + + + named_slot with spaces + + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templates/variable_parsing_test.cotton.html b/docs/docs_project/django_cotton/templates/variable_parsing_test.cotton.html new file mode 100644 index 0000000..8402bd4 --- /dev/null +++ b/docs/docs_project/django_cotton/templates/variable_parsing_test.cotton.html @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/docs_project/django_cotton/templatetags/__init__.py b/docs/docs_project/django_cotton/templatetags/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs_project/django_cotton/templatetags/_component.py b/docs/docs_project/django_cotton/templatetags/_component.py new file mode 100644 index 0000000..eaf365c --- /dev/null +++ b/docs/docs_project/django_cotton/templatetags/_component.py @@ -0,0 +1,68 @@ +from django import template +from django.template import Node +from django.template.loader import render_to_string + + +def cotton_component(parser, token): + bits = token.split_contents() + tag_name = bits[0] + template_path = bits[1] + component_key = bits[2] + + kwargs = {} + for bit in bits[3:]: + key, value = bit.split("=") + if key.startswith(":"): # Detect variables + key = key[1:] # Remove ':' prefix + value = value.strip("'\"") # Remove quotes + kwargs[key] = template.Variable(value) # Treat as a variable + else: + kwargs[key] = value.strip("'\"") # Treat as a literal string + + nodelist = parser.parse(("end_cotton_component",)) + parser.delete_first_token() + + return CottonComponentNode(nodelist, template_path, component_key, kwargs) + + +class CottonComponentNode(Node): + def __init__(self, nodelist, template_path, component_key, kwargs): + self.nodelist = nodelist + self.template_path = template_path + self.component_key = component_key + self.kwargs = kwargs + + def render(self, context): + local_context = context.flatten() + + attrs = {} + for key, value in self.kwargs.items(): + if isinstance(value, template.Variable): # Resolve variables + try: + resolved_value = value.resolve(context) + attrs[key] = resolved_value + except template.VariableDoesNotExist: + pass # Handle variable not found, if necessary + else: + attrs[key] = value # Use literal string + + # Add the remainder as the default slot + rendered = self.nodelist.render(context) + local_context.update({"slot": rendered}) + + slots = context.get("cotton_slots", {}) + component_slots = slots.get(self.component_key, {}) + + local_context.update(component_slots) + local_context.update(attrs) + local_context.update({"attrs_dict": attrs}) + + rendered = render_to_string(self.template_path, local_context) + + # Now reset the component's slots in context to prevent bleeding + if self.component_key in slots: + slots[self.component_key] = {} + + context.update({"cotton_slots": slots}) + + return rendered diff --git a/docs/docs_project/django_cotton/templatetags/_props.py b/docs/docs_project/django_cotton/templatetags/_props.py new file mode 100644 index 0000000..e5f2961 --- /dev/null +++ b/docs/docs_project/django_cotton/templatetags/_props.py @@ -0,0 +1,43 @@ +from django import template + +register = template.Library() + + +def cotton_props(parser, token): + # Split the token to get variable assignments + parts = token.split_contents() + cotton_props = {} + for part in parts[1:]: + key, value = part.split("=") + cotton_props[key] = value + + return CottonPropNode(cotton_props) + + +class CottonPropNode(template.Node): + def __init__(self, cotton_props): + self.cotton_props = cotton_props + + def render(self, context): + resolved_props = {} + + # if the same var is already set in context, it's being passed explicitly to override the cotton_var + # if not, then we resolve it from the context + for key, value in self.cotton_props.items(): + # if key in context: + # resolved_props[key] = context[key] + # continue + try: + resolved_props[key] = template.Variable(value).resolve(context) + except (TypeError, template.VariableDoesNotExist): + resolved_props[key] = value + + cotton_props = {"cotton_props": resolved_props} + + # Update the global context directly + context.update(resolved_props) + context.update(cotton_props) + context.update({"cotton_props": resolved_props}) + context["cotton_props"].update(resolved_props) + + return "" diff --git a/docs/docs_project/django_cotton/templatetags/_props_frame.py b/docs/docs_project/django_cotton/templatetags/_props_frame.py new file mode 100644 index 0000000..e1c5492 --- /dev/null +++ b/docs/docs_project/django_cotton/templatetags/_props_frame.py @@ -0,0 +1,64 @@ +from django import template +from django.template.base import token_kwargs +from django.utils.safestring import mark_safe + +register = template.Library() + + +def cotton_props_frame(parser, token): + """The job of the props frame is to filter component kwargs (attributes) against declared props. It has to be + second component because we desire to declare props () inside the component template and therefore the + component can not manipulate its own context from it's own template, instead we declare the props frame + directly inside component""" + bits = token.split_contents()[1:] # Skip the tag name + # Parse token kwargs while maintaining token order + tag_kwargs = token_kwargs(bits, parser) + + nodelist = parser.parse(("endcotton_props_frame",)) + parser.delete_first_token() + return CottonPropsFrameNode(nodelist, tag_kwargs) + + +class CottonPropsFrameNode(template.Node): + def __init__(self, nodelist, kwargs): + self.nodelist = nodelist + self.kwargs = kwargs + + def render(self, context): + # Assume 'attrs' are passed from the parent and are available in the context + parent_attrs = context.get("attrs_dict", {}) + + # Initialize props based on the frame's kwargs and parent attrs + props = {} + for key, value in self.kwargs.items(): + # Attempt to resolve each kwarg value (which may include template variables) + resolved_value = value.resolve(context) + # Check if the prop exists in parent attrs; if so, use it, otherwise use the resolved default + if key in parent_attrs: + props[key] = parent_attrs[key] + else: + props[key] = resolved_value + + # Overwrite 'attrs' in the local context by excluding keys that are identified as props + attrs_without_props = {k: v for k, v in parent_attrs.items() if k not in props} + context["attrs_dict"] = attrs_without_props + + # Provide all of the attrs as a string to pass to the component + def ensure_quoted(value): + if isinstance(value, str) and value.startswith('"') and value.endswith('"'): + return value + else: + return f'"{value}"' + + attrs = " ".join( + [ + f"{key}={ensure_quoted(value)}" + for key, value in attrs_without_props.items() + ] + ) + + context.update({"attrs": mark_safe(attrs)}) + context.update(attrs_without_props) + context.update(props) + + return self.nodelist.render(context) diff --git a/docs/docs_project/django_cotton/templatetags/_slot.py b/docs/docs_project/django_cotton/templatetags/_slot.py new file mode 100644 index 0000000..e25ba70 --- /dev/null +++ b/docs/docs_project/django_cotton/templatetags/_slot.py @@ -0,0 +1,48 @@ +from django import template +from django.utils.safestring import mark_safe + + +def cotton_slot(parser, token): + try: + tag_name, slot_name, component_key = token.split_contents() + except ValueError: + raise template.TemplateSyntaxError("incomplete c-slot %r" % token.contents) + + nodelist = parser.parse(("end_cotton_slot",)) + parser.delete_first_token() + return CottonSlotNode(slot_name, nodelist, component_key) + + +class CottonSlotNode(template.Node): + def __init__(self, slot_name, nodelist, component_key): + self.slot_name = slot_name + self.nodelist = nodelist + self.component_key = component_key + + def render(self, context): + # Add the rendered content to the context. + if "cotton_slots" not in context: + context.update({"cotton_slots": {}}) + + # context["cotton_slots"][self.slot_name] = mark_safe(output) + + output = self.nodelist.render(context) + + # with context.push(): + # Temporarily store the slot's content in the new layer + # if "cotton_slots" not in context: + # context["cotton_slots"] = {} + + if self.component_key not in context["cotton_slots"]: + context["cotton_slots"][self.component_key] = {} + + # if self.slot_name not in context["cotton_slots"][self.component_key]: + # context["cotton_slots"][self.component_key][self.slot_name] = mark_safe(output) + context["cotton_slots"][self.component_key][self.slot_name] = mark_safe(output) + + # context.push() + + # todo add scoping by component + # context["cotton_slots"][self.component_key][self.slot_name] = mark_safe(output) + + return "" diff --git a/docs/docs_project/django_cotton/templatetags/cotton.py b/docs/docs_project/django_cotton/templatetags/cotton.py new file mode 100644 index 0000000..43c9b17 --- /dev/null +++ b/docs/docs_project/django_cotton/templatetags/cotton.py @@ -0,0 +1,26 @@ +from django import template +from django.utils.html import format_html_join + +from django_cotton.templatetags._component import cotton_component +from django_cotton.templatetags._slot import cotton_slot +from django_cotton.templatetags._props import cotton_props +from django_cotton.templatetags._props_frame import cotton_props_frame + +register = template.Library() +register.tag("cotton_component", cotton_component) +register.tag("cotton_slot", cotton_slot) +register.tag("cotton_props", cotton_props) +register.tag("cotton_props_frame", cotton_props_frame) + + +@register.filter +def merge(attrs, args): + # attrs is expected to be a dictionary of existing attributes + # args is a string of additional attributes to merge, e.g., "class:extra-class" + for arg in args.split(","): + key, value = arg.split(":", 1) + if key in attrs: + attrs[key] = value + " " + attrs[key] + else: + attrs[key] = value + return format_html_join(" ", '{0}="{1}"', attrs.items()) diff --git a/docs/docs_project/django_cotton/tests/__init__.py b/docs/docs_project/django_cotton/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs_project/django_cotton/tests/test_cotton.py b/docs/docs_project/django_cotton/tests/test_cotton.py new file mode 100644 index 0000000..aa5bafe --- /dev/null +++ b/docs/docs_project/django_cotton/tests/test_cotton.py @@ -0,0 +1,111 @@ +from django.test import TestCase + +from django_cotton.tests.utils import get_compiled, get_rendered + + +class CottonTestCase(TestCase): + def test_parent_component_is_rendered(self): + response = self.client.get("/parent") + self.assertContains(response, '
') + + def test_child_is_rendered(self): + response = self.client.get("/child") + self.assertContains(response, '
') + self.assertContains(response, '
') + + def test_self_closing_is_rendered(self): + response = self.client.get("/self-closing") + self.assertContains(response, '
') + + def test_named_slots_correctly_display_in_loop(self): + response = self.client.get("/named-slot-in-loop") + self.assertContains(response, "item name: Item 1") + self.assertContains(response, "item name: Item 2") + self.assertContains(response, "item name: Item 3") + + def test_attribute_passing(self): + response = self.client.get("/attribute-passing") + self.assertContains( + response, '
' + ) + + def test_attribute_merging(self): + response = self.client.get("/attribute-merging") + self.assertContains( + response, 'class="form-group another-class-with:colon extra-class"' + ) + + def test_django_syntax_decoding(self): + response = self.client.get("/django-syntax-decoding") + self.assertContains(response, "some-class") + + def test_props_are_converted_to_props_frame_tags(self): + compiled = get_compiled( + """ + + + content + """ + ) + + self.assertEquals( + compiled, + """{% cotton_props_frame prop1=prop1|default:"string with space" %}content{% endcotton_props_frame %}""", + ) + + def test_attrs_do_not_contain_props(self): + response = self.client.get("/props-test") + self.assertContains(response, "attr1: 'im an attr'") + self.assertContains(response, "prop1: 'im a prop'") + self.assertContains(response, """attrs: 'attr1="im an attr"'""") + + def test_strings_with_spaces_can_be_passed(self): + response = self.client.get("/string-with-spaces") + self.assertContains(response, "attr1: 'I have spaces'") + self.assertContains(response, "prop1: 'string with space'") + self.assertContains(response, "default_prop: 'default prop'") + self.assertContains(response, "named_slot: '") + self.assertContains(response, "named_slot with spaces") + self.assertContains(response, """attrs: 'attr1="I have spaces"'""") + + def test_named_slots_dont_bleed_into_sibling_components(self): + html = """ + + component1 + named slot 1 + + + component2 + + """ + + rendered = get_rendered(html) + + self.assertTrue("named_slot: 'named slot 1'" in rendered) + self.assertTrue("named_slot: ''" in rendered) + + def test_template_variables_are_not_parsed(self): + html = """ + + + test + + + """ + + rendered = get_rendered(html, {"variable": 1}) + + self.assertTrue("attr1: 'variable'" in rendered) + self.assertTrue("attr2: '1'" in rendered) + + def test_int_attributes(self): + pass + + def test_none_attributes(self): + pass + + def test_list_attributes(self): + pass + + def quotes_inside_quotes(self): + pass diff --git a/docs/docs_project/django_cotton/tests/utils.py b/docs/docs_project/django_cotton/tests/utils.py new file mode 100644 index 0000000..f7f9d73 --- /dev/null +++ b/docs/docs_project/django_cotton/tests/utils.py @@ -0,0 +1,18 @@ +from django.template import Context, Template + +from django_cotton.cotton_loader import Loader as CottonLoader + + +def get_compiled(template_string): + return CottonLoader(engine=None)._compile_template_from_string( + template_string, component_key="test_key" + ) + + +def get_rendered(template_string, context: dict = None): + if context is None: + context = {} + + compiled_string = get_compiled(template_string) + + return Template(compiled_string).render(Context(context)) diff --git a/docs/docs_project/django_cotton/urls.py b/docs/docs_project/django_cotton/urls.py new file mode 100644 index 0000000..6990478 --- /dev/null +++ b/docs/docs_project/django_cotton/urls.py @@ -0,0 +1,45 @@ +from django.views.generic import TemplateView +from . import views +from django.urls import path + +app_name = "django_cotton" + + +class NamedSlotInLoop(TemplateView): + template_name = "named_slot_in_loop.cotton.html" + + def get_context_data(self, **kwargs): + return { + "items": [ + {"name": "Item 1"}, + {"name": "Item 2"}, + {"name": "Item 3"}, + ] + } + + +urlpatterns = [ + path("parent", TemplateView.as_view(template_name="parent_test.cotton.html")), + path("child", TemplateView.as_view(template_name="child_test.cotton.html")), + path( + "self-closing", + TemplateView.as_view(template_name="self_closing_test.cotton.html"), + ), + path("include", TemplateView.as_view(template_name="cotton_include.cotton.html")), + path("playground", TemplateView.as_view(template_name="playground.cotton.html")), + path("tag", TemplateView.as_view(template_name="tag.cotton.html")), + path("named-slot-in-loop", NamedSlotInLoop.as_view()), + path("test/compiled-cotton", views.compiled_cotton_test_view), + path("test/cotton", views.cotton_test_view), + path("test/native-extends", views.native_extends_test_view), + path("test/native-include", views.native_include_test_view), + path("attribute-merging", views.attribute_merging_test_view), + path("attribute-passing", views.attribute_passing_test_view), + path("django-syntax-decoding", views.django_syntax_decoding_test_view), + path( + "string-with-spaces", + TemplateView.as_view(template_name="string_with_spaces.cotton.html"), + ), + path("props-test", TemplateView.as_view(template_name="props_test.cotton.html")), + path("variable-parsing", views.variable_parsing_test_view), +] diff --git a/docs/docs_project/django_cotton/views.py b/docs/docs_project/django_cotton/views.py new file mode 100644 index 0000000..c6c60ef --- /dev/null +++ b/docs/docs_project/django_cotton/views.py @@ -0,0 +1,40 @@ +from django.shortcuts import render + +# benchmark tests + + +def compiled_cotton_test_view(request): + return render(request, "compiled_cotton_test.html") + + +def cotton_test_view(request): + return render(request, "cotton_test.cotton.html") + + +def native_extends_test_view(request): + return render(request, "native_extends_test.html") + + +def native_include_test_view(request): + return render(request, "native_include_test.html") + + +# Django tests + + +def attribute_merging_test_view(request): + return render(request, "attribute_merging_test.cotton.html") + + +def attribute_passing_test_view(request): + return render(request, "attribute_passing_test.cotton.html") + + +def django_syntax_decoding_test_view(request): + return render(request, "django_syntax_decoding_test.cotton.html") + + +def variable_parsing_test_view(request): + return render( + request, "variable_parsing_test.cotton.html", {"variable": "some-class"} + ) diff --git a/docs/docs_project/django_cotton/wsgi.py b/docs/docs_project/django_cotton/wsgi.py new file mode 100644 index 0000000..6462b4b --- /dev/null +++ b/docs/docs_project/django_cotton/wsgi.py @@ -0,0 +1,16 @@ +""" +WSGI config for django_cotton project. + +It exposes the WSGI callable as a module-level variable named ``application``. + +For more information on this file, see +https://docs.djangoproject.com/en/4.2/howto/deployment/wsgi/ +""" + +import os + +from django.core.wsgi import get_wsgi_application + +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings") + +application = get_wsgi_application() diff --git a/docs/docs_project/docs_project/__init__.py b/docs/docs_project/docs_project/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs_project/docs_project/asgi.py b/docs/docs_project/docs_project/asgi.py new file mode 100644 index 0000000..12f5d35 --- /dev/null +++ b/docs/docs_project/docs_project/asgi.py @@ -0,0 +1,16 @@ +""" +ASGI config for django_cotton project. + +It exposes the ASGI callable as a module-level variable named ``application``. + +For more information on this file, see +https://docs.djangoproject.com/en/4.2/howto/deployment/asgi/ +""" + +import os + +from django.core.asgi import get_asgi_application + +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docs_project.settings") + +application = get_asgi_application() diff --git a/docs/docs_project/docs_project/settings.py b/docs/docs_project/docs_project/settings.py new file mode 100644 index 0000000..e1077a0 --- /dev/null +++ b/docs/docs_project/docs_project/settings.py @@ -0,0 +1,155 @@ +""" +Django settings for django_cotton project. + +Generated by 'django-admin startproject' using Django 4.2.8. + +For more information on this file, see +https://docs.djangoproject.com/en/4.2/topics/settings/ + +For the full list of settings and their values, see +https://docs.djangoproject.com/en/4.2/ref/settings/ +""" +import os +from pathlib import Path + +# SETTINGS_PATH = os.path.dirname(os.path.dirname(__file__)) + +# Build paths inside the project like this: BASE_DIR / 'subdir'. +BASE_DIR = Path(__file__).resolve().parent.parent + + +# Quick-start development settings - unsuitable for production +# See https://docs.djangoproject.com/en/4.2/howto/deployment/checklist/ + +# SECURITY WARNING: keep the secret key used in production secret! +SECRET_KEY = "django-insecure-%)7a&zw=le4uey^36*z*9^4#*iii65t)nyt$36mxq70@=(z6^n" + +# SECURITY WARNING: don't run with debug turned on in production! +DEBUG = True + +ALLOWED_HOSTS = ["0.0.0.0", "django-cotton.com"] + + +# Application definition + +INSTALLED_APPS = [ + "django.contrib.admin", + "django.contrib.auth", + "django.contrib.contenttypes", + "django.contrib.sessions", + "django.contrib.messages", + "django.contrib.staticfiles", + "django_cotton", + "heroicons", +] + +MIDDLEWARE = [ + "django.middleware.security.SecurityMiddleware", + "django.contrib.sessions.middleware.SessionMiddleware", + "django.middleware.common.CommonMiddleware", + "django.middleware.csrf.CsrfViewMiddleware", + "django.contrib.auth.middleware.AuthenticationMiddleware", + "django.contrib.messages.middleware.MessageMiddleware", + "django.middleware.clickjacking.XFrameOptionsMiddleware", + "whitenoise.middleware.WhiteNoiseMiddleware", +] + +ROOT_URLCONF = "docs_project.urls" + +COTTON_AUTO_UPDATE_SETTINGS = False + +TEMPLATES = [ + { + "BACKEND": "django.template.backends.django.DjangoTemplates", + "DIRS": ["docs_project/templates"], + "APP_DIRS": False, + "OPTIONS": { + "context_processors": [ + "django.template.context_processors.debug", + "django.template.context_processors.request", + "django.contrib.auth.context_processors.auth", + "django.contrib.messages.context_processors.messages", + ], + "loaders": [ + "django_cotton.cotton_loader.Loader", + "django.template.loaders.filesystem.Loader", + "django.template.loaders.app_directories.Loader", + ], + "builtins": [ + "django.templatetags.static", + "django_cotton.templatetags.cotton", + "docs_project.templatetags.force_escape", + "docs_project.templatetags.custom_tags", + "heroicons.templatetags.heroicons", + ], + }, + }, +] + +WSGI_APPLICATION = "django_cotton.wsgi.application" + + +# Database +# https://docs.djangoproject.com/en/4.2/ref/settings/#databases + +DATABASES = { + "default": { + "ENGINE": "django.db.backends.sqlite3", + "NAME": BASE_DIR / "db.sqlite3", + } +} + + +# Password validation +# https://docs.djangoproject.com/en/4.2/ref/settings/#auth-password-validators + +AUTH_PASSWORD_VALIDATORS = [ + { + "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator", + }, + { + "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator", + }, + { + "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator", + }, + { + "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator", + }, +] + + +# Internationalization +# https://docs.djangoproject.com/en/4.2/topics/i18n/ + +LANGUAGE_CODE = "en-us" + +TIME_ZONE = "UTC" + +USE_I18N = True + +USE_TZ = True + + +# Static files (CSS, JavaScript, Images) +# https://docs.djangoproject.com/en/4.2/howto/static-files/ + +STORAGES = { + "default": { + "BACKEND": "django.core.files.storage.FileSystemStorage", + }, + "staticfiles": { + "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage", + }, +} + +STATIC_URL = "staticfiles/" +STATICFILES_DIRS = [os.path.join(BASE_DIR, "docs_project", "static")] +STATIC_ROOT = os.path.join(BASE_DIR, "staticfiles") + +# Default primary key field type +# https://docs.djangoproject.com/en/4.2/ref/settings/#default-auto-field + +DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField" + +TEMPLATE_CACHING_ENABLED = True diff --git a/docs/docs_project/docs_project/static/alpine3.min.js b/docs/docs_project/docs_project/static/alpine3.min.js new file mode 100644 index 0000000..f1500dc --- /dev/null +++ b/docs/docs_project/docs_project/static/alpine3.min.js @@ -0,0 +1,5 @@ +(()=>{var tt=!1,rt=!1,V=[],nt=-1;function Vt(e){Sn(e)}function Sn(e){V.includes(e)||V.push(e),An()}function Ee(e){let t=V.indexOf(e);t!==-1&&t>nt&&V.splice(t,1)}function An(){!rt&&!tt&&(tt=!0,queueMicrotask(On))}function On(){tt=!1,rt=!0;for(let e=0;ee.effect(t,{scheduler:r=>{it?Vt(r):r()}}),ot=e.raw}function st(e){k=e}function Wt(e){let t=()=>{};return[n=>{let i=k(n);return e._x_effects||(e._x_effects=new Set,e._x_runEffects=()=>{e._x_effects.forEach(o=>o())}),e._x_effects.add(i),t=()=>{i!==void 0&&(e._x_effects.delete(i),$(i))},i},()=>{t()}]}function q(e,t,r={}){e.dispatchEvent(new CustomEvent(t,{detail:r,bubbles:!0,composed:!0,cancelable:!0}))}function O(e,t){if(typeof ShadowRoot=="function"&&e instanceof ShadowRoot){Array.from(e.children).forEach(i=>O(i,t));return}let r=!1;if(t(e,()=>r=!0),r)return;let n=e.firstElementChild;for(;n;)O(n,t,!1),n=n.nextElementSibling}function v(e,...t){console.warn(`Alpine Warning: ${e}`,...t)}var Gt=!1;function Jt(){Gt&&v("Alpine has already been initialized on this page. Calling Alpine.start() more than once can cause problems."),Gt=!0,document.body||v("Unable to initialize. Trying to load Alpine before `` is available. Did you forget to add `defer` in Alpine's ` + + +``` + +The full list of digests for every file can be found below. + +### Digests + +``` +sha384-hYnh6bxVnenrhg3HDafFjUPaO4yMWcNa6jjBCbcRJAzOW9RidrTLcmNgEyk1EkqC /es/languages/django.js +sha384-fYhQZafPWO54UUJ6/TWCLZVfptppoJrgZw8syHnvkUeAf7+lAiBkU3x8UQ7rTmvB /es/languages/django.min.js +sha384-7m427rj9OYl8KKObOk+aD0QhXmqXy6hU/sHGS6OUwW9hRiiHvr+tLTbLiSJYbIyD /es/languages/http.js +sha384-GdKwMgTrO0R3SPXhm+DuaN3Qr7WkqYmmTClINAGPuV/BUPE9WUI/WnTEntp522Sl /es/languages/http.min.js +sha384-+5oyk7Ed3OlvEWGj8xracq/6e52BScKUN4kxcreNwB7kfRTVsAMs/aAJM58dzIFN /es/languages/python.js +sha384-ND/UH2UkaeWiej5v/oJspfKDz9BGUaVpoDcz4cof0jaiv/mCigjvy7RQ7e+3S6bg /es/languages/python.min.js +sha384-OFoR8IZ+CFwcY8plx8HSDZNoCwLxc701CwdNGfoIEhSgwAbwhvInaxnEi3HYTt2Q /es/languages/xml.js +sha384-yFd3InBtG6WtAVgIl6iIdFKis8HmMC7GbbronB4lHJq3OLef3U8K9puak6MuVZqx /es/languages/xml.min.js +sha384-dFC7/UlAe1aH832WvFmt6fwQFIha+bFdz4Jw/Stp0m65X0P0zgiyaSYVKpRyPCOo /languages/django.js +sha384-AqTOESQu37Lj9i0LQjA1B5Ju2XOJzwB7RR1NYcpo+JgnUF+UTdQi8km+UzU8uYBZ /languages/django.min.js +sha384-g/lhU6FXH73RQL4eFwkPk4CuudGpbHg6cyVZCRpXft3EKCrcQTToBVEDRStjYWQb /languages/http.js +sha384-wt2eEhJoUmjz8wmTq0k9WvI19Pumi9/h7B87i0wc7QMYwnCJ0dcuyfcYo/ui1M6t /languages/http.min.js +sha384-zdZio5RcGiKQJCpe/1IXujPle3bIY8sbmvCabSU5G5GzWAzZtoRZfg9QAQXCL08q /languages/python.js +sha384-IP4vv4Aoh9Lyg8QyzVkAmn2JGoDCpgVHzVSrD3Z+rVyn7+s4wx4pRjv+go3TEwfj /languages/python.min.js +sha384-+PuZYFfVX2UQZU2yKt/FsJUZNUPzZWxW7auXltsaecr1xLvzBYF3c5gYoyOs1++x /languages/xml.js +sha384-jgkY4GMNWfQcLLIoP1vg3FWXflDrRhcSXGBW6ONIWC2SOIv5H1Pa57sXs+aomCuZ /languages/xml.min.js +sha384-NEcIIZ1sdwqm163E+KXE/DwJe5GlD1pGB5XH5SBRHtPVz5HNdF3Ctrmqlc86Yer5 /highlight.js +sha384-xWuEo3so2TxwMB/U1KZiCReufdgsA2YHUmiIDXDzepyfzlFU+kSLVZd1poU9Dpbj /highlight.min.js +``` + diff --git a/docs/docs_project/docs_project/static/highlight/LICENSE b/docs/docs_project/docs_project/static/highlight/LICENSE new file mode 100755 index 0000000..2250cc7 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/LICENSE @@ -0,0 +1,29 @@ +BSD 3-Clause License + +Copyright (c) 2006, Ivan Sagalaev. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/docs_project/docs_project/static/highlight/README.md b/docs/docs_project/docs_project/static/highlight/README.md new file mode 100755 index 0000000..30d84b9 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/README.md @@ -0,0 +1,45 @@ +# Highlight.js CDN Assets + +[![install size](https://packagephobia.now.sh/badge?p=highlight.js)](https://packagephobia.now.sh/result?p=highlight.js) + +**This package contains only the CDN build assets of highlight.js.** + +This may be what you want if you'd like to install the pre-built distributable highlight.js client-side assets via NPM. If you're wanting to use highlight.js mainly on the server-side you likely want the [highlight.js][1] package instead. + +To access these files via CDN:
+https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@latest/build/ + +**If you just want a single .js file with the common languages built-in: +** + +--- + +## Highlight.js + +Highlight.js is a syntax highlighter written in JavaScript. It works in +the browser as well as on the server. It works with pretty much any +markup, doesn’t depend on any framework, and has automatic language +detection. + +If you'd like to read the full README:
+ + +## License + +Highlight.js is released under the BSD License. See [LICENSE][7] file +for details. + +## Links + +The official site for the library is at . + +The Github project may be found at: + +Further in-depth documentation for the API and other topics is at +. + +A list of the Core Team and contributors can be found in the [CONTRIBUTORS.md][8] file. + +[1]: https://www.npmjs.com/package/highlight.js +[7]: https://github.com/highlightjs/highlight.js/blob/main/LICENSE +[8]: https://github.com/highlightjs/highlight.js/blob/main/CONTRIBUTORS.md diff --git a/docs/docs_project/docs_project/static/highlight/es/core.js b/docs/docs_project/docs_project/static/highlight/es/core.js new file mode 100755 index 0000000..7294b81 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/core.js @@ -0,0 +1,2600 @@ +/*! + Highlight.js v11.9.0 (git: b7ec4bfafc) + (c) 2006-2023 undefined and other contributors + License: BSD-3-Clause + */ +/* eslint-disable no-multi-assign */ + +function deepFreeze(obj) { + if (obj instanceof Map) { + obj.clear = + obj.delete = + obj.set = + function () { + throw new Error('map is read-only'); + }; + } else if (obj instanceof Set) { + obj.add = + obj.clear = + obj.delete = + function () { + throw new Error('set is read-only'); + }; + } + + // Freeze self + Object.freeze(obj); + + Object.getOwnPropertyNames(obj).forEach((name) => { + const prop = obj[name]; + const type = typeof prop; + + // Freeze prop if it is an object or function and also not already frozen + if ((type === 'object' || type === 'function') && !Object.isFrozen(prop)) { + deepFreeze(prop); + } + }); + + return obj; +} + +/** @typedef {import('highlight.js').CallbackResponse} CallbackResponse */ +/** @typedef {import('highlight.js').CompiledMode} CompiledMode */ +/** @implements CallbackResponse */ + +class Response { + /** + * @param {CompiledMode} mode + */ + constructor(mode) { + // eslint-disable-next-line no-undefined + if (mode.data === undefined) mode.data = {}; + + this.data = mode.data; + this.isMatchIgnored = false; + } + + ignoreMatch() { + this.isMatchIgnored = true; + } +} + +/** + * @param {string} value + * @returns {string} + */ +function escapeHTML(value) { + return value + .replace(/&/g, '&') + .replace(//g, '>') + .replace(/"/g, '"') + .replace(/'/g, '''); +} + +/** + * performs a shallow merge of multiple objects into one + * + * @template T + * @param {T} original + * @param {Record[]} objects + * @returns {T} a single new object + */ +function inherit$1(original, ...objects) { + /** @type Record */ + const result = Object.create(null); + + for (const key in original) { + result[key] = original[key]; + } + objects.forEach(function(obj) { + for (const key in obj) { + result[key] = obj[key]; + } + }); + return /** @type {T} */ (result); +} + +/** + * @typedef {object} Renderer + * @property {(text: string) => void} addText + * @property {(node: Node) => void} openNode + * @property {(node: Node) => void} closeNode + * @property {() => string} value + */ + +/** @typedef {{scope?: string, language?: string, sublanguage?: boolean}} Node */ +/** @typedef {{walk: (r: Renderer) => void}} Tree */ +/** */ + +const SPAN_CLOSE = ''; + +/** + * Determines if a node needs to be wrapped in + * + * @param {Node} node */ +const emitsWrappingTags = (node) => { + // rarely we can have a sublanguage where language is undefined + // TODO: track down why + return !!node.scope; +}; + +/** + * + * @param {string} name + * @param {{prefix:string}} options + */ +const scopeToCSSClass = (name, { prefix }) => { + // sub-language + if (name.startsWith("language:")) { + return name.replace("language:", "language-"); + } + // tiered scope: comment.line + if (name.includes(".")) { + const pieces = name.split("."); + return [ + `${prefix}${pieces.shift()}`, + ...(pieces.map((x, i) => `${x}${"_".repeat(i + 1)}`)) + ].join(" "); + } + // simple scope + return `${prefix}${name}`; +}; + +/** @type {Renderer} */ +class HTMLRenderer { + /** + * Creates a new HTMLRenderer + * + * @param {Tree} parseTree - the parse tree (must support `walk` API) + * @param {{classPrefix: string}} options + */ + constructor(parseTree, options) { + this.buffer = ""; + this.classPrefix = options.classPrefix; + parseTree.walk(this); + } + + /** + * Adds texts to the output stream + * + * @param {string} text */ + addText(text) { + this.buffer += escapeHTML(text); + } + + /** + * Adds a node open to the output stream (if needed) + * + * @param {Node} node */ + openNode(node) { + if (!emitsWrappingTags(node)) return; + + const className = scopeToCSSClass(node.scope, + { prefix: this.classPrefix }); + this.span(className); + } + + /** + * Adds a node close to the output stream (if needed) + * + * @param {Node} node */ + closeNode(node) { + if (!emitsWrappingTags(node)) return; + + this.buffer += SPAN_CLOSE; + } + + /** + * returns the accumulated buffer + */ + value() { + return this.buffer; + } + + // helpers + + /** + * Builds a span element + * + * @param {string} className */ + span(className) { + this.buffer += ``; + } +} + +/** @typedef {{scope?: string, language?: string, children: Node[]} | string} Node */ +/** @typedef {{scope?: string, language?: string, children: Node[]} } DataNode */ +/** @typedef {import('highlight.js').Emitter} Emitter */ +/** */ + +/** @returns {DataNode} */ +const newNode = (opts = {}) => { + /** @type DataNode */ + const result = { children: [] }; + Object.assign(result, opts); + return result; +}; + +class TokenTree { + constructor() { + /** @type DataNode */ + this.rootNode = newNode(); + this.stack = [this.rootNode]; + } + + get top() { + return this.stack[this.stack.length - 1]; + } + + get root() { return this.rootNode; } + + /** @param {Node} node */ + add(node) { + this.top.children.push(node); + } + + /** @param {string} scope */ + openNode(scope) { + /** @type Node */ + const node = newNode({ scope }); + this.add(node); + this.stack.push(node); + } + + closeNode() { + if (this.stack.length > 1) { + return this.stack.pop(); + } + // eslint-disable-next-line no-undefined + return undefined; + } + + closeAllNodes() { + while (this.closeNode()); + } + + toJSON() { + return JSON.stringify(this.rootNode, null, 4); + } + + /** + * @typedef { import("./html_renderer").Renderer } Renderer + * @param {Renderer} builder + */ + walk(builder) { + // this does not + return this.constructor._walk(builder, this.rootNode); + // this works + // return TokenTree._walk(builder, this.rootNode); + } + + /** + * @param {Renderer} builder + * @param {Node} node + */ + static _walk(builder, node) { + if (typeof node === "string") { + builder.addText(node); + } else if (node.children) { + builder.openNode(node); + node.children.forEach((child) => this._walk(builder, child)); + builder.closeNode(node); + } + return builder; + } + + /** + * @param {Node} node + */ + static _collapse(node) { + if (typeof node === "string") return; + if (!node.children) return; + + if (node.children.every(el => typeof el === "string")) { + // node.text = node.children.join(""); + // delete node.children; + node.children = [node.children.join("")]; + } else { + node.children.forEach((child) => { + TokenTree._collapse(child); + }); + } + } +} + +/** + Currently this is all private API, but this is the minimal API necessary + that an Emitter must implement to fully support the parser. + + Minimal interface: + + - addText(text) + - __addSublanguage(emitter, subLanguageName) + - startScope(scope) + - endScope() + - finalize() + - toHTML() + +*/ + +/** + * @implements {Emitter} + */ +class TokenTreeEmitter extends TokenTree { + /** + * @param {*} options + */ + constructor(options) { + super(); + this.options = options; + } + + /** + * @param {string} text + */ + addText(text) { + if (text === "") { return; } + + this.add(text); + } + + /** @param {string} scope */ + startScope(scope) { + this.openNode(scope); + } + + endScope() { + this.closeNode(); + } + + /** + * @param {Emitter & {root: DataNode}} emitter + * @param {string} name + */ + __addSublanguage(emitter, name) { + /** @type DataNode */ + const node = emitter.root; + if (name) node.scope = `language:${name}`; + + this.add(node); + } + + toHTML() { + const renderer = new HTMLRenderer(this, this.options); + return renderer.value(); + } + + finalize() { + this.closeAllNodes(); + return true; + } +} + +/** + * @param {string} value + * @returns {RegExp} + * */ + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function source(re) { + if (!re) return null; + if (typeof re === "string") return re; + + return re.source; +} + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function lookahead(re) { + return concat('(?=', re, ')'); +} + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function anyNumberOfTimes(re) { + return concat('(?:', re, ')*'); +} + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function optional(re) { + return concat('(?:', re, ')?'); +} + +/** + * @param {...(RegExp | string) } args + * @returns {string} + */ +function concat(...args) { + const joined = args.map((x) => source(x)).join(""); + return joined; +} + +/** + * @param { Array } args + * @returns {object} + */ +function stripOptionsFromArgs(args) { + const opts = args[args.length - 1]; + + if (typeof opts === 'object' && opts.constructor === Object) { + args.splice(args.length - 1, 1); + return opts; + } else { + return {}; + } +} + +/** @typedef { {capture?: boolean} } RegexEitherOptions */ + +/** + * Any of the passed expresssions may match + * + * Creates a huge this | this | that | that match + * @param {(RegExp | string)[] | [...(RegExp | string)[], RegexEitherOptions]} args + * @returns {string} + */ +function either(...args) { + /** @type { object & {capture?: boolean} } */ + const opts = stripOptionsFromArgs(args); + const joined = '(' + + (opts.capture ? "" : "?:") + + args.map((x) => source(x)).join("|") + ")"; + return joined; +} + +/** + * @param {RegExp | string} re + * @returns {number} + */ +function countMatchGroups(re) { + return (new RegExp(re.toString() + '|')).exec('').length - 1; +} + +/** + * Does lexeme start with a regular expression match at the beginning + * @param {RegExp} re + * @param {string} lexeme + */ +function startsWith(re, lexeme) { + const match = re && re.exec(lexeme); + return match && match.index === 0; +} + +// BACKREF_RE matches an open parenthesis or backreference. To avoid +// an incorrect parse, it additionally matches the following: +// - [...] elements, where the meaning of parentheses and escapes change +// - other escape sequences, so we do not misparse escape sequences as +// interesting elements +// - non-matching or lookahead parentheses, which do not capture. These +// follow the '(' with a '?'. +const BACKREF_RE = /\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./; + +// **INTERNAL** Not intended for outside usage +// join logically computes regexps.join(separator), but fixes the +// backreferences so they continue to match. +// it also places each individual regular expression into it's own +// match group, keeping track of the sequencing of those match groups +// is currently an exercise for the caller. :-) +/** + * @param {(string | RegExp)[]} regexps + * @param {{joinWith: string}} opts + * @returns {string} + */ +function _rewriteBackreferences(regexps, { joinWith }) { + let numCaptures = 0; + + return regexps.map((regex) => { + numCaptures += 1; + const offset = numCaptures; + let re = source(regex); + let out = ''; + + while (re.length > 0) { + const match = BACKREF_RE.exec(re); + if (!match) { + out += re; + break; + } + out += re.substring(0, match.index); + re = re.substring(match.index + match[0].length); + if (match[0][0] === '\\' && match[1]) { + // Adjust the backreference. + out += '\\' + String(Number(match[1]) + offset); + } else { + out += match[0]; + if (match[0] === '(') { + numCaptures++; + } + } + } + return out; + }).map(re => `(${re})`).join(joinWith); +} + +/** @typedef {import('highlight.js').Mode} Mode */ +/** @typedef {import('highlight.js').ModeCallback} ModeCallback */ + +// Common regexps +const MATCH_NOTHING_RE = /\b\B/; +const IDENT_RE = '[a-zA-Z]\\w*'; +const UNDERSCORE_IDENT_RE = '[a-zA-Z_]\\w*'; +const NUMBER_RE = '\\b\\d+(\\.\\d+)?'; +const C_NUMBER_RE = '(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)'; // 0x..., 0..., decimal, float +const BINARY_NUMBER_RE = '\\b(0b[01]+)'; // 0b... +const RE_STARTERS_RE = '!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~'; + +/** +* @param { Partial & {binary?: string | RegExp} } opts +*/ +const SHEBANG = (opts = {}) => { + const beginShebang = /^#![ ]*\//; + if (opts.binary) { + opts.begin = concat( + beginShebang, + /.*\b/, + opts.binary, + /\b.*/); + } + return inherit$1({ + scope: 'meta', + begin: beginShebang, + end: /$/, + relevance: 0, + /** @type {ModeCallback} */ + "on:begin": (m, resp) => { + if (m.index !== 0) resp.ignoreMatch(); + } + }, opts); +}; + +// Common modes +const BACKSLASH_ESCAPE = { + begin: '\\\\[\\s\\S]', relevance: 0 +}; +const APOS_STRING_MODE = { + scope: 'string', + begin: '\'', + end: '\'', + illegal: '\\n', + contains: [BACKSLASH_ESCAPE] +}; +const QUOTE_STRING_MODE = { + scope: 'string', + begin: '"', + end: '"', + illegal: '\\n', + contains: [BACKSLASH_ESCAPE] +}; +const PHRASAL_WORDS_MODE = { + begin: /\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/ +}; +/** + * Creates a comment mode + * + * @param {string | RegExp} begin + * @param {string | RegExp} end + * @param {Mode | {}} [modeOptions] + * @returns {Partial} + */ +const COMMENT = function(begin, end, modeOptions = {}) { + const mode = inherit$1( + { + scope: 'comment', + begin, + end, + contains: [] + }, + modeOptions + ); + mode.contains.push({ + scope: 'doctag', + // hack to avoid the space from being included. the space is necessary to + // match here to prevent the plain text rule below from gobbling up doctags + begin: '[ ]*(?=(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):)', + end: /(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):/, + excludeBegin: true, + relevance: 0 + }); + const ENGLISH_WORD = either( + // list of common 1 and 2 letter words in English + "I", + "a", + "is", + "so", + "us", + "to", + "at", + "if", + "in", + "it", + "on", + // note: this is not an exhaustive list of contractions, just popular ones + /[A-Za-z]+['](d|ve|re|ll|t|s|n)/, // contractions - can't we'd they're let's, etc + /[A-Za-z]+[-][a-z]+/, // `no-way`, etc. + /[A-Za-z][a-z]{2,}/ // allow capitalized words at beginning of sentences + ); + // looking like plain text, more likely to be a comment + mode.contains.push( + { + // TODO: how to include ", (, ) without breaking grammars that use these for + // comment delimiters? + // begin: /[ ]+([()"]?([A-Za-z'-]{3,}|is|a|I|so|us|[tT][oO]|at|if|in|it|on)[.]?[()":]?([.][ ]|[ ]|\))){3}/ + // --- + + // this tries to find sequences of 3 english words in a row (without any + // "programming" type syntax) this gives us a strong signal that we've + // TRULY found a comment - vs perhaps scanning with the wrong language. + // It's possible to find something that LOOKS like the start of the + // comment - but then if there is no readable text - good chance it is a + // false match and not a comment. + // + // for a visual example please see: + // https://github.com/highlightjs/highlight.js/issues/2827 + + begin: concat( + /[ ]+/, // necessary to prevent us gobbling up doctags like /* @author Bob Mcgill */ + '(', + ENGLISH_WORD, + /[.]?[:]?([.][ ]|[ ])/, + '){3}') // look for 3 words in a row + } + ); + return mode; +}; +const C_LINE_COMMENT_MODE = COMMENT('//', '$'); +const C_BLOCK_COMMENT_MODE = COMMENT('/\\*', '\\*/'); +const HASH_COMMENT_MODE = COMMENT('#', '$'); +const NUMBER_MODE = { + scope: 'number', + begin: NUMBER_RE, + relevance: 0 +}; +const C_NUMBER_MODE = { + scope: 'number', + begin: C_NUMBER_RE, + relevance: 0 +}; +const BINARY_NUMBER_MODE = { + scope: 'number', + begin: BINARY_NUMBER_RE, + relevance: 0 +}; +const REGEXP_MODE = { + scope: "regexp", + begin: /\/(?=[^/\n]*\/)/, + end: /\/[gimuy]*/, + contains: [ + BACKSLASH_ESCAPE, + { + begin: /\[/, + end: /\]/, + relevance: 0, + contains: [BACKSLASH_ESCAPE] + } + ] +}; +const TITLE_MODE = { + scope: 'title', + begin: IDENT_RE, + relevance: 0 +}; +const UNDERSCORE_TITLE_MODE = { + scope: 'title', + begin: UNDERSCORE_IDENT_RE, + relevance: 0 +}; +const METHOD_GUARD = { + // excludes method names from keyword processing + begin: '\\.\\s*' + UNDERSCORE_IDENT_RE, + relevance: 0 +}; + +/** + * Adds end same as begin mechanics to a mode + * + * Your mode must include at least a single () match group as that first match + * group is what is used for comparison + * @param {Partial} mode + */ +const END_SAME_AS_BEGIN = function(mode) { + return Object.assign(mode, + { + /** @type {ModeCallback} */ + 'on:begin': (m, resp) => { resp.data._beginMatch = m[1]; }, + /** @type {ModeCallback} */ + 'on:end': (m, resp) => { if (resp.data._beginMatch !== m[1]) resp.ignoreMatch(); } + }); +}; + +var MODES = /*#__PURE__*/Object.freeze({ + __proto__: null, + APOS_STRING_MODE: APOS_STRING_MODE, + BACKSLASH_ESCAPE: BACKSLASH_ESCAPE, + BINARY_NUMBER_MODE: BINARY_NUMBER_MODE, + BINARY_NUMBER_RE: BINARY_NUMBER_RE, + COMMENT: COMMENT, + C_BLOCK_COMMENT_MODE: C_BLOCK_COMMENT_MODE, + C_LINE_COMMENT_MODE: C_LINE_COMMENT_MODE, + C_NUMBER_MODE: C_NUMBER_MODE, + C_NUMBER_RE: C_NUMBER_RE, + END_SAME_AS_BEGIN: END_SAME_AS_BEGIN, + HASH_COMMENT_MODE: HASH_COMMENT_MODE, + IDENT_RE: IDENT_RE, + MATCH_NOTHING_RE: MATCH_NOTHING_RE, + METHOD_GUARD: METHOD_GUARD, + NUMBER_MODE: NUMBER_MODE, + NUMBER_RE: NUMBER_RE, + PHRASAL_WORDS_MODE: PHRASAL_WORDS_MODE, + QUOTE_STRING_MODE: QUOTE_STRING_MODE, + REGEXP_MODE: REGEXP_MODE, + RE_STARTERS_RE: RE_STARTERS_RE, + SHEBANG: SHEBANG, + TITLE_MODE: TITLE_MODE, + UNDERSCORE_IDENT_RE: UNDERSCORE_IDENT_RE, + UNDERSCORE_TITLE_MODE: UNDERSCORE_TITLE_MODE +}); + +/** +@typedef {import('highlight.js').CallbackResponse} CallbackResponse +@typedef {import('highlight.js').CompilerExt} CompilerExt +*/ + +// Grammar extensions / plugins +// See: https://github.com/highlightjs/highlight.js/issues/2833 + +// Grammar extensions allow "syntactic sugar" to be added to the grammar modes +// without requiring any underlying changes to the compiler internals. + +// `compileMatch` being the perfect small example of now allowing a grammar +// author to write `match` when they desire to match a single expression rather +// than being forced to use `begin`. The extension then just moves `match` into +// `begin` when it runs. Ie, no features have been added, but we've just made +// the experience of writing (and reading grammars) a little bit nicer. + +// ------ + +// TODO: We need negative look-behind support to do this properly +/** + * Skip a match if it has a preceding dot + * + * This is used for `beginKeywords` to prevent matching expressions such as + * `bob.keyword.do()`. The mode compiler automatically wires this up as a + * special _internal_ 'on:begin' callback for modes with `beginKeywords` + * @param {RegExpMatchArray} match + * @param {CallbackResponse} response + */ +function skipIfHasPrecedingDot(match, response) { + const before = match.input[match.index - 1]; + if (before === ".") { + response.ignoreMatch(); + } +} + +/** + * + * @type {CompilerExt} + */ +function scopeClassName(mode, _parent) { + // eslint-disable-next-line no-undefined + if (mode.className !== undefined) { + mode.scope = mode.className; + delete mode.className; + } +} + +/** + * `beginKeywords` syntactic sugar + * @type {CompilerExt} + */ +function beginKeywords(mode, parent) { + if (!parent) return; + if (!mode.beginKeywords) return; + + // for languages with keywords that include non-word characters checking for + // a word boundary is not sufficient, so instead we check for a word boundary + // or whitespace - this does no harm in any case since our keyword engine + // doesn't allow spaces in keywords anyways and we still check for the boundary + // first + mode.begin = '\\b(' + mode.beginKeywords.split(' ').join('|') + ')(?!\\.)(?=\\b|\\s)'; + mode.__beforeBegin = skipIfHasPrecedingDot; + mode.keywords = mode.keywords || mode.beginKeywords; + delete mode.beginKeywords; + + // prevents double relevance, the keywords themselves provide + // relevance, the mode doesn't need to double it + // eslint-disable-next-line no-undefined + if (mode.relevance === undefined) mode.relevance = 0; +} + +/** + * Allow `illegal` to contain an array of illegal values + * @type {CompilerExt} + */ +function compileIllegal(mode, _parent) { + if (!Array.isArray(mode.illegal)) return; + + mode.illegal = either(...mode.illegal); +} + +/** + * `match` to match a single expression for readability + * @type {CompilerExt} + */ +function compileMatch(mode, _parent) { + if (!mode.match) return; + if (mode.begin || mode.end) throw new Error("begin & end are not supported with match"); + + mode.begin = mode.match; + delete mode.match; +} + +/** + * provides the default 1 relevance to all modes + * @type {CompilerExt} + */ +function compileRelevance(mode, _parent) { + // eslint-disable-next-line no-undefined + if (mode.relevance === undefined) mode.relevance = 1; +} + +// allow beforeMatch to act as a "qualifier" for the match +// the full match begin must be [beforeMatch][begin] +const beforeMatchExt = (mode, parent) => { + if (!mode.beforeMatch) return; + // starts conflicts with endsParent which we need to make sure the child + // rule is not matched multiple times + if (mode.starts) throw new Error("beforeMatch cannot be used with starts"); + + const originalMode = Object.assign({}, mode); + Object.keys(mode).forEach((key) => { delete mode[key]; }); + + mode.keywords = originalMode.keywords; + mode.begin = concat(originalMode.beforeMatch, lookahead(originalMode.begin)); + mode.starts = { + relevance: 0, + contains: [ + Object.assign(originalMode, { endsParent: true }) + ] + }; + mode.relevance = 0; + + delete originalMode.beforeMatch; +}; + +// keywords that should have no default relevance value +const COMMON_KEYWORDS = [ + 'of', + 'and', + 'for', + 'in', + 'not', + 'or', + 'if', + 'then', + 'parent', // common variable name + 'list', // common variable name + 'value' // common variable name +]; + +const DEFAULT_KEYWORD_SCOPE = "keyword"; + +/** + * Given raw keywords from a language definition, compile them. + * + * @param {string | Record | Array} rawKeywords + * @param {boolean} caseInsensitive + */ +function compileKeywords(rawKeywords, caseInsensitive, scopeName = DEFAULT_KEYWORD_SCOPE) { + /** @type {import("highlight.js/private").KeywordDict} */ + const compiledKeywords = Object.create(null); + + // input can be a string of keywords, an array of keywords, or a object with + // named keys representing scopeName (which can then point to a string or array) + if (typeof rawKeywords === 'string') { + compileList(scopeName, rawKeywords.split(" ")); + } else if (Array.isArray(rawKeywords)) { + compileList(scopeName, rawKeywords); + } else { + Object.keys(rawKeywords).forEach(function(scopeName) { + // collapse all our objects back into the parent object + Object.assign( + compiledKeywords, + compileKeywords(rawKeywords[scopeName], caseInsensitive, scopeName) + ); + }); + } + return compiledKeywords; + + // --- + + /** + * Compiles an individual list of keywords + * + * Ex: "for if when while|5" + * + * @param {string} scopeName + * @param {Array} keywordList + */ + function compileList(scopeName, keywordList) { + if (caseInsensitive) { + keywordList = keywordList.map(x => x.toLowerCase()); + } + keywordList.forEach(function(keyword) { + const pair = keyword.split('|'); + compiledKeywords[pair[0]] = [scopeName, scoreForKeyword(pair[0], pair[1])]; + }); + } +} + +/** + * Returns the proper score for a given keyword + * + * Also takes into account comment keywords, which will be scored 0 UNLESS + * another score has been manually assigned. + * @param {string} keyword + * @param {string} [providedScore] + */ +function scoreForKeyword(keyword, providedScore) { + // manual scores always win over common keywords + // so you can force a score of 1 if you really insist + if (providedScore) { + return Number(providedScore); + } + + return commonKeyword(keyword) ? 0 : 1; +} + +/** + * Determines if a given keyword is common or not + * + * @param {string} keyword */ +function commonKeyword(keyword) { + return COMMON_KEYWORDS.includes(keyword.toLowerCase()); +} + +/* + +For the reasoning behind this please see: +https://github.com/highlightjs/highlight.js/issues/2880#issuecomment-747275419 + +*/ + +/** + * @type {Record} + */ +const seenDeprecations = {}; + +/** + * @param {string} message + */ +const error = (message) => { + console.error(message); +}; + +/** + * @param {string} message + * @param {any} args + */ +const warn = (message, ...args) => { + console.log(`WARN: ${message}`, ...args); +}; + +/** + * @param {string} version + * @param {string} message + */ +const deprecated = (version, message) => { + if (seenDeprecations[`${version}/${message}`]) return; + + console.log(`Deprecated as of ${version}. ${message}`); + seenDeprecations[`${version}/${message}`] = true; +}; + +/* eslint-disable no-throw-literal */ + +/** +@typedef {import('highlight.js').CompiledMode} CompiledMode +*/ + +const MultiClassError = new Error(); + +/** + * Renumbers labeled scope names to account for additional inner match + * groups that otherwise would break everything. + * + * Lets say we 3 match scopes: + * + * { 1 => ..., 2 => ..., 3 => ... } + * + * So what we need is a clean match like this: + * + * (a)(b)(c) => [ "a", "b", "c" ] + * + * But this falls apart with inner match groups: + * + * (a)(((b)))(c) => ["a", "b", "b", "b", "c" ] + * + * Our scopes are now "out of alignment" and we're repeating `b` 3 times. + * What needs to happen is the numbers are remapped: + * + * { 1 => ..., 2 => ..., 5 => ... } + * + * We also need to know that the ONLY groups that should be output + * are 1, 2, and 5. This function handles this behavior. + * + * @param {CompiledMode} mode + * @param {Array} regexes + * @param {{key: "beginScope"|"endScope"}} opts + */ +function remapScopeNames(mode, regexes, { key }) { + let offset = 0; + const scopeNames = mode[key]; + /** @type Record */ + const emit = {}; + /** @type Record */ + const positions = {}; + + for (let i = 1; i <= regexes.length; i++) { + positions[i + offset] = scopeNames[i]; + emit[i + offset] = true; + offset += countMatchGroups(regexes[i - 1]); + } + // we use _emit to keep track of which match groups are "top-level" to avoid double + // output from inside match groups + mode[key] = positions; + mode[key]._emit = emit; + mode[key]._multi = true; +} + +/** + * @param {CompiledMode} mode + */ +function beginMultiClass(mode) { + if (!Array.isArray(mode.begin)) return; + + if (mode.skip || mode.excludeBegin || mode.returnBegin) { + error("skip, excludeBegin, returnBegin not compatible with beginScope: {}"); + throw MultiClassError; + } + + if (typeof mode.beginScope !== "object" || mode.beginScope === null) { + error("beginScope must be object"); + throw MultiClassError; + } + + remapScopeNames(mode, mode.begin, { key: "beginScope" }); + mode.begin = _rewriteBackreferences(mode.begin, { joinWith: "" }); +} + +/** + * @param {CompiledMode} mode + */ +function endMultiClass(mode) { + if (!Array.isArray(mode.end)) return; + + if (mode.skip || mode.excludeEnd || mode.returnEnd) { + error("skip, excludeEnd, returnEnd not compatible with endScope: {}"); + throw MultiClassError; + } + + if (typeof mode.endScope !== "object" || mode.endScope === null) { + error("endScope must be object"); + throw MultiClassError; + } + + remapScopeNames(mode, mode.end, { key: "endScope" }); + mode.end = _rewriteBackreferences(mode.end, { joinWith: "" }); +} + +/** + * this exists only to allow `scope: {}` to be used beside `match:` + * Otherwise `beginScope` would necessary and that would look weird + + { + match: [ /def/, /\w+/ ] + scope: { 1: "keyword" , 2: "title" } + } + + * @param {CompiledMode} mode + */ +function scopeSugar(mode) { + if (mode.scope && typeof mode.scope === "object" && mode.scope !== null) { + mode.beginScope = mode.scope; + delete mode.scope; + } +} + +/** + * @param {CompiledMode} mode + */ +function MultiClass(mode) { + scopeSugar(mode); + + if (typeof mode.beginScope === "string") { + mode.beginScope = { _wrap: mode.beginScope }; + } + if (typeof mode.endScope === "string") { + mode.endScope = { _wrap: mode.endScope }; + } + + beginMultiClass(mode); + endMultiClass(mode); +} + +/** +@typedef {import('highlight.js').Mode} Mode +@typedef {import('highlight.js').CompiledMode} CompiledMode +@typedef {import('highlight.js').Language} Language +@typedef {import('highlight.js').HLJSPlugin} HLJSPlugin +@typedef {import('highlight.js').CompiledLanguage} CompiledLanguage +*/ + +// compilation + +/** + * Compiles a language definition result + * + * Given the raw result of a language definition (Language), compiles this so + * that it is ready for highlighting code. + * @param {Language} language + * @returns {CompiledLanguage} + */ +function compileLanguage(language) { + /** + * Builds a regex with the case sensitivity of the current language + * + * @param {RegExp | string} value + * @param {boolean} [global] + */ + function langRe(value, global) { + return new RegExp( + source(value), + 'm' + + (language.case_insensitive ? 'i' : '') + + (language.unicodeRegex ? 'u' : '') + + (global ? 'g' : '') + ); + } + + /** + Stores multiple regular expressions and allows you to quickly search for + them all in a string simultaneously - returning the first match. It does + this by creating a huge (a|b|c) regex - each individual item wrapped with () + and joined by `|` - using match groups to track position. When a match is + found checking which position in the array has content allows us to figure + out which of the original regexes / match groups triggered the match. + + The match object itself (the result of `Regex.exec`) is returned but also + enhanced by merging in any meta-data that was registered with the regex. + This is how we keep track of which mode matched, and what type of rule + (`illegal`, `begin`, end, etc). + */ + class MultiRegex { + constructor() { + this.matchIndexes = {}; + // @ts-ignore + this.regexes = []; + this.matchAt = 1; + this.position = 0; + } + + // @ts-ignore + addRule(re, opts) { + opts.position = this.position++; + // @ts-ignore + this.matchIndexes[this.matchAt] = opts; + this.regexes.push([opts, re]); + this.matchAt += countMatchGroups(re) + 1; + } + + compile() { + if (this.regexes.length === 0) { + // avoids the need to check length every time exec is called + // @ts-ignore + this.exec = () => null; + } + const terminators = this.regexes.map(el => el[1]); + this.matcherRe = langRe(_rewriteBackreferences(terminators, { joinWith: '|' }), true); + this.lastIndex = 0; + } + + /** @param {string} s */ + exec(s) { + this.matcherRe.lastIndex = this.lastIndex; + const match = this.matcherRe.exec(s); + if (!match) { return null; } + + // eslint-disable-next-line no-undefined + const i = match.findIndex((el, i) => i > 0 && el !== undefined); + // @ts-ignore + const matchData = this.matchIndexes[i]; + // trim off any earlier non-relevant match groups (ie, the other regex + // match groups that make up the multi-matcher) + match.splice(0, i); + + return Object.assign(match, matchData); + } + } + + /* + Created to solve the key deficiently with MultiRegex - there is no way to + test for multiple matches at a single location. Why would we need to do + that? In the future a more dynamic engine will allow certain matches to be + ignored. An example: if we matched say the 3rd regex in a large group but + decided to ignore it - we'd need to started testing again at the 4th + regex... but MultiRegex itself gives us no real way to do that. + + So what this class creates MultiRegexs on the fly for whatever search + position they are needed. + + NOTE: These additional MultiRegex objects are created dynamically. For most + grammars most of the time we will never actually need anything more than the + first MultiRegex - so this shouldn't have too much overhead. + + Say this is our search group, and we match regex3, but wish to ignore it. + + regex1 | regex2 | regex3 | regex4 | regex5 ' ie, startAt = 0 + + What we need is a new MultiRegex that only includes the remaining + possibilities: + + regex4 | regex5 ' ie, startAt = 3 + + This class wraps all that complexity up in a simple API... `startAt` decides + where in the array of expressions to start doing the matching. It + auto-increments, so if a match is found at position 2, then startAt will be + set to 3. If the end is reached startAt will return to 0. + + MOST of the time the parser will be setting startAt manually to 0. + */ + class ResumableMultiRegex { + constructor() { + // @ts-ignore + this.rules = []; + // @ts-ignore + this.multiRegexes = []; + this.count = 0; + + this.lastIndex = 0; + this.regexIndex = 0; + } + + // @ts-ignore + getMatcher(index) { + if (this.multiRegexes[index]) return this.multiRegexes[index]; + + const matcher = new MultiRegex(); + this.rules.slice(index).forEach(([re, opts]) => matcher.addRule(re, opts)); + matcher.compile(); + this.multiRegexes[index] = matcher; + return matcher; + } + + resumingScanAtSamePosition() { + return this.regexIndex !== 0; + } + + considerAll() { + this.regexIndex = 0; + } + + // @ts-ignore + addRule(re, opts) { + this.rules.push([re, opts]); + if (opts.type === "begin") this.count++; + } + + /** @param {string} s */ + exec(s) { + const m = this.getMatcher(this.regexIndex); + m.lastIndex = this.lastIndex; + let result = m.exec(s); + + // The following is because we have no easy way to say "resume scanning at the + // existing position but also skip the current rule ONLY". What happens is + // all prior rules are also skipped which can result in matching the wrong + // thing. Example of matching "booger": + + // our matcher is [string, "booger", number] + // + // ....booger.... + + // if "booger" is ignored then we'd really need a regex to scan from the + // SAME position for only: [string, number] but ignoring "booger" (if it + // was the first match), a simple resume would scan ahead who knows how + // far looking only for "number", ignoring potential string matches (or + // future "booger" matches that might be valid.) + + // So what we do: We execute two matchers, one resuming at the same + // position, but the second full matcher starting at the position after: + + // /--- resume first regex match here (for [number]) + // |/---- full match here for [string, "booger", number] + // vv + // ....booger.... + + // Which ever results in a match first is then used. So this 3-4 step + // process essentially allows us to say "match at this position, excluding + // a prior rule that was ignored". + // + // 1. Match "booger" first, ignore. Also proves that [string] does non match. + // 2. Resume matching for [number] + // 3. Match at index + 1 for [string, "booger", number] + // 4. If #2 and #3 result in matches, which came first? + if (this.resumingScanAtSamePosition()) { + if (result && result.index === this.lastIndex) ; else { // use the second matcher result + const m2 = this.getMatcher(0); + m2.lastIndex = this.lastIndex + 1; + result = m2.exec(s); + } + } + + if (result) { + this.regexIndex += result.position + 1; + if (this.regexIndex === this.count) { + // wrap-around to considering all matches again + this.considerAll(); + } + } + + return result; + } + } + + /** + * Given a mode, builds a huge ResumableMultiRegex that can be used to walk + * the content and find matches. + * + * @param {CompiledMode} mode + * @returns {ResumableMultiRegex} + */ + function buildModeRegex(mode) { + const mm = new ResumableMultiRegex(); + + mode.contains.forEach(term => mm.addRule(term.begin, { rule: term, type: "begin" })); + + if (mode.terminatorEnd) { + mm.addRule(mode.terminatorEnd, { type: "end" }); + } + if (mode.illegal) { + mm.addRule(mode.illegal, { type: "illegal" }); + } + + return mm; + } + + /** skip vs abort vs ignore + * + * @skip - The mode is still entered and exited normally (and contains rules apply), + * but all content is held and added to the parent buffer rather than being + * output when the mode ends. Mostly used with `sublanguage` to build up + * a single large buffer than can be parsed by sublanguage. + * + * - The mode begin ands ends normally. + * - Content matched is added to the parent mode buffer. + * - The parser cursor is moved forward normally. + * + * @abort - A hack placeholder until we have ignore. Aborts the mode (as if it + * never matched) but DOES NOT continue to match subsequent `contains` + * modes. Abort is bad/suboptimal because it can result in modes + * farther down not getting applied because an earlier rule eats the + * content but then aborts. + * + * - The mode does not begin. + * - Content matched by `begin` is added to the mode buffer. + * - The parser cursor is moved forward accordingly. + * + * @ignore - Ignores the mode (as if it never matched) and continues to match any + * subsequent `contains` modes. Ignore isn't technically possible with + * the current parser implementation. + * + * - The mode does not begin. + * - Content matched by `begin` is ignored. + * - The parser cursor is not moved forward. + */ + + /** + * Compiles an individual mode + * + * This can raise an error if the mode contains certain detectable known logic + * issues. + * @param {Mode} mode + * @param {CompiledMode | null} [parent] + * @returns {CompiledMode | never} + */ + function compileMode(mode, parent) { + const cmode = /** @type CompiledMode */ (mode); + if (mode.isCompiled) return cmode; + + [ + scopeClassName, + // do this early so compiler extensions generally don't have to worry about + // the distinction between match/begin + compileMatch, + MultiClass, + beforeMatchExt + ].forEach(ext => ext(mode, parent)); + + language.compilerExtensions.forEach(ext => ext(mode, parent)); + + // __beforeBegin is considered private API, internal use only + mode.__beforeBegin = null; + + [ + beginKeywords, + // do this later so compiler extensions that come earlier have access to the + // raw array if they wanted to perhaps manipulate it, etc. + compileIllegal, + // default to 1 relevance if not specified + compileRelevance + ].forEach(ext => ext(mode, parent)); + + mode.isCompiled = true; + + let keywordPattern = null; + if (typeof mode.keywords === "object" && mode.keywords.$pattern) { + // we need a copy because keywords might be compiled multiple times + // so we can't go deleting $pattern from the original on the first + // pass + mode.keywords = Object.assign({}, mode.keywords); + keywordPattern = mode.keywords.$pattern; + delete mode.keywords.$pattern; + } + keywordPattern = keywordPattern || /\w+/; + + if (mode.keywords) { + mode.keywords = compileKeywords(mode.keywords, language.case_insensitive); + } + + cmode.keywordPatternRe = langRe(keywordPattern, true); + + if (parent) { + if (!mode.begin) mode.begin = /\B|\b/; + cmode.beginRe = langRe(cmode.begin); + if (!mode.end && !mode.endsWithParent) mode.end = /\B|\b/; + if (mode.end) cmode.endRe = langRe(cmode.end); + cmode.terminatorEnd = source(cmode.end) || ''; + if (mode.endsWithParent && parent.terminatorEnd) { + cmode.terminatorEnd += (mode.end ? '|' : '') + parent.terminatorEnd; + } + } + if (mode.illegal) cmode.illegalRe = langRe(/** @type {RegExp | string} */ (mode.illegal)); + if (!mode.contains) mode.contains = []; + + mode.contains = [].concat(...mode.contains.map(function(c) { + return expandOrCloneMode(c === 'self' ? mode : c); + })); + mode.contains.forEach(function(c) { compileMode(/** @type Mode */ (c), cmode); }); + + if (mode.starts) { + compileMode(mode.starts, parent); + } + + cmode.matcher = buildModeRegex(cmode); + return cmode; + } + + if (!language.compilerExtensions) language.compilerExtensions = []; + + // self is not valid at the top-level + if (language.contains && language.contains.includes('self')) { + throw new Error("ERR: contains `self` is not supported at the top-level of a language. See documentation."); + } + + // we need a null object, which inherit will guarantee + language.classNameAliases = inherit$1(language.classNameAliases || {}); + + return compileMode(/** @type Mode */ (language)); +} + +/** + * Determines if a mode has a dependency on it's parent or not + * + * If a mode does have a parent dependency then often we need to clone it if + * it's used in multiple places so that each copy points to the correct parent, + * where-as modes without a parent can often safely be re-used at the bottom of + * a mode chain. + * + * @param {Mode | null} mode + * @returns {boolean} - is there a dependency on the parent? + * */ +function dependencyOnParent(mode) { + if (!mode) return false; + + return mode.endsWithParent || dependencyOnParent(mode.starts); +} + +/** + * Expands a mode or clones it if necessary + * + * This is necessary for modes with parental dependenceis (see notes on + * `dependencyOnParent`) and for nodes that have `variants` - which must then be + * exploded into their own individual modes at compile time. + * + * @param {Mode} mode + * @returns {Mode | Mode[]} + * */ +function expandOrCloneMode(mode) { + if (mode.variants && !mode.cachedVariants) { + mode.cachedVariants = mode.variants.map(function(variant) { + return inherit$1(mode, { variants: null }, variant); + }); + } + + // EXPAND + // if we have variants then essentially "replace" the mode with the variants + // this happens in compileMode, where this function is called from + if (mode.cachedVariants) { + return mode.cachedVariants; + } + + // CLONE + // if we have dependencies on parents then we need a unique + // instance of ourselves, so we can be reused with many + // different parents without issue + if (dependencyOnParent(mode)) { + return inherit$1(mode, { starts: mode.starts ? inherit$1(mode.starts) : null }); + } + + if (Object.isFrozen(mode)) { + return inherit$1(mode); + } + + // no special dependency issues, just return ourselves + return mode; +} + +var version = "11.9.0"; + +class HTMLInjectionError extends Error { + constructor(reason, html) { + super(reason); + this.name = "HTMLInjectionError"; + this.html = html; + } +} + +/* +Syntax highlighting with language autodetection. +https://highlightjs.org/ +*/ + + + +/** +@typedef {import('highlight.js').Mode} Mode +@typedef {import('highlight.js').CompiledMode} CompiledMode +@typedef {import('highlight.js').CompiledScope} CompiledScope +@typedef {import('highlight.js').Language} Language +@typedef {import('highlight.js').HLJSApi} HLJSApi +@typedef {import('highlight.js').HLJSPlugin} HLJSPlugin +@typedef {import('highlight.js').PluginEvent} PluginEvent +@typedef {import('highlight.js').HLJSOptions} HLJSOptions +@typedef {import('highlight.js').LanguageFn} LanguageFn +@typedef {import('highlight.js').HighlightedHTMLElement} HighlightedHTMLElement +@typedef {import('highlight.js').BeforeHighlightContext} BeforeHighlightContext +@typedef {import('highlight.js/private').MatchType} MatchType +@typedef {import('highlight.js/private').KeywordData} KeywordData +@typedef {import('highlight.js/private').EnhancedMatch} EnhancedMatch +@typedef {import('highlight.js/private').AnnotatedError} AnnotatedError +@typedef {import('highlight.js').AutoHighlightResult} AutoHighlightResult +@typedef {import('highlight.js').HighlightOptions} HighlightOptions +@typedef {import('highlight.js').HighlightResult} HighlightResult +*/ + + +const escape = escapeHTML; +const inherit = inherit$1; +const NO_MATCH = Symbol("nomatch"); +const MAX_KEYWORD_HITS = 7; + +/** + * @param {any} hljs - object that is extended (legacy) + * @returns {HLJSApi} + */ +const HLJS = function(hljs) { + // Global internal variables used within the highlight.js library. + /** @type {Record} */ + const languages = Object.create(null); + /** @type {Record} */ + const aliases = Object.create(null); + /** @type {HLJSPlugin[]} */ + const plugins = []; + + // safe/production mode - swallows more errors, tries to keep running + // even if a single syntax or parse hits a fatal error + let SAFE_MODE = true; + const LANGUAGE_NOT_FOUND = "Could not find the language '{}', did you forget to load/include a language module?"; + /** @type {Language} */ + const PLAINTEXT_LANGUAGE = { disableAutodetect: true, name: 'Plain text', contains: [] }; + + // Global options used when within external APIs. This is modified when + // calling the `hljs.configure` function. + /** @type HLJSOptions */ + let options = { + ignoreUnescapedHTML: false, + throwUnescapedHTML: false, + noHighlightRe: /^(no-?highlight)$/i, + languageDetectRe: /\blang(?:uage)?-([\w-]+)\b/i, + classPrefix: 'hljs-', + cssSelector: 'pre code', + languages: null, + // beta configuration options, subject to change, welcome to discuss + // https://github.com/highlightjs/highlight.js/issues/1086 + __emitter: TokenTreeEmitter + }; + + /* Utility functions */ + + /** + * Tests a language name to see if highlighting should be skipped + * @param {string} languageName + */ + function shouldNotHighlight(languageName) { + return options.noHighlightRe.test(languageName); + } + + /** + * @param {HighlightedHTMLElement} block - the HTML element to determine language for + */ + function blockLanguage(block) { + let classes = block.className + ' '; + + classes += block.parentNode ? block.parentNode.className : ''; + + // language-* takes precedence over non-prefixed class names. + const match = options.languageDetectRe.exec(classes); + if (match) { + const language = getLanguage(match[1]); + if (!language) { + warn(LANGUAGE_NOT_FOUND.replace("{}", match[1])); + warn("Falling back to no-highlight mode for this block.", block); + } + return language ? match[1] : 'no-highlight'; + } + + return classes + .split(/\s+/) + .find((_class) => shouldNotHighlight(_class) || getLanguage(_class)); + } + + /** + * Core highlighting function. + * + * OLD API + * highlight(lang, code, ignoreIllegals, continuation) + * + * NEW API + * highlight(code, {lang, ignoreIllegals}) + * + * @param {string} codeOrLanguageName - the language to use for highlighting + * @param {string | HighlightOptions} optionsOrCode - the code to highlight + * @param {boolean} [ignoreIllegals] - whether to ignore illegal matches, default is to bail + * + * @returns {HighlightResult} Result - an object that represents the result + * @property {string} language - the language name + * @property {number} relevance - the relevance score + * @property {string} value - the highlighted HTML code + * @property {string} code - the original raw code + * @property {CompiledMode} top - top of the current mode stack + * @property {boolean} illegal - indicates whether any illegal matches were found + */ + function highlight(codeOrLanguageName, optionsOrCode, ignoreIllegals) { + let code = ""; + let languageName = ""; + if (typeof optionsOrCode === "object") { + code = codeOrLanguageName; + ignoreIllegals = optionsOrCode.ignoreIllegals; + languageName = optionsOrCode.language; + } else { + // old API + deprecated("10.7.0", "highlight(lang, code, ...args) has been deprecated."); + deprecated("10.7.0", "Please use highlight(code, options) instead.\nhttps://github.com/highlightjs/highlight.js/issues/2277"); + languageName = codeOrLanguageName; + code = optionsOrCode; + } + + // https://github.com/highlightjs/highlight.js/issues/3149 + // eslint-disable-next-line no-undefined + if (ignoreIllegals === undefined) { ignoreIllegals = true; } + + /** @type {BeforeHighlightContext} */ + const context = { + code, + language: languageName + }; + // the plugin can change the desired language or the code to be highlighted + // just be changing the object it was passed + fire("before:highlight", context); + + // a before plugin can usurp the result completely by providing it's own + // in which case we don't even need to call highlight + const result = context.result + ? context.result + : _highlight(context.language, context.code, ignoreIllegals); + + result.code = context.code; + // the plugin can change anything in result to suite it + fire("after:highlight", result); + + return result; + } + + /** + * private highlight that's used internally and does not fire callbacks + * + * @param {string} languageName - the language to use for highlighting + * @param {string} codeToHighlight - the code to highlight + * @param {boolean?} [ignoreIllegals] - whether to ignore illegal matches, default is to bail + * @param {CompiledMode?} [continuation] - current continuation mode, if any + * @returns {HighlightResult} - result of the highlight operation + */ + function _highlight(languageName, codeToHighlight, ignoreIllegals, continuation) { + const keywordHits = Object.create(null); + + /** + * Return keyword data if a match is a keyword + * @param {CompiledMode} mode - current mode + * @param {string} matchText - the textual match + * @returns {KeywordData | false} + */ + function keywordData(mode, matchText) { + return mode.keywords[matchText]; + } + + function processKeywords() { + if (!top.keywords) { + emitter.addText(modeBuffer); + return; + } + + let lastIndex = 0; + top.keywordPatternRe.lastIndex = 0; + let match = top.keywordPatternRe.exec(modeBuffer); + let buf = ""; + + while (match) { + buf += modeBuffer.substring(lastIndex, match.index); + const word = language.case_insensitive ? match[0].toLowerCase() : match[0]; + const data = keywordData(top, word); + if (data) { + const [kind, keywordRelevance] = data; + emitter.addText(buf); + buf = ""; + + keywordHits[word] = (keywordHits[word] || 0) + 1; + if (keywordHits[word] <= MAX_KEYWORD_HITS) relevance += keywordRelevance; + if (kind.startsWith("_")) { + // _ implied for relevance only, do not highlight + // by applying a class name + buf += match[0]; + } else { + const cssClass = language.classNameAliases[kind] || kind; + emitKeyword(match[0], cssClass); + } + } else { + buf += match[0]; + } + lastIndex = top.keywordPatternRe.lastIndex; + match = top.keywordPatternRe.exec(modeBuffer); + } + buf += modeBuffer.substring(lastIndex); + emitter.addText(buf); + } + + function processSubLanguage() { + if (modeBuffer === "") return; + /** @type HighlightResult */ + let result = null; + + if (typeof top.subLanguage === 'string') { + if (!languages[top.subLanguage]) { + emitter.addText(modeBuffer); + return; + } + result = _highlight(top.subLanguage, modeBuffer, true, continuations[top.subLanguage]); + continuations[top.subLanguage] = /** @type {CompiledMode} */ (result._top); + } else { + result = highlightAuto(modeBuffer, top.subLanguage.length ? top.subLanguage : null); + } + + // Counting embedded language score towards the host language may be disabled + // with zeroing the containing mode relevance. Use case in point is Markdown that + // allows XML everywhere and makes every XML snippet to have a much larger Markdown + // score. + if (top.relevance > 0) { + relevance += result.relevance; + } + emitter.__addSublanguage(result._emitter, result.language); + } + + function processBuffer() { + if (top.subLanguage != null) { + processSubLanguage(); + } else { + processKeywords(); + } + modeBuffer = ''; + } + + /** + * @param {string} text + * @param {string} scope + */ + function emitKeyword(keyword, scope) { + if (keyword === "") return; + + emitter.startScope(scope); + emitter.addText(keyword); + emitter.endScope(); + } + + /** + * @param {CompiledScope} scope + * @param {RegExpMatchArray} match + */ + function emitMultiClass(scope, match) { + let i = 1; + const max = match.length - 1; + while (i <= max) { + if (!scope._emit[i]) { i++; continue; } + const klass = language.classNameAliases[scope[i]] || scope[i]; + const text = match[i]; + if (klass) { + emitKeyword(text, klass); + } else { + modeBuffer = text; + processKeywords(); + modeBuffer = ""; + } + i++; + } + } + + /** + * @param {CompiledMode} mode - new mode to start + * @param {RegExpMatchArray} match + */ + function startNewMode(mode, match) { + if (mode.scope && typeof mode.scope === "string") { + emitter.openNode(language.classNameAliases[mode.scope] || mode.scope); + } + if (mode.beginScope) { + // beginScope just wraps the begin match itself in a scope + if (mode.beginScope._wrap) { + emitKeyword(modeBuffer, language.classNameAliases[mode.beginScope._wrap] || mode.beginScope._wrap); + modeBuffer = ""; + } else if (mode.beginScope._multi) { + // at this point modeBuffer should just be the match + emitMultiClass(mode.beginScope, match); + modeBuffer = ""; + } + } + + top = Object.create(mode, { parent: { value: top } }); + return top; + } + + /** + * @param {CompiledMode } mode - the mode to potentially end + * @param {RegExpMatchArray} match - the latest match + * @param {string} matchPlusRemainder - match plus remainder of content + * @returns {CompiledMode | void} - the next mode, or if void continue on in current mode + */ + function endOfMode(mode, match, matchPlusRemainder) { + let matched = startsWith(mode.endRe, matchPlusRemainder); + + if (matched) { + if (mode["on:end"]) { + const resp = new Response(mode); + mode["on:end"](match, resp); + if (resp.isMatchIgnored) matched = false; + } + + if (matched) { + while (mode.endsParent && mode.parent) { + mode = mode.parent; + } + return mode; + } + } + // even if on:end fires an `ignore` it's still possible + // that we might trigger the end node because of a parent mode + if (mode.endsWithParent) { + return endOfMode(mode.parent, match, matchPlusRemainder); + } + } + + /** + * Handle matching but then ignoring a sequence of text + * + * @param {string} lexeme - string containing full match text + */ + function doIgnore(lexeme) { + if (top.matcher.regexIndex === 0) { + // no more regexes to potentially match here, so we move the cursor forward one + // space + modeBuffer += lexeme[0]; + return 1; + } else { + // no need to move the cursor, we still have additional regexes to try and + // match at this very spot + resumeScanAtSamePosition = true; + return 0; + } + } + + /** + * Handle the start of a new potential mode match + * + * @param {EnhancedMatch} match - the current match + * @returns {number} how far to advance the parse cursor + */ + function doBeginMatch(match) { + const lexeme = match[0]; + const newMode = match.rule; + + const resp = new Response(newMode); + // first internal before callbacks, then the public ones + const beforeCallbacks = [newMode.__beforeBegin, newMode["on:begin"]]; + for (const cb of beforeCallbacks) { + if (!cb) continue; + cb(match, resp); + if (resp.isMatchIgnored) return doIgnore(lexeme); + } + + if (newMode.skip) { + modeBuffer += lexeme; + } else { + if (newMode.excludeBegin) { + modeBuffer += lexeme; + } + processBuffer(); + if (!newMode.returnBegin && !newMode.excludeBegin) { + modeBuffer = lexeme; + } + } + startNewMode(newMode, match); + return newMode.returnBegin ? 0 : lexeme.length; + } + + /** + * Handle the potential end of mode + * + * @param {RegExpMatchArray} match - the current match + */ + function doEndMatch(match) { + const lexeme = match[0]; + const matchPlusRemainder = codeToHighlight.substring(match.index); + + const endMode = endOfMode(top, match, matchPlusRemainder); + if (!endMode) { return NO_MATCH; } + + const origin = top; + if (top.endScope && top.endScope._wrap) { + processBuffer(); + emitKeyword(lexeme, top.endScope._wrap); + } else if (top.endScope && top.endScope._multi) { + processBuffer(); + emitMultiClass(top.endScope, match); + } else if (origin.skip) { + modeBuffer += lexeme; + } else { + if (!(origin.returnEnd || origin.excludeEnd)) { + modeBuffer += lexeme; + } + processBuffer(); + if (origin.excludeEnd) { + modeBuffer = lexeme; + } + } + do { + if (top.scope) { + emitter.closeNode(); + } + if (!top.skip && !top.subLanguage) { + relevance += top.relevance; + } + top = top.parent; + } while (top !== endMode.parent); + if (endMode.starts) { + startNewMode(endMode.starts, match); + } + return origin.returnEnd ? 0 : lexeme.length; + } + + function processContinuations() { + const list = []; + for (let current = top; current !== language; current = current.parent) { + if (current.scope) { + list.unshift(current.scope); + } + } + list.forEach(item => emitter.openNode(item)); + } + + /** @type {{type?: MatchType, index?: number, rule?: Mode}}} */ + let lastMatch = {}; + + /** + * Process an individual match + * + * @param {string} textBeforeMatch - text preceding the match (since the last match) + * @param {EnhancedMatch} [match] - the match itself + */ + function processLexeme(textBeforeMatch, match) { + const lexeme = match && match[0]; + + // add non-matched text to the current mode buffer + modeBuffer += textBeforeMatch; + + if (lexeme == null) { + processBuffer(); + return 0; + } + + // we've found a 0 width match and we're stuck, so we need to advance + // this happens when we have badly behaved rules that have optional matchers to the degree that + // sometimes they can end up matching nothing at all + // Ref: https://github.com/highlightjs/highlight.js/issues/2140 + if (lastMatch.type === "begin" && match.type === "end" && lastMatch.index === match.index && lexeme === "") { + // spit the "skipped" character that our regex choked on back into the output sequence + modeBuffer += codeToHighlight.slice(match.index, match.index + 1); + if (!SAFE_MODE) { + /** @type {AnnotatedError} */ + const err = new Error(`0 width match regex (${languageName})`); + err.languageName = languageName; + err.badRule = lastMatch.rule; + throw err; + } + return 1; + } + lastMatch = match; + + if (match.type === "begin") { + return doBeginMatch(match); + } else if (match.type === "illegal" && !ignoreIllegals) { + // illegal match, we do not continue processing + /** @type {AnnotatedError} */ + const err = new Error('Illegal lexeme "' + lexeme + '" for mode "' + (top.scope || '') + '"'); + err.mode = top; + throw err; + } else if (match.type === "end") { + const processed = doEndMatch(match); + if (processed !== NO_MATCH) { + return processed; + } + } + + // edge case for when illegal matches $ (end of line) which is technically + // a 0 width match but not a begin/end match so it's not caught by the + // first handler (when ignoreIllegals is true) + if (match.type === "illegal" && lexeme === "") { + // advance so we aren't stuck in an infinite loop + return 1; + } + + // infinite loops are BAD, this is a last ditch catch all. if we have a + // decent number of iterations yet our index (cursor position in our + // parsing) still 3x behind our index then something is very wrong + // so we bail + if (iterations > 100000 && iterations > match.index * 3) { + const err = new Error('potential infinite loop, way more iterations than matches'); + throw err; + } + + /* + Why might be find ourselves here? An potential end match that was + triggered but could not be completed. IE, `doEndMatch` returned NO_MATCH. + (this could be because a callback requests the match be ignored, etc) + + This causes no real harm other than stopping a few times too many. + */ + + modeBuffer += lexeme; + return lexeme.length; + } + + const language = getLanguage(languageName); + if (!language) { + error(LANGUAGE_NOT_FOUND.replace("{}", languageName)); + throw new Error('Unknown language: "' + languageName + '"'); + } + + const md = compileLanguage(language); + let result = ''; + /** @type {CompiledMode} */ + let top = continuation || md; + /** @type Record */ + const continuations = {}; // keep continuations for sub-languages + const emitter = new options.__emitter(options); + processContinuations(); + let modeBuffer = ''; + let relevance = 0; + let index = 0; + let iterations = 0; + let resumeScanAtSamePosition = false; + + try { + if (!language.__emitTokens) { + top.matcher.considerAll(); + + for (;;) { + iterations++; + if (resumeScanAtSamePosition) { + // only regexes not matched previously will now be + // considered for a potential match + resumeScanAtSamePosition = false; + } else { + top.matcher.considerAll(); + } + top.matcher.lastIndex = index; + + const match = top.matcher.exec(codeToHighlight); + // console.log("match", match[0], match.rule && match.rule.begin) + + if (!match) break; + + const beforeMatch = codeToHighlight.substring(index, match.index); + const processedCount = processLexeme(beforeMatch, match); + index = match.index + processedCount; + } + processLexeme(codeToHighlight.substring(index)); + } else { + language.__emitTokens(codeToHighlight, emitter); + } + + emitter.finalize(); + result = emitter.toHTML(); + + return { + language: languageName, + value: result, + relevance, + illegal: false, + _emitter: emitter, + _top: top + }; + } catch (err) { + if (err.message && err.message.includes('Illegal')) { + return { + language: languageName, + value: escape(codeToHighlight), + illegal: true, + relevance: 0, + _illegalBy: { + message: err.message, + index, + context: codeToHighlight.slice(index - 100, index + 100), + mode: err.mode, + resultSoFar: result + }, + _emitter: emitter + }; + } else if (SAFE_MODE) { + return { + language: languageName, + value: escape(codeToHighlight), + illegal: false, + relevance: 0, + errorRaised: err, + _emitter: emitter, + _top: top + }; + } else { + throw err; + } + } + } + + /** + * returns a valid highlight result, without actually doing any actual work, + * auto highlight starts with this and it's possible for small snippets that + * auto-detection may not find a better match + * @param {string} code + * @returns {HighlightResult} + */ + function justTextHighlightResult(code) { + const result = { + value: escape(code), + illegal: false, + relevance: 0, + _top: PLAINTEXT_LANGUAGE, + _emitter: new options.__emitter(options) + }; + result._emitter.addText(code); + return result; + } + + /** + Highlighting with language detection. Accepts a string with the code to + highlight. Returns an object with the following properties: + + - language (detected language) + - relevance (int) + - value (an HTML string with highlighting markup) + - secondBest (object with the same structure for second-best heuristically + detected language, may be absent) + + @param {string} code + @param {Array} [languageSubset] + @returns {AutoHighlightResult} + */ + function highlightAuto(code, languageSubset) { + languageSubset = languageSubset || options.languages || Object.keys(languages); + const plaintext = justTextHighlightResult(code); + + const results = languageSubset.filter(getLanguage).filter(autoDetection).map(name => + _highlight(name, code, false) + ); + results.unshift(plaintext); // plaintext is always an option + + const sorted = results.sort((a, b) => { + // sort base on relevance + if (a.relevance !== b.relevance) return b.relevance - a.relevance; + + // always award the tie to the base language + // ie if C++ and Arduino are tied, it's more likely to be C++ + if (a.language && b.language) { + if (getLanguage(a.language).supersetOf === b.language) { + return 1; + } else if (getLanguage(b.language).supersetOf === a.language) { + return -1; + } + } + + // otherwise say they are equal, which has the effect of sorting on + // relevance while preserving the original ordering - which is how ties + // have historically been settled, ie the language that comes first always + // wins in the case of a tie + return 0; + }); + + const [best, secondBest] = sorted; + + /** @type {AutoHighlightResult} */ + const result = best; + result.secondBest = secondBest; + + return result; + } + + /** + * Builds new class name for block given the language name + * + * @param {HTMLElement} element + * @param {string} [currentLang] + * @param {string} [resultLang] + */ + function updateClassName(element, currentLang, resultLang) { + const language = (currentLang && aliases[currentLang]) || resultLang; + + element.classList.add("hljs"); + element.classList.add(`language-${language}`); + } + + /** + * Applies highlighting to a DOM node containing code. + * + * @param {HighlightedHTMLElement} element - the HTML element to highlight + */ + function highlightElement(element) { + /** @type HTMLElement */ + let node = null; + const language = blockLanguage(element); + + if (shouldNotHighlight(language)) return; + + fire("before:highlightElement", + { el: element, language }); + + if (element.dataset.highlighted) { + console.log("Element previously highlighted. To highlight again, first unset `dataset.highlighted`.", element); + return; + } + + // we should be all text, no child nodes (unescaped HTML) - this is possibly + // an HTML injection attack - it's likely too late if this is already in + // production (the code has likely already done its damage by the time + // we're seeing it)... but we yell loudly about this so that hopefully it's + // more likely to be caught in development before making it to production + if (element.children.length > 0) { + if (!options.ignoreUnescapedHTML) { + console.warn("One of your code blocks includes unescaped HTML. This is a potentially serious security risk."); + console.warn("https://github.com/highlightjs/highlight.js/wiki/security"); + console.warn("The element with unescaped HTML:"); + console.warn(element); + } + if (options.throwUnescapedHTML) { + const err = new HTMLInjectionError( + "One of your code blocks includes unescaped HTML.", + element.innerHTML + ); + throw err; + } + } + + node = element; + const text = node.textContent; + const result = language ? highlight(text, { language, ignoreIllegals: true }) : highlightAuto(text); + + element.innerHTML = result.value; + element.dataset.highlighted = "yes"; + updateClassName(element, language, result.language); + element.result = { + language: result.language, + // TODO: remove with version 11.0 + re: result.relevance, + relevance: result.relevance + }; + if (result.secondBest) { + element.secondBest = { + language: result.secondBest.language, + relevance: result.secondBest.relevance + }; + } + + fire("after:highlightElement", { el: element, result, text }); + } + + /** + * Updates highlight.js global options with the passed options + * + * @param {Partial} userOptions + */ + function configure(userOptions) { + options = inherit(options, userOptions); + } + + // TODO: remove v12, deprecated + const initHighlighting = () => { + highlightAll(); + deprecated("10.6.0", "initHighlighting() deprecated. Use highlightAll() now."); + }; + + // TODO: remove v12, deprecated + function initHighlightingOnLoad() { + highlightAll(); + deprecated("10.6.0", "initHighlightingOnLoad() deprecated. Use highlightAll() now."); + } + + let wantsHighlight = false; + + /** + * auto-highlights all pre>code elements on the page + */ + function highlightAll() { + // if we are called too early in the loading process + if (document.readyState === "loading") { + wantsHighlight = true; + return; + } + + const blocks = document.querySelectorAll(options.cssSelector); + blocks.forEach(highlightElement); + } + + function boot() { + // if a highlight was requested before DOM was loaded, do now + if (wantsHighlight) highlightAll(); + } + + // make sure we are in the browser environment + if (typeof window !== 'undefined' && window.addEventListener) { + window.addEventListener('DOMContentLoaded', boot, false); + } + + /** + * Register a language grammar module + * + * @param {string} languageName + * @param {LanguageFn} languageDefinition + */ + function registerLanguage(languageName, languageDefinition) { + let lang = null; + try { + lang = languageDefinition(hljs); + } catch (error$1) { + error("Language definition for '{}' could not be registered.".replace("{}", languageName)); + // hard or soft error + if (!SAFE_MODE) { throw error$1; } else { error(error$1); } + // languages that have serious errors are replaced with essentially a + // "plaintext" stand-in so that the code blocks will still get normal + // css classes applied to them - and one bad language won't break the + // entire highlighter + lang = PLAINTEXT_LANGUAGE; + } + // give it a temporary name if it doesn't have one in the meta-data + if (!lang.name) lang.name = languageName; + languages[languageName] = lang; + lang.rawDefinition = languageDefinition.bind(null, hljs); + + if (lang.aliases) { + registerAliases(lang.aliases, { languageName }); + } + } + + /** + * Remove a language grammar module + * + * @param {string} languageName + */ + function unregisterLanguage(languageName) { + delete languages[languageName]; + for (const alias of Object.keys(aliases)) { + if (aliases[alias] === languageName) { + delete aliases[alias]; + } + } + } + + /** + * @returns {string[]} List of language internal names + */ + function listLanguages() { + return Object.keys(languages); + } + + /** + * @param {string} name - name of the language to retrieve + * @returns {Language | undefined} + */ + function getLanguage(name) { + name = (name || '').toLowerCase(); + return languages[name] || languages[aliases[name]]; + } + + /** + * + * @param {string|string[]} aliasList - single alias or list of aliases + * @param {{languageName: string}} opts + */ + function registerAliases(aliasList, { languageName }) { + if (typeof aliasList === 'string') { + aliasList = [aliasList]; + } + aliasList.forEach(alias => { aliases[alias.toLowerCase()] = languageName; }); + } + + /** + * Determines if a given language has auto-detection enabled + * @param {string} name - name of the language + */ + function autoDetection(name) { + const lang = getLanguage(name); + return lang && !lang.disableAutodetect; + } + + /** + * Upgrades the old highlightBlock plugins to the new + * highlightElement API + * @param {HLJSPlugin} plugin + */ + function upgradePluginAPI(plugin) { + // TODO: remove with v12 + if (plugin["before:highlightBlock"] && !plugin["before:highlightElement"]) { + plugin["before:highlightElement"] = (data) => { + plugin["before:highlightBlock"]( + Object.assign({ block: data.el }, data) + ); + }; + } + if (plugin["after:highlightBlock"] && !plugin["after:highlightElement"]) { + plugin["after:highlightElement"] = (data) => { + plugin["after:highlightBlock"]( + Object.assign({ block: data.el }, data) + ); + }; + } + } + + /** + * @param {HLJSPlugin} plugin + */ + function addPlugin(plugin) { + upgradePluginAPI(plugin); + plugins.push(plugin); + } + + /** + * @param {HLJSPlugin} plugin + */ + function removePlugin(plugin) { + const index = plugins.indexOf(plugin); + if (index !== -1) { + plugins.splice(index, 1); + } + } + + /** + * + * @param {PluginEvent} event + * @param {any} args + */ + function fire(event, args) { + const cb = event; + plugins.forEach(function(plugin) { + if (plugin[cb]) { + plugin[cb](args); + } + }); + } + + /** + * DEPRECATED + * @param {HighlightedHTMLElement} el + */ + function deprecateHighlightBlock(el) { + deprecated("10.7.0", "highlightBlock will be removed entirely in v12.0"); + deprecated("10.7.0", "Please use highlightElement now."); + + return highlightElement(el); + } + + /* Interface definition */ + Object.assign(hljs, { + highlight, + highlightAuto, + highlightAll, + highlightElement, + // TODO: Remove with v12 API + highlightBlock: deprecateHighlightBlock, + configure, + initHighlighting, + initHighlightingOnLoad, + registerLanguage, + unregisterLanguage, + listLanguages, + getLanguage, + registerAliases, + autoDetection, + inherit, + addPlugin, + removePlugin + }); + + hljs.debugMode = function() { SAFE_MODE = false; }; + hljs.safeMode = function() { SAFE_MODE = true; }; + hljs.versionString = version; + + hljs.regex = { + concat: concat, + lookahead: lookahead, + either: either, + optional: optional, + anyNumberOfTimes: anyNumberOfTimes + }; + + for (const key in MODES) { + // @ts-ignore + if (typeof MODES[key] === "object") { + // @ts-ignore + deepFreeze(MODES[key]); + } + } + + // merge all the modes/regexes into our main object + Object.assign(hljs, MODES); + + return hljs; +}; + +// Other names for the variable may break build script +const highlight = HLJS({}); + +// returns a new instance of the highlighter to be used for extensions +// check https://github.com/wooorm/lowlight/issues/47 +highlight.newInstance = () => HLJS({}); + +export { highlight as default }; diff --git a/docs/docs_project/docs_project/static/highlight/es/core.min.js b/docs/docs_project/docs_project/static/highlight/es/core.min.js new file mode 100755 index 0000000..c6d4ae5 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/core.min.js @@ -0,0 +1,307 @@ +/*! + Highlight.js v11.9.0 (git: b7ec4bfafc) + (c) 2006-2023 undefined and other contributors + License: BSD-3-Clause + */ +function e(t){return t instanceof Map?t.clear=t.delete=t.set=()=>{ +throw Error("map is read-only")}:t instanceof Set&&(t.add=t.clear=t.delete=()=>{ +throw Error("set is read-only") +}),Object.freeze(t),Object.getOwnPropertyNames(t).forEach((n=>{ +const i=t[n],s=typeof i;"object"!==s&&"function"!==s||Object.isFrozen(i)||e(i) +})),t}class t{constructor(e){ +void 0===e.data&&(e.data={}),this.data=e.data,this.isMatchIgnored=!1} +ignoreMatch(){this.isMatchIgnored=!0}}function n(e){ +return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'") +}function i(e,...t){const n=Object.create(null);for(const t in e)n[t]=e[t] +;return t.forEach((e=>{for(const t in e)n[t]=e[t]})),n}const s=e=>!!e.scope +;class r{constructor(e,t){ +this.buffer="",this.classPrefix=t.classPrefix,e.walk(this)}addText(e){ +this.buffer+=n(e)}openNode(e){if(!s(e))return;const t=((e,{prefix:t})=>{ +if(e.startsWith("language:"))return e.replace("language:","language-") +;if(e.includes(".")){const n=e.split(".") +;return[`${t}${n.shift()}`,...n.map(((e,t)=>`${e}${"_".repeat(t+1)}`))].join(" ") +}return`${t}${e}`})(e.scope,{prefix:this.classPrefix});this.span(t)} +closeNode(e){s(e)&&(this.buffer+="")}value(){return this.buffer}span(e){ +this.buffer+=``}}const o=(e={})=>{const t={children:[]} +;return Object.assign(t,e),t};class a{constructor(){ +this.rootNode=o(),this.stack=[this.rootNode]}get top(){ +return this.stack[this.stack.length-1]}get root(){return this.rootNode}add(e){ +this.top.children.push(e)}openNode(e){const t=o({scope:e}) +;this.add(t),this.stack.push(t)}closeNode(){ +if(this.stack.length>1)return this.stack.pop()}closeAllNodes(){ +for(;this.closeNode(););}toJSON(){return JSON.stringify(this.rootNode,null,4)} +walk(e){return this.constructor._walk(e,this.rootNode)}static _walk(e,t){ +return"string"==typeof t?e.addText(t):t.children&&(e.openNode(t), +t.children.forEach((t=>this._walk(e,t))),e.closeNode(t)),e}static _collapse(e){ +"string"!=typeof e&&e.children&&(e.children.every((e=>"string"==typeof e))?e.children=[e.children.join("")]:e.children.forEach((e=>{ +a._collapse(e)})))}}class c extends a{constructor(e){super(),this.options=e} +addText(e){""!==e&&this.add(e)}startScope(e){this.openNode(e)}endScope(){ +this.closeNode()}__addSublanguage(e,t){const n=e.root +;t&&(n.scope="language:"+t),this.add(n)}toHTML(){ +return new r(this,this.options).value()}finalize(){ +return this.closeAllNodes(),!0}}function l(e){ +return e?"string"==typeof e?e:e.source:null}function g(e){return h("(?=",e,")")} +function u(e){return h("(?:",e,")*")}function d(e){return h("(?:",e,")?")} +function h(...e){return e.map((e=>l(e))).join("")}function f(...e){const t=(e=>{ +const t=e[e.length-1] +;return"object"==typeof t&&t.constructor===Object?(e.splice(e.length-1,1),t):{} +})(e);return"("+(t.capture?"":"?:")+e.map((e=>l(e))).join("|")+")"} +function p(e){return RegExp(e.toString()+"|").exec("").length-1} +const b=/\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./ +;function m(e,{joinWith:t}){let n=0;return e.map((e=>{n+=1;const t=n +;let i=l(e),s="";for(;i.length>0;){const e=b.exec(i);if(!e){s+=i;break} +s+=i.substring(0,e.index), +i=i.substring(e.index+e[0].length),"\\"===e[0][0]&&e[1]?s+="\\"+(Number(e[1])+t):(s+=e[0], +"("===e[0]&&n++)}return s})).map((e=>`(${e})`)).join(t)} +const E="[a-zA-Z]\\w*",x="[a-zA-Z_]\\w*",w="\\b\\d+(\\.\\d+)?",y="(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",_="\\b(0b[01]+)",O={ +begin:"\\\\[\\s\\S]",relevance:0},k={scope:"string",begin:"'",end:"'", +illegal:"\\n",contains:[O]},v={scope:"string",begin:'"',end:'"',illegal:"\\n", +contains:[O]},N=(e,t,n={})=>{const s=i({scope:"comment",begin:e,end:t, +contains:[]},n);s.contains.push({scope:"doctag", +begin:"[ ]*(?=(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):)", +end:/(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):/,excludeBegin:!0,relevance:0}) +;const r=f("I","a","is","so","us","to","at","if","in","it","on",/[A-Za-z]+['](d|ve|re|ll|t|s|n)/,/[A-Za-z]+[-][a-z]+/,/[A-Za-z][a-z]{2,}/) +;return s.contains.push({begin:h(/[ ]+/,"(",r,/[.]?[:]?([.][ ]|[ ])/,"){3}")}),s +},S=N("//","$"),M=N("/\\*","\\*/"),R=N("#","$");var A=Object.freeze({ +__proto__:null,APOS_STRING_MODE:k,BACKSLASH_ESCAPE:O,BINARY_NUMBER_MODE:{ +scope:"number",begin:_,relevance:0},BINARY_NUMBER_RE:_,COMMENT:N, +C_BLOCK_COMMENT_MODE:M,C_LINE_COMMENT_MODE:S,C_NUMBER_MODE:{scope:"number", +begin:y,relevance:0},C_NUMBER_RE:y,END_SAME_AS_BEGIN:e=>Object.assign(e,{ +"on:begin":(e,t)=>{t.data._beginMatch=e[1]},"on:end":(e,t)=>{ +t.data._beginMatch!==e[1]&&t.ignoreMatch()}}),HASH_COMMENT_MODE:R,IDENT_RE:E, +MATCH_NOTHING_RE:/\b\B/,METHOD_GUARD:{begin:"\\.\\s*"+x,relevance:0}, +NUMBER_MODE:{scope:"number",begin:w,relevance:0},NUMBER_RE:w, +PHRASAL_WORDS_MODE:{ +begin:/\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/ +},QUOTE_STRING_MODE:v,REGEXP_MODE:{scope:"regexp",begin:/\/(?=[^/\n]*\/)/, +end:/\/[gimuy]*/,contains:[O,{begin:/\[/,end:/\]/,relevance:0,contains:[O]}]}, +RE_STARTERS_RE:"!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~", +SHEBANG:(e={})=>{const t=/^#![ ]*\// +;return e.binary&&(e.begin=h(t,/.*\b/,e.binary,/\b.*/)),i({scope:"meta",begin:t, +end:/$/,relevance:0,"on:begin":(e,t)=>{0!==e.index&&t.ignoreMatch()}},e)}, +TITLE_MODE:{scope:"title",begin:E,relevance:0},UNDERSCORE_IDENT_RE:x, +UNDERSCORE_TITLE_MODE:{scope:"title",begin:x,relevance:0}});function j(e,t){ +"."===e.input[e.index-1]&&t.ignoreMatch()}function I(e,t){ +void 0!==e.className&&(e.scope=e.className,delete e.className)}function T(e,t){ +t&&e.beginKeywords&&(e.begin="\\b("+e.beginKeywords.split(" ").join("|")+")(?!\\.)(?=\\b|\\s)", +e.__beforeBegin=j,e.keywords=e.keywords||e.beginKeywords,delete e.beginKeywords, +void 0===e.relevance&&(e.relevance=0))}function L(e,t){ +Array.isArray(e.illegal)&&(e.illegal=f(...e.illegal))}function B(e,t){ +if(e.match){ +if(e.begin||e.end)throw Error("begin & end are not supported with match") +;e.begin=e.match,delete e.match}}function P(e,t){ +void 0===e.relevance&&(e.relevance=1)}const D=(e,t)=>{if(!e.beforeMatch)return +;if(e.starts)throw Error("beforeMatch cannot be used with starts") +;const n=Object.assign({},e);Object.keys(e).forEach((t=>{delete e[t] +})),e.keywords=n.keywords,e.begin=h(n.beforeMatch,g(n.begin)),e.starts={ +relevance:0,contains:[Object.assign(n,{endsParent:!0})] +},e.relevance=0,delete n.beforeMatch +},H=["of","and","for","in","not","or","if","then","parent","list","value"],C="keyword" +;function $(e,t,n=C){const i=Object.create(null) +;return"string"==typeof e?s(n,e.split(" ")):Array.isArray(e)?s(n,e):Object.keys(e).forEach((n=>{ +Object.assign(i,$(e[n],t,n))})),i;function s(e,n){ +t&&(n=n.map((e=>e.toLowerCase()))),n.forEach((t=>{const n=t.split("|") +;i[n[0]]=[e,U(n[0],n[1])]}))}}function U(e,t){ +return t?Number(t):(e=>H.includes(e.toLowerCase()))(e)?0:1}const z={},W=e=>{ +console.error(e)},X=(e,...t)=>{console.log("WARN: "+e,...t)},G=(e,t)=>{ +z[`${e}/${t}`]||(console.log(`Deprecated as of ${e}. ${t}`),z[`${e}/${t}`]=!0) +},K=Error();function F(e,t,{key:n}){let i=0;const s=e[n],r={},o={} +;for(let e=1;e<=t.length;e++)o[e+i]=s[e],r[e+i]=!0,i+=p(t[e-1]) +;e[n]=o,e[n]._emit=r,e[n]._multi=!0}function Z(e){(e=>{ +e.scope&&"object"==typeof e.scope&&null!==e.scope&&(e.beginScope=e.scope, +delete e.scope)})(e),"string"==typeof e.beginScope&&(e.beginScope={ +_wrap:e.beginScope}),"string"==typeof e.endScope&&(e.endScope={_wrap:e.endScope +}),(e=>{if(Array.isArray(e.begin)){ +if(e.skip||e.excludeBegin||e.returnBegin)throw W("skip, excludeBegin, returnBegin not compatible with beginScope: {}"), +K +;if("object"!=typeof e.beginScope||null===e.beginScope)throw W("beginScope must be object"), +K;F(e,e.begin,{key:"beginScope"}),e.begin=m(e.begin,{joinWith:""})}})(e),(e=>{ +if(Array.isArray(e.end)){ +if(e.skip||e.excludeEnd||e.returnEnd)throw W("skip, excludeEnd, returnEnd not compatible with endScope: {}"), +K +;if("object"!=typeof e.endScope||null===e.endScope)throw W("endScope must be object"), +K;F(e,e.end,{key:"endScope"}),e.end=m(e.end,{joinWith:""})}})(e)}function V(e){ +function t(t,n){ +return RegExp(l(t),"m"+(e.case_insensitive?"i":"")+(e.unicodeRegex?"u":"")+(n?"g":"")) +}class n{constructor(){ +this.matchIndexes={},this.regexes=[],this.matchAt=1,this.position=0} +addRule(e,t){ +t.position=this.position++,this.matchIndexes[this.matchAt]=t,this.regexes.push([t,e]), +this.matchAt+=p(e)+1}compile(){0===this.regexes.length&&(this.exec=()=>null) +;const e=this.regexes.map((e=>e[1]));this.matcherRe=t(m(e,{joinWith:"|" +}),!0),this.lastIndex=0}exec(e){this.matcherRe.lastIndex=this.lastIndex +;const t=this.matcherRe.exec(e);if(!t)return null +;const n=t.findIndex(((e,t)=>t>0&&void 0!==e)),i=this.matchIndexes[n] +;return t.splice(0,n),Object.assign(t,i)}}class s{constructor(){ +this.rules=[],this.multiRegexes=[], +this.count=0,this.lastIndex=0,this.regexIndex=0}getMatcher(e){ +if(this.multiRegexes[e])return this.multiRegexes[e];const t=new n +;return this.rules.slice(e).forEach((([e,n])=>t.addRule(e,n))), +t.compile(),this.multiRegexes[e]=t,t}resumingScanAtSamePosition(){ +return 0!==this.regexIndex}considerAll(){this.regexIndex=0}addRule(e,t){ +this.rules.push([e,t]),"begin"===t.type&&this.count++}exec(e){ +const t=this.getMatcher(this.regexIndex);t.lastIndex=this.lastIndex +;let n=t.exec(e) +;if(this.resumingScanAtSamePosition())if(n&&n.index===this.lastIndex);else{ +const t=this.getMatcher(0);t.lastIndex=this.lastIndex+1,n=t.exec(e)} +return n&&(this.regexIndex+=n.position+1, +this.regexIndex===this.count&&this.considerAll()),n}} +if(e.compilerExtensions||(e.compilerExtensions=[]), +e.contains&&e.contains.includes("self"))throw Error("ERR: contains `self` is not supported at the top-level of a language. See documentation.") +;return e.classNameAliases=i(e.classNameAliases||{}),function n(r,o){const a=r +;if(r.isCompiled)return a +;[I,B,Z,D].forEach((e=>e(r,o))),e.compilerExtensions.forEach((e=>e(r,o))), +r.__beforeBegin=null,[T,L,P].forEach((e=>e(r,o))),r.isCompiled=!0;let c=null +;return"object"==typeof r.keywords&&r.keywords.$pattern&&(r.keywords=Object.assign({},r.keywords), +c=r.keywords.$pattern, +delete r.keywords.$pattern),c=c||/\w+/,r.keywords&&(r.keywords=$(r.keywords,e.case_insensitive)), +a.keywordPatternRe=t(c,!0), +o&&(r.begin||(r.begin=/\B|\b/),a.beginRe=t(a.begin),r.end||r.endsWithParent||(r.end=/\B|\b/), +r.end&&(a.endRe=t(a.end)), +a.terminatorEnd=l(a.end)||"",r.endsWithParent&&o.terminatorEnd&&(a.terminatorEnd+=(r.end?"|":"")+o.terminatorEnd)), +r.illegal&&(a.illegalRe=t(r.illegal)), +r.contains||(r.contains=[]),r.contains=[].concat(...r.contains.map((e=>(e=>(e.variants&&!e.cachedVariants&&(e.cachedVariants=e.variants.map((t=>i(e,{ +variants:null},t)))),e.cachedVariants?e.cachedVariants:q(e)?i(e,{ +starts:e.starts?i(e.starts):null +}):Object.isFrozen(e)?i(e):e))("self"===e?r:e)))),r.contains.forEach((e=>{n(e,a) +})),r.starts&&n(r.starts,o),a.matcher=(e=>{const t=new s +;return e.contains.forEach((e=>t.addRule(e.begin,{rule:e,type:"begin" +}))),e.terminatorEnd&&t.addRule(e.terminatorEnd,{type:"end" +}),e.illegal&&t.addRule(e.illegal,{type:"illegal"}),t})(a),a}(e)}function q(e){ +return!!e&&(e.endsWithParent||q(e.starts))}class J extends Error{ +constructor(e,t){super(e),this.name="HTMLInjectionError",this.html=t}} +const Y=n,Q=i,ee=Symbol("nomatch"),te=n=>{ +const i=Object.create(null),s=Object.create(null),r=[];let o=!0 +;const a="Could not find the language '{}', did you forget to load/include a language module?",l={ +disableAutodetect:!0,name:"Plain text",contains:[]};let p={ +ignoreUnescapedHTML:!1,throwUnescapedHTML:!1,noHighlightRe:/^(no-?highlight)$/i, +languageDetectRe:/\blang(?:uage)?-([\w-]+)\b/i,classPrefix:"hljs-", +cssSelector:"pre code",languages:null,__emitter:c};function b(e){ +return p.noHighlightRe.test(e)}function m(e,t,n){let i="",s="" +;"object"==typeof t?(i=e, +n=t.ignoreIllegals,s=t.language):(G("10.7.0","highlight(lang, code, ...args) has been deprecated."), +G("10.7.0","Please use highlight(code, options) instead.\nhttps://github.com/highlightjs/highlight.js/issues/2277"), +s=e,i=t),void 0===n&&(n=!0);const r={code:i,language:s};N("before:highlight",r) +;const o=r.result?r.result:E(r.language,r.code,n) +;return o.code=r.code,N("after:highlight",o),o}function E(e,n,s,r){ +const c=Object.create(null);function l(){if(!N.keywords)return void M.addText(R) +;let e=0;N.keywordPatternRe.lastIndex=0;let t=N.keywordPatternRe.exec(R),n="" +;for(;t;){n+=R.substring(e,t.index) +;const s=_.case_insensitive?t[0].toLowerCase():t[0],r=(i=s,N.keywords[i]);if(r){ +const[e,i]=r +;if(M.addText(n),n="",c[s]=(c[s]||0)+1,c[s]<=7&&(A+=i),e.startsWith("_"))n+=t[0];else{ +const n=_.classNameAliases[e]||e;u(t[0],n)}}else n+=t[0] +;e=N.keywordPatternRe.lastIndex,t=N.keywordPatternRe.exec(R)}var i +;n+=R.substring(e),M.addText(n)}function g(){null!=N.subLanguage?(()=>{ +if(""===R)return;let e=null;if("string"==typeof N.subLanguage){ +if(!i[N.subLanguage])return void M.addText(R) +;e=E(N.subLanguage,R,!0,S[N.subLanguage]),S[N.subLanguage]=e._top +}else e=x(R,N.subLanguage.length?N.subLanguage:null) +;N.relevance>0&&(A+=e.relevance),M.__addSublanguage(e._emitter,e.language) +})():l(),R=""}function u(e,t){ +""!==e&&(M.startScope(t),M.addText(e),M.endScope())}function d(e,t){let n=1 +;const i=t.length-1;for(;n<=i;){if(!e._emit[n]){n++;continue} +const i=_.classNameAliases[e[n]]||e[n],s=t[n];i?u(s,i):(R=s,l(),R=""),n++}} +function h(e,t){ +return e.scope&&"string"==typeof e.scope&&M.openNode(_.classNameAliases[e.scope]||e.scope), +e.beginScope&&(e.beginScope._wrap?(u(R,_.classNameAliases[e.beginScope._wrap]||e.beginScope._wrap), +R=""):e.beginScope._multi&&(d(e.beginScope,t),R="")),N=Object.create(e,{parent:{ +value:N}}),N}function f(e,n,i){let s=((e,t)=>{const n=e&&e.exec(t) +;return n&&0===n.index})(e.endRe,i);if(s){if(e["on:end"]){const i=new t(e) +;e["on:end"](n,i),i.isMatchIgnored&&(s=!1)}if(s){ +for(;e.endsParent&&e.parent;)e=e.parent;return e}} +if(e.endsWithParent)return f(e.parent,n,i)}function b(e){ +return 0===N.matcher.regexIndex?(R+=e[0],1):(T=!0,0)}function m(e){ +const t=e[0],i=n.substring(e.index),s=f(N,e,i);if(!s)return ee;const r=N +;N.endScope&&N.endScope._wrap?(g(), +u(t,N.endScope._wrap)):N.endScope&&N.endScope._multi?(g(), +d(N.endScope,e)):r.skip?R+=t:(r.returnEnd||r.excludeEnd||(R+=t), +g(),r.excludeEnd&&(R=t));do{ +N.scope&&M.closeNode(),N.skip||N.subLanguage||(A+=N.relevance),N=N.parent +}while(N!==s.parent);return s.starts&&h(s.starts,e),r.returnEnd?0:t.length} +let w={};function y(i,r){const a=r&&r[0];if(R+=i,null==a)return g(),0 +;if("begin"===w.type&&"end"===r.type&&w.index===r.index&&""===a){ +if(R+=n.slice(r.index,r.index+1),!o){const t=Error(`0 width match regex (${e})`) +;throw t.languageName=e,t.badRule=w.rule,t}return 1} +if(w=r,"begin"===r.type)return(e=>{ +const n=e[0],i=e.rule,s=new t(i),r=[i.__beforeBegin,i["on:begin"]] +;for(const t of r)if(t&&(t(e,s),s.isMatchIgnored))return b(n) +;return i.skip?R+=n:(i.excludeBegin&&(R+=n), +g(),i.returnBegin||i.excludeBegin||(R=n)),h(i,e),i.returnBegin?0:n.length})(r) +;if("illegal"===r.type&&!s){ +const e=Error('Illegal lexeme "'+a+'" for mode "'+(N.scope||"")+'"') +;throw e.mode=N,e}if("end"===r.type){const e=m(r);if(e!==ee)return e} +if("illegal"===r.type&&""===a)return 1 +;if(I>1e5&&I>3*r.index)throw Error("potential infinite loop, way more iterations than matches") +;return R+=a,a.length}const _=O(e) +;if(!_)throw W(a.replace("{}",e)),Error('Unknown language: "'+e+'"') +;const k=V(_);let v="",N=r||k;const S={},M=new p.__emitter(p);(()=>{const e=[] +;for(let t=N;t!==_;t=t.parent)t.scope&&e.unshift(t.scope) +;e.forEach((e=>M.openNode(e)))})();let R="",A=0,j=0,I=0,T=!1;try{ +if(_.__emitTokens)_.__emitTokens(n,M);else{for(N.matcher.considerAll();;){ +I++,T?T=!1:N.matcher.considerAll(),N.matcher.lastIndex=j +;const e=N.matcher.exec(n);if(!e)break;const t=y(n.substring(j,e.index),e) +;j=e.index+t}y(n.substring(j))}return M.finalize(),v=M.toHTML(),{language:e, +value:v,relevance:A,illegal:!1,_emitter:M,_top:N}}catch(t){ +if(t.message&&t.message.includes("Illegal"))return{language:e,value:Y(n), +illegal:!0,relevance:0,_illegalBy:{message:t.message,index:j, +context:n.slice(j-100,j+100),mode:t.mode,resultSoFar:v},_emitter:M};if(o)return{ +language:e,value:Y(n),illegal:!1,relevance:0,errorRaised:t,_emitter:M,_top:N} +;throw t}}function x(e,t){t=t||p.languages||Object.keys(i);const n=(e=>{ +const t={value:Y(e),illegal:!1,relevance:0,_top:l,_emitter:new p.__emitter(p)} +;return t._emitter.addText(e),t})(e),s=t.filter(O).filter(v).map((t=>E(t,e,!1))) +;s.unshift(n);const r=s.sort(((e,t)=>{ +if(e.relevance!==t.relevance)return t.relevance-e.relevance +;if(e.language&&t.language){if(O(e.language).supersetOf===t.language)return 1 +;if(O(t.language).supersetOf===e.language)return-1}return 0})),[o,a]=r,c=o +;return c.secondBest=a,c}function w(e){let t=null;const n=(e=>{ +let t=e.className+" ";t+=e.parentNode?e.parentNode.className:"" +;const n=p.languageDetectRe.exec(t);if(n){const t=O(n[1]) +;return t||(X(a.replace("{}",n[1])), +X("Falling back to no-highlight mode for this block.",e)),t?n[1]:"no-highlight"} +return t.split(/\s+/).find((e=>b(e)||O(e)))})(e);if(b(n))return +;if(N("before:highlightElement",{el:e,language:n +}),e.dataset.highlighted)return void console.log("Element previously highlighted. To highlight again, first unset `dataset.highlighted`.",e) +;if(e.children.length>0&&(p.ignoreUnescapedHTML||(console.warn("One of your code blocks includes unescaped HTML. This is a potentially serious security risk."), +console.warn("https://github.com/highlightjs/highlight.js/wiki/security"), +console.warn("The element with unescaped HTML:"), +console.warn(e)),p.throwUnescapedHTML))throw new J("One of your code blocks includes unescaped HTML.",e.innerHTML) +;t=e;const i=t.textContent,r=n?m(i,{language:n,ignoreIllegals:!0}):x(i) +;e.innerHTML=r.value,e.dataset.highlighted="yes",((e,t,n)=>{const i=t&&s[t]||n +;e.classList.add("hljs"),e.classList.add("language-"+i) +})(e,n,r.language),e.result={language:r.language,re:r.relevance, +relevance:r.relevance},r.secondBest&&(e.secondBest={ +language:r.secondBest.language,relevance:r.secondBest.relevance +}),N("after:highlightElement",{el:e,result:r,text:i})}let y=!1;function _(){ +"loading"!==document.readyState?document.querySelectorAll(p.cssSelector).forEach(w):y=!0 +}function O(e){return e=(e||"").toLowerCase(),i[e]||i[s[e]]} +function k(e,{languageName:t}){"string"==typeof e&&(e=[e]),e.forEach((e=>{ +s[e.toLowerCase()]=t}))}function v(e){const t=O(e) +;return t&&!t.disableAutodetect}function N(e,t){const n=e;r.forEach((e=>{ +e[n]&&e[n](t)}))} +"undefined"!=typeof window&&window.addEventListener&&window.addEventListener("DOMContentLoaded",(()=>{ +y&&_()}),!1),Object.assign(n,{highlight:m,highlightAuto:x,highlightAll:_, +highlightElement:w, +highlightBlock:e=>(G("10.7.0","highlightBlock will be removed entirely in v12.0"), +G("10.7.0","Please use highlightElement now."),w(e)),configure:e=>{p=Q(p,e)}, +initHighlighting:()=>{ +_(),G("10.6.0","initHighlighting() deprecated. Use highlightAll() now.")}, +initHighlightingOnLoad:()=>{ +_(),G("10.6.0","initHighlightingOnLoad() deprecated. Use highlightAll() now.") +},registerLanguage:(e,t)=>{let s=null;try{s=t(n)}catch(t){ +if(W("Language definition for '{}' could not be registered.".replace("{}",e)), +!o)throw t;W(t),s=l} +s.name||(s.name=e),i[e]=s,s.rawDefinition=t.bind(null,n),s.aliases&&k(s.aliases,{ +languageName:e})},unregisterLanguage:e=>{delete i[e] +;for(const t of Object.keys(s))s[t]===e&&delete s[t]}, +listLanguages:()=>Object.keys(i),getLanguage:O,registerAliases:k, +autoDetection:v,inherit:Q,addPlugin:e=>{(e=>{ +e["before:highlightBlock"]&&!e["before:highlightElement"]&&(e["before:highlightElement"]=t=>{ +e["before:highlightBlock"](Object.assign({block:t.el},t)) +}),e["after:highlightBlock"]&&!e["after:highlightElement"]&&(e["after:highlightElement"]=t=>{ +e["after:highlightBlock"](Object.assign({block:t.el},t))})})(e),r.push(e)}, +removePlugin:e=>{const t=r.indexOf(e);-1!==t&&r.splice(t,1)}}),n.debugMode=()=>{ +o=!1},n.safeMode=()=>{o=!0},n.versionString="11.9.0",n.regex={concat:h, +lookahead:g,either:f,optional:d,anyNumberOfTimes:u} +;for(const t in A)"object"==typeof A[t]&&e(A[t]);return Object.assign(n,A),n +},ne=te({});ne.newInstance=()=>te({});export{ne as default}; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/highlight.js b/docs/docs_project/docs_project/static/highlight/es/highlight.js new file mode 100755 index 0000000..7294b81 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/highlight.js @@ -0,0 +1,2600 @@ +/*! + Highlight.js v11.9.0 (git: b7ec4bfafc) + (c) 2006-2023 undefined and other contributors + License: BSD-3-Clause + */ +/* eslint-disable no-multi-assign */ + +function deepFreeze(obj) { + if (obj instanceof Map) { + obj.clear = + obj.delete = + obj.set = + function () { + throw new Error('map is read-only'); + }; + } else if (obj instanceof Set) { + obj.add = + obj.clear = + obj.delete = + function () { + throw new Error('set is read-only'); + }; + } + + // Freeze self + Object.freeze(obj); + + Object.getOwnPropertyNames(obj).forEach((name) => { + const prop = obj[name]; + const type = typeof prop; + + // Freeze prop if it is an object or function and also not already frozen + if ((type === 'object' || type === 'function') && !Object.isFrozen(prop)) { + deepFreeze(prop); + } + }); + + return obj; +} + +/** @typedef {import('highlight.js').CallbackResponse} CallbackResponse */ +/** @typedef {import('highlight.js').CompiledMode} CompiledMode */ +/** @implements CallbackResponse */ + +class Response { + /** + * @param {CompiledMode} mode + */ + constructor(mode) { + // eslint-disable-next-line no-undefined + if (mode.data === undefined) mode.data = {}; + + this.data = mode.data; + this.isMatchIgnored = false; + } + + ignoreMatch() { + this.isMatchIgnored = true; + } +} + +/** + * @param {string} value + * @returns {string} + */ +function escapeHTML(value) { + return value + .replace(/&/g, '&') + .replace(//g, '>') + .replace(/"/g, '"') + .replace(/'/g, '''); +} + +/** + * performs a shallow merge of multiple objects into one + * + * @template T + * @param {T} original + * @param {Record[]} objects + * @returns {T} a single new object + */ +function inherit$1(original, ...objects) { + /** @type Record */ + const result = Object.create(null); + + for (const key in original) { + result[key] = original[key]; + } + objects.forEach(function(obj) { + for (const key in obj) { + result[key] = obj[key]; + } + }); + return /** @type {T} */ (result); +} + +/** + * @typedef {object} Renderer + * @property {(text: string) => void} addText + * @property {(node: Node) => void} openNode + * @property {(node: Node) => void} closeNode + * @property {() => string} value + */ + +/** @typedef {{scope?: string, language?: string, sublanguage?: boolean}} Node */ +/** @typedef {{walk: (r: Renderer) => void}} Tree */ +/** */ + +const SPAN_CLOSE = ''; + +/** + * Determines if a node needs to be wrapped in + * + * @param {Node} node */ +const emitsWrappingTags = (node) => { + // rarely we can have a sublanguage where language is undefined + // TODO: track down why + return !!node.scope; +}; + +/** + * + * @param {string} name + * @param {{prefix:string}} options + */ +const scopeToCSSClass = (name, { prefix }) => { + // sub-language + if (name.startsWith("language:")) { + return name.replace("language:", "language-"); + } + // tiered scope: comment.line + if (name.includes(".")) { + const pieces = name.split("."); + return [ + `${prefix}${pieces.shift()}`, + ...(pieces.map((x, i) => `${x}${"_".repeat(i + 1)}`)) + ].join(" "); + } + // simple scope + return `${prefix}${name}`; +}; + +/** @type {Renderer} */ +class HTMLRenderer { + /** + * Creates a new HTMLRenderer + * + * @param {Tree} parseTree - the parse tree (must support `walk` API) + * @param {{classPrefix: string}} options + */ + constructor(parseTree, options) { + this.buffer = ""; + this.classPrefix = options.classPrefix; + parseTree.walk(this); + } + + /** + * Adds texts to the output stream + * + * @param {string} text */ + addText(text) { + this.buffer += escapeHTML(text); + } + + /** + * Adds a node open to the output stream (if needed) + * + * @param {Node} node */ + openNode(node) { + if (!emitsWrappingTags(node)) return; + + const className = scopeToCSSClass(node.scope, + { prefix: this.classPrefix }); + this.span(className); + } + + /** + * Adds a node close to the output stream (if needed) + * + * @param {Node} node */ + closeNode(node) { + if (!emitsWrappingTags(node)) return; + + this.buffer += SPAN_CLOSE; + } + + /** + * returns the accumulated buffer + */ + value() { + return this.buffer; + } + + // helpers + + /** + * Builds a span element + * + * @param {string} className */ + span(className) { + this.buffer += ``; + } +} + +/** @typedef {{scope?: string, language?: string, children: Node[]} | string} Node */ +/** @typedef {{scope?: string, language?: string, children: Node[]} } DataNode */ +/** @typedef {import('highlight.js').Emitter} Emitter */ +/** */ + +/** @returns {DataNode} */ +const newNode = (opts = {}) => { + /** @type DataNode */ + const result = { children: [] }; + Object.assign(result, opts); + return result; +}; + +class TokenTree { + constructor() { + /** @type DataNode */ + this.rootNode = newNode(); + this.stack = [this.rootNode]; + } + + get top() { + return this.stack[this.stack.length - 1]; + } + + get root() { return this.rootNode; } + + /** @param {Node} node */ + add(node) { + this.top.children.push(node); + } + + /** @param {string} scope */ + openNode(scope) { + /** @type Node */ + const node = newNode({ scope }); + this.add(node); + this.stack.push(node); + } + + closeNode() { + if (this.stack.length > 1) { + return this.stack.pop(); + } + // eslint-disable-next-line no-undefined + return undefined; + } + + closeAllNodes() { + while (this.closeNode()); + } + + toJSON() { + return JSON.stringify(this.rootNode, null, 4); + } + + /** + * @typedef { import("./html_renderer").Renderer } Renderer + * @param {Renderer} builder + */ + walk(builder) { + // this does not + return this.constructor._walk(builder, this.rootNode); + // this works + // return TokenTree._walk(builder, this.rootNode); + } + + /** + * @param {Renderer} builder + * @param {Node} node + */ + static _walk(builder, node) { + if (typeof node === "string") { + builder.addText(node); + } else if (node.children) { + builder.openNode(node); + node.children.forEach((child) => this._walk(builder, child)); + builder.closeNode(node); + } + return builder; + } + + /** + * @param {Node} node + */ + static _collapse(node) { + if (typeof node === "string") return; + if (!node.children) return; + + if (node.children.every(el => typeof el === "string")) { + // node.text = node.children.join(""); + // delete node.children; + node.children = [node.children.join("")]; + } else { + node.children.forEach((child) => { + TokenTree._collapse(child); + }); + } + } +} + +/** + Currently this is all private API, but this is the minimal API necessary + that an Emitter must implement to fully support the parser. + + Minimal interface: + + - addText(text) + - __addSublanguage(emitter, subLanguageName) + - startScope(scope) + - endScope() + - finalize() + - toHTML() + +*/ + +/** + * @implements {Emitter} + */ +class TokenTreeEmitter extends TokenTree { + /** + * @param {*} options + */ + constructor(options) { + super(); + this.options = options; + } + + /** + * @param {string} text + */ + addText(text) { + if (text === "") { return; } + + this.add(text); + } + + /** @param {string} scope */ + startScope(scope) { + this.openNode(scope); + } + + endScope() { + this.closeNode(); + } + + /** + * @param {Emitter & {root: DataNode}} emitter + * @param {string} name + */ + __addSublanguage(emitter, name) { + /** @type DataNode */ + const node = emitter.root; + if (name) node.scope = `language:${name}`; + + this.add(node); + } + + toHTML() { + const renderer = new HTMLRenderer(this, this.options); + return renderer.value(); + } + + finalize() { + this.closeAllNodes(); + return true; + } +} + +/** + * @param {string} value + * @returns {RegExp} + * */ + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function source(re) { + if (!re) return null; + if (typeof re === "string") return re; + + return re.source; +} + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function lookahead(re) { + return concat('(?=', re, ')'); +} + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function anyNumberOfTimes(re) { + return concat('(?:', re, ')*'); +} + +/** + * @param {RegExp | string } re + * @returns {string} + */ +function optional(re) { + return concat('(?:', re, ')?'); +} + +/** + * @param {...(RegExp | string) } args + * @returns {string} + */ +function concat(...args) { + const joined = args.map((x) => source(x)).join(""); + return joined; +} + +/** + * @param { Array } args + * @returns {object} + */ +function stripOptionsFromArgs(args) { + const opts = args[args.length - 1]; + + if (typeof opts === 'object' && opts.constructor === Object) { + args.splice(args.length - 1, 1); + return opts; + } else { + return {}; + } +} + +/** @typedef { {capture?: boolean} } RegexEitherOptions */ + +/** + * Any of the passed expresssions may match + * + * Creates a huge this | this | that | that match + * @param {(RegExp | string)[] | [...(RegExp | string)[], RegexEitherOptions]} args + * @returns {string} + */ +function either(...args) { + /** @type { object & {capture?: boolean} } */ + const opts = stripOptionsFromArgs(args); + const joined = '(' + + (opts.capture ? "" : "?:") + + args.map((x) => source(x)).join("|") + ")"; + return joined; +} + +/** + * @param {RegExp | string} re + * @returns {number} + */ +function countMatchGroups(re) { + return (new RegExp(re.toString() + '|')).exec('').length - 1; +} + +/** + * Does lexeme start with a regular expression match at the beginning + * @param {RegExp} re + * @param {string} lexeme + */ +function startsWith(re, lexeme) { + const match = re && re.exec(lexeme); + return match && match.index === 0; +} + +// BACKREF_RE matches an open parenthesis or backreference. To avoid +// an incorrect parse, it additionally matches the following: +// - [...] elements, where the meaning of parentheses and escapes change +// - other escape sequences, so we do not misparse escape sequences as +// interesting elements +// - non-matching or lookahead parentheses, which do not capture. These +// follow the '(' with a '?'. +const BACKREF_RE = /\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./; + +// **INTERNAL** Not intended for outside usage +// join logically computes regexps.join(separator), but fixes the +// backreferences so they continue to match. +// it also places each individual regular expression into it's own +// match group, keeping track of the sequencing of those match groups +// is currently an exercise for the caller. :-) +/** + * @param {(string | RegExp)[]} regexps + * @param {{joinWith: string}} opts + * @returns {string} + */ +function _rewriteBackreferences(regexps, { joinWith }) { + let numCaptures = 0; + + return regexps.map((regex) => { + numCaptures += 1; + const offset = numCaptures; + let re = source(regex); + let out = ''; + + while (re.length > 0) { + const match = BACKREF_RE.exec(re); + if (!match) { + out += re; + break; + } + out += re.substring(0, match.index); + re = re.substring(match.index + match[0].length); + if (match[0][0] === '\\' && match[1]) { + // Adjust the backreference. + out += '\\' + String(Number(match[1]) + offset); + } else { + out += match[0]; + if (match[0] === '(') { + numCaptures++; + } + } + } + return out; + }).map(re => `(${re})`).join(joinWith); +} + +/** @typedef {import('highlight.js').Mode} Mode */ +/** @typedef {import('highlight.js').ModeCallback} ModeCallback */ + +// Common regexps +const MATCH_NOTHING_RE = /\b\B/; +const IDENT_RE = '[a-zA-Z]\\w*'; +const UNDERSCORE_IDENT_RE = '[a-zA-Z_]\\w*'; +const NUMBER_RE = '\\b\\d+(\\.\\d+)?'; +const C_NUMBER_RE = '(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)'; // 0x..., 0..., decimal, float +const BINARY_NUMBER_RE = '\\b(0b[01]+)'; // 0b... +const RE_STARTERS_RE = '!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~'; + +/** +* @param { Partial & {binary?: string | RegExp} } opts +*/ +const SHEBANG = (opts = {}) => { + const beginShebang = /^#![ ]*\//; + if (opts.binary) { + opts.begin = concat( + beginShebang, + /.*\b/, + opts.binary, + /\b.*/); + } + return inherit$1({ + scope: 'meta', + begin: beginShebang, + end: /$/, + relevance: 0, + /** @type {ModeCallback} */ + "on:begin": (m, resp) => { + if (m.index !== 0) resp.ignoreMatch(); + } + }, opts); +}; + +// Common modes +const BACKSLASH_ESCAPE = { + begin: '\\\\[\\s\\S]', relevance: 0 +}; +const APOS_STRING_MODE = { + scope: 'string', + begin: '\'', + end: '\'', + illegal: '\\n', + contains: [BACKSLASH_ESCAPE] +}; +const QUOTE_STRING_MODE = { + scope: 'string', + begin: '"', + end: '"', + illegal: '\\n', + contains: [BACKSLASH_ESCAPE] +}; +const PHRASAL_WORDS_MODE = { + begin: /\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/ +}; +/** + * Creates a comment mode + * + * @param {string | RegExp} begin + * @param {string | RegExp} end + * @param {Mode | {}} [modeOptions] + * @returns {Partial} + */ +const COMMENT = function(begin, end, modeOptions = {}) { + const mode = inherit$1( + { + scope: 'comment', + begin, + end, + contains: [] + }, + modeOptions + ); + mode.contains.push({ + scope: 'doctag', + // hack to avoid the space from being included. the space is necessary to + // match here to prevent the plain text rule below from gobbling up doctags + begin: '[ ]*(?=(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):)', + end: /(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):/, + excludeBegin: true, + relevance: 0 + }); + const ENGLISH_WORD = either( + // list of common 1 and 2 letter words in English + "I", + "a", + "is", + "so", + "us", + "to", + "at", + "if", + "in", + "it", + "on", + // note: this is not an exhaustive list of contractions, just popular ones + /[A-Za-z]+['](d|ve|re|ll|t|s|n)/, // contractions - can't we'd they're let's, etc + /[A-Za-z]+[-][a-z]+/, // `no-way`, etc. + /[A-Za-z][a-z]{2,}/ // allow capitalized words at beginning of sentences + ); + // looking like plain text, more likely to be a comment + mode.contains.push( + { + // TODO: how to include ", (, ) without breaking grammars that use these for + // comment delimiters? + // begin: /[ ]+([()"]?([A-Za-z'-]{3,}|is|a|I|so|us|[tT][oO]|at|if|in|it|on)[.]?[()":]?([.][ ]|[ ]|\))){3}/ + // --- + + // this tries to find sequences of 3 english words in a row (without any + // "programming" type syntax) this gives us a strong signal that we've + // TRULY found a comment - vs perhaps scanning with the wrong language. + // It's possible to find something that LOOKS like the start of the + // comment - but then if there is no readable text - good chance it is a + // false match and not a comment. + // + // for a visual example please see: + // https://github.com/highlightjs/highlight.js/issues/2827 + + begin: concat( + /[ ]+/, // necessary to prevent us gobbling up doctags like /* @author Bob Mcgill */ + '(', + ENGLISH_WORD, + /[.]?[:]?([.][ ]|[ ])/, + '){3}') // look for 3 words in a row + } + ); + return mode; +}; +const C_LINE_COMMENT_MODE = COMMENT('//', '$'); +const C_BLOCK_COMMENT_MODE = COMMENT('/\\*', '\\*/'); +const HASH_COMMENT_MODE = COMMENT('#', '$'); +const NUMBER_MODE = { + scope: 'number', + begin: NUMBER_RE, + relevance: 0 +}; +const C_NUMBER_MODE = { + scope: 'number', + begin: C_NUMBER_RE, + relevance: 0 +}; +const BINARY_NUMBER_MODE = { + scope: 'number', + begin: BINARY_NUMBER_RE, + relevance: 0 +}; +const REGEXP_MODE = { + scope: "regexp", + begin: /\/(?=[^/\n]*\/)/, + end: /\/[gimuy]*/, + contains: [ + BACKSLASH_ESCAPE, + { + begin: /\[/, + end: /\]/, + relevance: 0, + contains: [BACKSLASH_ESCAPE] + } + ] +}; +const TITLE_MODE = { + scope: 'title', + begin: IDENT_RE, + relevance: 0 +}; +const UNDERSCORE_TITLE_MODE = { + scope: 'title', + begin: UNDERSCORE_IDENT_RE, + relevance: 0 +}; +const METHOD_GUARD = { + // excludes method names from keyword processing + begin: '\\.\\s*' + UNDERSCORE_IDENT_RE, + relevance: 0 +}; + +/** + * Adds end same as begin mechanics to a mode + * + * Your mode must include at least a single () match group as that first match + * group is what is used for comparison + * @param {Partial} mode + */ +const END_SAME_AS_BEGIN = function(mode) { + return Object.assign(mode, + { + /** @type {ModeCallback} */ + 'on:begin': (m, resp) => { resp.data._beginMatch = m[1]; }, + /** @type {ModeCallback} */ + 'on:end': (m, resp) => { if (resp.data._beginMatch !== m[1]) resp.ignoreMatch(); } + }); +}; + +var MODES = /*#__PURE__*/Object.freeze({ + __proto__: null, + APOS_STRING_MODE: APOS_STRING_MODE, + BACKSLASH_ESCAPE: BACKSLASH_ESCAPE, + BINARY_NUMBER_MODE: BINARY_NUMBER_MODE, + BINARY_NUMBER_RE: BINARY_NUMBER_RE, + COMMENT: COMMENT, + C_BLOCK_COMMENT_MODE: C_BLOCK_COMMENT_MODE, + C_LINE_COMMENT_MODE: C_LINE_COMMENT_MODE, + C_NUMBER_MODE: C_NUMBER_MODE, + C_NUMBER_RE: C_NUMBER_RE, + END_SAME_AS_BEGIN: END_SAME_AS_BEGIN, + HASH_COMMENT_MODE: HASH_COMMENT_MODE, + IDENT_RE: IDENT_RE, + MATCH_NOTHING_RE: MATCH_NOTHING_RE, + METHOD_GUARD: METHOD_GUARD, + NUMBER_MODE: NUMBER_MODE, + NUMBER_RE: NUMBER_RE, + PHRASAL_WORDS_MODE: PHRASAL_WORDS_MODE, + QUOTE_STRING_MODE: QUOTE_STRING_MODE, + REGEXP_MODE: REGEXP_MODE, + RE_STARTERS_RE: RE_STARTERS_RE, + SHEBANG: SHEBANG, + TITLE_MODE: TITLE_MODE, + UNDERSCORE_IDENT_RE: UNDERSCORE_IDENT_RE, + UNDERSCORE_TITLE_MODE: UNDERSCORE_TITLE_MODE +}); + +/** +@typedef {import('highlight.js').CallbackResponse} CallbackResponse +@typedef {import('highlight.js').CompilerExt} CompilerExt +*/ + +// Grammar extensions / plugins +// See: https://github.com/highlightjs/highlight.js/issues/2833 + +// Grammar extensions allow "syntactic sugar" to be added to the grammar modes +// without requiring any underlying changes to the compiler internals. + +// `compileMatch` being the perfect small example of now allowing a grammar +// author to write `match` when they desire to match a single expression rather +// than being forced to use `begin`. The extension then just moves `match` into +// `begin` when it runs. Ie, no features have been added, but we've just made +// the experience of writing (and reading grammars) a little bit nicer. + +// ------ + +// TODO: We need negative look-behind support to do this properly +/** + * Skip a match if it has a preceding dot + * + * This is used for `beginKeywords` to prevent matching expressions such as + * `bob.keyword.do()`. The mode compiler automatically wires this up as a + * special _internal_ 'on:begin' callback for modes with `beginKeywords` + * @param {RegExpMatchArray} match + * @param {CallbackResponse} response + */ +function skipIfHasPrecedingDot(match, response) { + const before = match.input[match.index - 1]; + if (before === ".") { + response.ignoreMatch(); + } +} + +/** + * + * @type {CompilerExt} + */ +function scopeClassName(mode, _parent) { + // eslint-disable-next-line no-undefined + if (mode.className !== undefined) { + mode.scope = mode.className; + delete mode.className; + } +} + +/** + * `beginKeywords` syntactic sugar + * @type {CompilerExt} + */ +function beginKeywords(mode, parent) { + if (!parent) return; + if (!mode.beginKeywords) return; + + // for languages with keywords that include non-word characters checking for + // a word boundary is not sufficient, so instead we check for a word boundary + // or whitespace - this does no harm in any case since our keyword engine + // doesn't allow spaces in keywords anyways and we still check for the boundary + // first + mode.begin = '\\b(' + mode.beginKeywords.split(' ').join('|') + ')(?!\\.)(?=\\b|\\s)'; + mode.__beforeBegin = skipIfHasPrecedingDot; + mode.keywords = mode.keywords || mode.beginKeywords; + delete mode.beginKeywords; + + // prevents double relevance, the keywords themselves provide + // relevance, the mode doesn't need to double it + // eslint-disable-next-line no-undefined + if (mode.relevance === undefined) mode.relevance = 0; +} + +/** + * Allow `illegal` to contain an array of illegal values + * @type {CompilerExt} + */ +function compileIllegal(mode, _parent) { + if (!Array.isArray(mode.illegal)) return; + + mode.illegal = either(...mode.illegal); +} + +/** + * `match` to match a single expression for readability + * @type {CompilerExt} + */ +function compileMatch(mode, _parent) { + if (!mode.match) return; + if (mode.begin || mode.end) throw new Error("begin & end are not supported with match"); + + mode.begin = mode.match; + delete mode.match; +} + +/** + * provides the default 1 relevance to all modes + * @type {CompilerExt} + */ +function compileRelevance(mode, _parent) { + // eslint-disable-next-line no-undefined + if (mode.relevance === undefined) mode.relevance = 1; +} + +// allow beforeMatch to act as a "qualifier" for the match +// the full match begin must be [beforeMatch][begin] +const beforeMatchExt = (mode, parent) => { + if (!mode.beforeMatch) return; + // starts conflicts with endsParent which we need to make sure the child + // rule is not matched multiple times + if (mode.starts) throw new Error("beforeMatch cannot be used with starts"); + + const originalMode = Object.assign({}, mode); + Object.keys(mode).forEach((key) => { delete mode[key]; }); + + mode.keywords = originalMode.keywords; + mode.begin = concat(originalMode.beforeMatch, lookahead(originalMode.begin)); + mode.starts = { + relevance: 0, + contains: [ + Object.assign(originalMode, { endsParent: true }) + ] + }; + mode.relevance = 0; + + delete originalMode.beforeMatch; +}; + +// keywords that should have no default relevance value +const COMMON_KEYWORDS = [ + 'of', + 'and', + 'for', + 'in', + 'not', + 'or', + 'if', + 'then', + 'parent', // common variable name + 'list', // common variable name + 'value' // common variable name +]; + +const DEFAULT_KEYWORD_SCOPE = "keyword"; + +/** + * Given raw keywords from a language definition, compile them. + * + * @param {string | Record | Array} rawKeywords + * @param {boolean} caseInsensitive + */ +function compileKeywords(rawKeywords, caseInsensitive, scopeName = DEFAULT_KEYWORD_SCOPE) { + /** @type {import("highlight.js/private").KeywordDict} */ + const compiledKeywords = Object.create(null); + + // input can be a string of keywords, an array of keywords, or a object with + // named keys representing scopeName (which can then point to a string or array) + if (typeof rawKeywords === 'string') { + compileList(scopeName, rawKeywords.split(" ")); + } else if (Array.isArray(rawKeywords)) { + compileList(scopeName, rawKeywords); + } else { + Object.keys(rawKeywords).forEach(function(scopeName) { + // collapse all our objects back into the parent object + Object.assign( + compiledKeywords, + compileKeywords(rawKeywords[scopeName], caseInsensitive, scopeName) + ); + }); + } + return compiledKeywords; + + // --- + + /** + * Compiles an individual list of keywords + * + * Ex: "for if when while|5" + * + * @param {string} scopeName + * @param {Array} keywordList + */ + function compileList(scopeName, keywordList) { + if (caseInsensitive) { + keywordList = keywordList.map(x => x.toLowerCase()); + } + keywordList.forEach(function(keyword) { + const pair = keyword.split('|'); + compiledKeywords[pair[0]] = [scopeName, scoreForKeyword(pair[0], pair[1])]; + }); + } +} + +/** + * Returns the proper score for a given keyword + * + * Also takes into account comment keywords, which will be scored 0 UNLESS + * another score has been manually assigned. + * @param {string} keyword + * @param {string} [providedScore] + */ +function scoreForKeyword(keyword, providedScore) { + // manual scores always win over common keywords + // so you can force a score of 1 if you really insist + if (providedScore) { + return Number(providedScore); + } + + return commonKeyword(keyword) ? 0 : 1; +} + +/** + * Determines if a given keyword is common or not + * + * @param {string} keyword */ +function commonKeyword(keyword) { + return COMMON_KEYWORDS.includes(keyword.toLowerCase()); +} + +/* + +For the reasoning behind this please see: +https://github.com/highlightjs/highlight.js/issues/2880#issuecomment-747275419 + +*/ + +/** + * @type {Record} + */ +const seenDeprecations = {}; + +/** + * @param {string} message + */ +const error = (message) => { + console.error(message); +}; + +/** + * @param {string} message + * @param {any} args + */ +const warn = (message, ...args) => { + console.log(`WARN: ${message}`, ...args); +}; + +/** + * @param {string} version + * @param {string} message + */ +const deprecated = (version, message) => { + if (seenDeprecations[`${version}/${message}`]) return; + + console.log(`Deprecated as of ${version}. ${message}`); + seenDeprecations[`${version}/${message}`] = true; +}; + +/* eslint-disable no-throw-literal */ + +/** +@typedef {import('highlight.js').CompiledMode} CompiledMode +*/ + +const MultiClassError = new Error(); + +/** + * Renumbers labeled scope names to account for additional inner match + * groups that otherwise would break everything. + * + * Lets say we 3 match scopes: + * + * { 1 => ..., 2 => ..., 3 => ... } + * + * So what we need is a clean match like this: + * + * (a)(b)(c) => [ "a", "b", "c" ] + * + * But this falls apart with inner match groups: + * + * (a)(((b)))(c) => ["a", "b", "b", "b", "c" ] + * + * Our scopes are now "out of alignment" and we're repeating `b` 3 times. + * What needs to happen is the numbers are remapped: + * + * { 1 => ..., 2 => ..., 5 => ... } + * + * We also need to know that the ONLY groups that should be output + * are 1, 2, and 5. This function handles this behavior. + * + * @param {CompiledMode} mode + * @param {Array} regexes + * @param {{key: "beginScope"|"endScope"}} opts + */ +function remapScopeNames(mode, regexes, { key }) { + let offset = 0; + const scopeNames = mode[key]; + /** @type Record */ + const emit = {}; + /** @type Record */ + const positions = {}; + + for (let i = 1; i <= regexes.length; i++) { + positions[i + offset] = scopeNames[i]; + emit[i + offset] = true; + offset += countMatchGroups(regexes[i - 1]); + } + // we use _emit to keep track of which match groups are "top-level" to avoid double + // output from inside match groups + mode[key] = positions; + mode[key]._emit = emit; + mode[key]._multi = true; +} + +/** + * @param {CompiledMode} mode + */ +function beginMultiClass(mode) { + if (!Array.isArray(mode.begin)) return; + + if (mode.skip || mode.excludeBegin || mode.returnBegin) { + error("skip, excludeBegin, returnBegin not compatible with beginScope: {}"); + throw MultiClassError; + } + + if (typeof mode.beginScope !== "object" || mode.beginScope === null) { + error("beginScope must be object"); + throw MultiClassError; + } + + remapScopeNames(mode, mode.begin, { key: "beginScope" }); + mode.begin = _rewriteBackreferences(mode.begin, { joinWith: "" }); +} + +/** + * @param {CompiledMode} mode + */ +function endMultiClass(mode) { + if (!Array.isArray(mode.end)) return; + + if (mode.skip || mode.excludeEnd || mode.returnEnd) { + error("skip, excludeEnd, returnEnd not compatible with endScope: {}"); + throw MultiClassError; + } + + if (typeof mode.endScope !== "object" || mode.endScope === null) { + error("endScope must be object"); + throw MultiClassError; + } + + remapScopeNames(mode, mode.end, { key: "endScope" }); + mode.end = _rewriteBackreferences(mode.end, { joinWith: "" }); +} + +/** + * this exists only to allow `scope: {}` to be used beside `match:` + * Otherwise `beginScope` would necessary and that would look weird + + { + match: [ /def/, /\w+/ ] + scope: { 1: "keyword" , 2: "title" } + } + + * @param {CompiledMode} mode + */ +function scopeSugar(mode) { + if (mode.scope && typeof mode.scope === "object" && mode.scope !== null) { + mode.beginScope = mode.scope; + delete mode.scope; + } +} + +/** + * @param {CompiledMode} mode + */ +function MultiClass(mode) { + scopeSugar(mode); + + if (typeof mode.beginScope === "string") { + mode.beginScope = { _wrap: mode.beginScope }; + } + if (typeof mode.endScope === "string") { + mode.endScope = { _wrap: mode.endScope }; + } + + beginMultiClass(mode); + endMultiClass(mode); +} + +/** +@typedef {import('highlight.js').Mode} Mode +@typedef {import('highlight.js').CompiledMode} CompiledMode +@typedef {import('highlight.js').Language} Language +@typedef {import('highlight.js').HLJSPlugin} HLJSPlugin +@typedef {import('highlight.js').CompiledLanguage} CompiledLanguage +*/ + +// compilation + +/** + * Compiles a language definition result + * + * Given the raw result of a language definition (Language), compiles this so + * that it is ready for highlighting code. + * @param {Language} language + * @returns {CompiledLanguage} + */ +function compileLanguage(language) { + /** + * Builds a regex with the case sensitivity of the current language + * + * @param {RegExp | string} value + * @param {boolean} [global] + */ + function langRe(value, global) { + return new RegExp( + source(value), + 'm' + + (language.case_insensitive ? 'i' : '') + + (language.unicodeRegex ? 'u' : '') + + (global ? 'g' : '') + ); + } + + /** + Stores multiple regular expressions and allows you to quickly search for + them all in a string simultaneously - returning the first match. It does + this by creating a huge (a|b|c) regex - each individual item wrapped with () + and joined by `|` - using match groups to track position. When a match is + found checking which position in the array has content allows us to figure + out which of the original regexes / match groups triggered the match. + + The match object itself (the result of `Regex.exec`) is returned but also + enhanced by merging in any meta-data that was registered with the regex. + This is how we keep track of which mode matched, and what type of rule + (`illegal`, `begin`, end, etc). + */ + class MultiRegex { + constructor() { + this.matchIndexes = {}; + // @ts-ignore + this.regexes = []; + this.matchAt = 1; + this.position = 0; + } + + // @ts-ignore + addRule(re, opts) { + opts.position = this.position++; + // @ts-ignore + this.matchIndexes[this.matchAt] = opts; + this.regexes.push([opts, re]); + this.matchAt += countMatchGroups(re) + 1; + } + + compile() { + if (this.regexes.length === 0) { + // avoids the need to check length every time exec is called + // @ts-ignore + this.exec = () => null; + } + const terminators = this.regexes.map(el => el[1]); + this.matcherRe = langRe(_rewriteBackreferences(terminators, { joinWith: '|' }), true); + this.lastIndex = 0; + } + + /** @param {string} s */ + exec(s) { + this.matcherRe.lastIndex = this.lastIndex; + const match = this.matcherRe.exec(s); + if (!match) { return null; } + + // eslint-disable-next-line no-undefined + const i = match.findIndex((el, i) => i > 0 && el !== undefined); + // @ts-ignore + const matchData = this.matchIndexes[i]; + // trim off any earlier non-relevant match groups (ie, the other regex + // match groups that make up the multi-matcher) + match.splice(0, i); + + return Object.assign(match, matchData); + } + } + + /* + Created to solve the key deficiently with MultiRegex - there is no way to + test for multiple matches at a single location. Why would we need to do + that? In the future a more dynamic engine will allow certain matches to be + ignored. An example: if we matched say the 3rd regex in a large group but + decided to ignore it - we'd need to started testing again at the 4th + regex... but MultiRegex itself gives us no real way to do that. + + So what this class creates MultiRegexs on the fly for whatever search + position they are needed. + + NOTE: These additional MultiRegex objects are created dynamically. For most + grammars most of the time we will never actually need anything more than the + first MultiRegex - so this shouldn't have too much overhead. + + Say this is our search group, and we match regex3, but wish to ignore it. + + regex1 | regex2 | regex3 | regex4 | regex5 ' ie, startAt = 0 + + What we need is a new MultiRegex that only includes the remaining + possibilities: + + regex4 | regex5 ' ie, startAt = 3 + + This class wraps all that complexity up in a simple API... `startAt` decides + where in the array of expressions to start doing the matching. It + auto-increments, so if a match is found at position 2, then startAt will be + set to 3. If the end is reached startAt will return to 0. + + MOST of the time the parser will be setting startAt manually to 0. + */ + class ResumableMultiRegex { + constructor() { + // @ts-ignore + this.rules = []; + // @ts-ignore + this.multiRegexes = []; + this.count = 0; + + this.lastIndex = 0; + this.regexIndex = 0; + } + + // @ts-ignore + getMatcher(index) { + if (this.multiRegexes[index]) return this.multiRegexes[index]; + + const matcher = new MultiRegex(); + this.rules.slice(index).forEach(([re, opts]) => matcher.addRule(re, opts)); + matcher.compile(); + this.multiRegexes[index] = matcher; + return matcher; + } + + resumingScanAtSamePosition() { + return this.regexIndex !== 0; + } + + considerAll() { + this.regexIndex = 0; + } + + // @ts-ignore + addRule(re, opts) { + this.rules.push([re, opts]); + if (opts.type === "begin") this.count++; + } + + /** @param {string} s */ + exec(s) { + const m = this.getMatcher(this.regexIndex); + m.lastIndex = this.lastIndex; + let result = m.exec(s); + + // The following is because we have no easy way to say "resume scanning at the + // existing position but also skip the current rule ONLY". What happens is + // all prior rules are also skipped which can result in matching the wrong + // thing. Example of matching "booger": + + // our matcher is [string, "booger", number] + // + // ....booger.... + + // if "booger" is ignored then we'd really need a regex to scan from the + // SAME position for only: [string, number] but ignoring "booger" (if it + // was the first match), a simple resume would scan ahead who knows how + // far looking only for "number", ignoring potential string matches (or + // future "booger" matches that might be valid.) + + // So what we do: We execute two matchers, one resuming at the same + // position, but the second full matcher starting at the position after: + + // /--- resume first regex match here (for [number]) + // |/---- full match here for [string, "booger", number] + // vv + // ....booger.... + + // Which ever results in a match first is then used. So this 3-4 step + // process essentially allows us to say "match at this position, excluding + // a prior rule that was ignored". + // + // 1. Match "booger" first, ignore. Also proves that [string] does non match. + // 2. Resume matching for [number] + // 3. Match at index + 1 for [string, "booger", number] + // 4. If #2 and #3 result in matches, which came first? + if (this.resumingScanAtSamePosition()) { + if (result && result.index === this.lastIndex) ; else { // use the second matcher result + const m2 = this.getMatcher(0); + m2.lastIndex = this.lastIndex + 1; + result = m2.exec(s); + } + } + + if (result) { + this.regexIndex += result.position + 1; + if (this.regexIndex === this.count) { + // wrap-around to considering all matches again + this.considerAll(); + } + } + + return result; + } + } + + /** + * Given a mode, builds a huge ResumableMultiRegex that can be used to walk + * the content and find matches. + * + * @param {CompiledMode} mode + * @returns {ResumableMultiRegex} + */ + function buildModeRegex(mode) { + const mm = new ResumableMultiRegex(); + + mode.contains.forEach(term => mm.addRule(term.begin, { rule: term, type: "begin" })); + + if (mode.terminatorEnd) { + mm.addRule(mode.terminatorEnd, { type: "end" }); + } + if (mode.illegal) { + mm.addRule(mode.illegal, { type: "illegal" }); + } + + return mm; + } + + /** skip vs abort vs ignore + * + * @skip - The mode is still entered and exited normally (and contains rules apply), + * but all content is held and added to the parent buffer rather than being + * output when the mode ends. Mostly used with `sublanguage` to build up + * a single large buffer than can be parsed by sublanguage. + * + * - The mode begin ands ends normally. + * - Content matched is added to the parent mode buffer. + * - The parser cursor is moved forward normally. + * + * @abort - A hack placeholder until we have ignore. Aborts the mode (as if it + * never matched) but DOES NOT continue to match subsequent `contains` + * modes. Abort is bad/suboptimal because it can result in modes + * farther down not getting applied because an earlier rule eats the + * content but then aborts. + * + * - The mode does not begin. + * - Content matched by `begin` is added to the mode buffer. + * - The parser cursor is moved forward accordingly. + * + * @ignore - Ignores the mode (as if it never matched) and continues to match any + * subsequent `contains` modes. Ignore isn't technically possible with + * the current parser implementation. + * + * - The mode does not begin. + * - Content matched by `begin` is ignored. + * - The parser cursor is not moved forward. + */ + + /** + * Compiles an individual mode + * + * This can raise an error if the mode contains certain detectable known logic + * issues. + * @param {Mode} mode + * @param {CompiledMode | null} [parent] + * @returns {CompiledMode | never} + */ + function compileMode(mode, parent) { + const cmode = /** @type CompiledMode */ (mode); + if (mode.isCompiled) return cmode; + + [ + scopeClassName, + // do this early so compiler extensions generally don't have to worry about + // the distinction between match/begin + compileMatch, + MultiClass, + beforeMatchExt + ].forEach(ext => ext(mode, parent)); + + language.compilerExtensions.forEach(ext => ext(mode, parent)); + + // __beforeBegin is considered private API, internal use only + mode.__beforeBegin = null; + + [ + beginKeywords, + // do this later so compiler extensions that come earlier have access to the + // raw array if they wanted to perhaps manipulate it, etc. + compileIllegal, + // default to 1 relevance if not specified + compileRelevance + ].forEach(ext => ext(mode, parent)); + + mode.isCompiled = true; + + let keywordPattern = null; + if (typeof mode.keywords === "object" && mode.keywords.$pattern) { + // we need a copy because keywords might be compiled multiple times + // so we can't go deleting $pattern from the original on the first + // pass + mode.keywords = Object.assign({}, mode.keywords); + keywordPattern = mode.keywords.$pattern; + delete mode.keywords.$pattern; + } + keywordPattern = keywordPattern || /\w+/; + + if (mode.keywords) { + mode.keywords = compileKeywords(mode.keywords, language.case_insensitive); + } + + cmode.keywordPatternRe = langRe(keywordPattern, true); + + if (parent) { + if (!mode.begin) mode.begin = /\B|\b/; + cmode.beginRe = langRe(cmode.begin); + if (!mode.end && !mode.endsWithParent) mode.end = /\B|\b/; + if (mode.end) cmode.endRe = langRe(cmode.end); + cmode.terminatorEnd = source(cmode.end) || ''; + if (mode.endsWithParent && parent.terminatorEnd) { + cmode.terminatorEnd += (mode.end ? '|' : '') + parent.terminatorEnd; + } + } + if (mode.illegal) cmode.illegalRe = langRe(/** @type {RegExp | string} */ (mode.illegal)); + if (!mode.contains) mode.contains = []; + + mode.contains = [].concat(...mode.contains.map(function(c) { + return expandOrCloneMode(c === 'self' ? mode : c); + })); + mode.contains.forEach(function(c) { compileMode(/** @type Mode */ (c), cmode); }); + + if (mode.starts) { + compileMode(mode.starts, parent); + } + + cmode.matcher = buildModeRegex(cmode); + return cmode; + } + + if (!language.compilerExtensions) language.compilerExtensions = []; + + // self is not valid at the top-level + if (language.contains && language.contains.includes('self')) { + throw new Error("ERR: contains `self` is not supported at the top-level of a language. See documentation."); + } + + // we need a null object, which inherit will guarantee + language.classNameAliases = inherit$1(language.classNameAliases || {}); + + return compileMode(/** @type Mode */ (language)); +} + +/** + * Determines if a mode has a dependency on it's parent or not + * + * If a mode does have a parent dependency then often we need to clone it if + * it's used in multiple places so that each copy points to the correct parent, + * where-as modes without a parent can often safely be re-used at the bottom of + * a mode chain. + * + * @param {Mode | null} mode + * @returns {boolean} - is there a dependency on the parent? + * */ +function dependencyOnParent(mode) { + if (!mode) return false; + + return mode.endsWithParent || dependencyOnParent(mode.starts); +} + +/** + * Expands a mode or clones it if necessary + * + * This is necessary for modes with parental dependenceis (see notes on + * `dependencyOnParent`) and for nodes that have `variants` - which must then be + * exploded into their own individual modes at compile time. + * + * @param {Mode} mode + * @returns {Mode | Mode[]} + * */ +function expandOrCloneMode(mode) { + if (mode.variants && !mode.cachedVariants) { + mode.cachedVariants = mode.variants.map(function(variant) { + return inherit$1(mode, { variants: null }, variant); + }); + } + + // EXPAND + // if we have variants then essentially "replace" the mode with the variants + // this happens in compileMode, where this function is called from + if (mode.cachedVariants) { + return mode.cachedVariants; + } + + // CLONE + // if we have dependencies on parents then we need a unique + // instance of ourselves, so we can be reused with many + // different parents without issue + if (dependencyOnParent(mode)) { + return inherit$1(mode, { starts: mode.starts ? inherit$1(mode.starts) : null }); + } + + if (Object.isFrozen(mode)) { + return inherit$1(mode); + } + + // no special dependency issues, just return ourselves + return mode; +} + +var version = "11.9.0"; + +class HTMLInjectionError extends Error { + constructor(reason, html) { + super(reason); + this.name = "HTMLInjectionError"; + this.html = html; + } +} + +/* +Syntax highlighting with language autodetection. +https://highlightjs.org/ +*/ + + + +/** +@typedef {import('highlight.js').Mode} Mode +@typedef {import('highlight.js').CompiledMode} CompiledMode +@typedef {import('highlight.js').CompiledScope} CompiledScope +@typedef {import('highlight.js').Language} Language +@typedef {import('highlight.js').HLJSApi} HLJSApi +@typedef {import('highlight.js').HLJSPlugin} HLJSPlugin +@typedef {import('highlight.js').PluginEvent} PluginEvent +@typedef {import('highlight.js').HLJSOptions} HLJSOptions +@typedef {import('highlight.js').LanguageFn} LanguageFn +@typedef {import('highlight.js').HighlightedHTMLElement} HighlightedHTMLElement +@typedef {import('highlight.js').BeforeHighlightContext} BeforeHighlightContext +@typedef {import('highlight.js/private').MatchType} MatchType +@typedef {import('highlight.js/private').KeywordData} KeywordData +@typedef {import('highlight.js/private').EnhancedMatch} EnhancedMatch +@typedef {import('highlight.js/private').AnnotatedError} AnnotatedError +@typedef {import('highlight.js').AutoHighlightResult} AutoHighlightResult +@typedef {import('highlight.js').HighlightOptions} HighlightOptions +@typedef {import('highlight.js').HighlightResult} HighlightResult +*/ + + +const escape = escapeHTML; +const inherit = inherit$1; +const NO_MATCH = Symbol("nomatch"); +const MAX_KEYWORD_HITS = 7; + +/** + * @param {any} hljs - object that is extended (legacy) + * @returns {HLJSApi} + */ +const HLJS = function(hljs) { + // Global internal variables used within the highlight.js library. + /** @type {Record} */ + const languages = Object.create(null); + /** @type {Record} */ + const aliases = Object.create(null); + /** @type {HLJSPlugin[]} */ + const plugins = []; + + // safe/production mode - swallows more errors, tries to keep running + // even if a single syntax or parse hits a fatal error + let SAFE_MODE = true; + const LANGUAGE_NOT_FOUND = "Could not find the language '{}', did you forget to load/include a language module?"; + /** @type {Language} */ + const PLAINTEXT_LANGUAGE = { disableAutodetect: true, name: 'Plain text', contains: [] }; + + // Global options used when within external APIs. This is modified when + // calling the `hljs.configure` function. + /** @type HLJSOptions */ + let options = { + ignoreUnescapedHTML: false, + throwUnescapedHTML: false, + noHighlightRe: /^(no-?highlight)$/i, + languageDetectRe: /\blang(?:uage)?-([\w-]+)\b/i, + classPrefix: 'hljs-', + cssSelector: 'pre code', + languages: null, + // beta configuration options, subject to change, welcome to discuss + // https://github.com/highlightjs/highlight.js/issues/1086 + __emitter: TokenTreeEmitter + }; + + /* Utility functions */ + + /** + * Tests a language name to see if highlighting should be skipped + * @param {string} languageName + */ + function shouldNotHighlight(languageName) { + return options.noHighlightRe.test(languageName); + } + + /** + * @param {HighlightedHTMLElement} block - the HTML element to determine language for + */ + function blockLanguage(block) { + let classes = block.className + ' '; + + classes += block.parentNode ? block.parentNode.className : ''; + + // language-* takes precedence over non-prefixed class names. + const match = options.languageDetectRe.exec(classes); + if (match) { + const language = getLanguage(match[1]); + if (!language) { + warn(LANGUAGE_NOT_FOUND.replace("{}", match[1])); + warn("Falling back to no-highlight mode for this block.", block); + } + return language ? match[1] : 'no-highlight'; + } + + return classes + .split(/\s+/) + .find((_class) => shouldNotHighlight(_class) || getLanguage(_class)); + } + + /** + * Core highlighting function. + * + * OLD API + * highlight(lang, code, ignoreIllegals, continuation) + * + * NEW API + * highlight(code, {lang, ignoreIllegals}) + * + * @param {string} codeOrLanguageName - the language to use for highlighting + * @param {string | HighlightOptions} optionsOrCode - the code to highlight + * @param {boolean} [ignoreIllegals] - whether to ignore illegal matches, default is to bail + * + * @returns {HighlightResult} Result - an object that represents the result + * @property {string} language - the language name + * @property {number} relevance - the relevance score + * @property {string} value - the highlighted HTML code + * @property {string} code - the original raw code + * @property {CompiledMode} top - top of the current mode stack + * @property {boolean} illegal - indicates whether any illegal matches were found + */ + function highlight(codeOrLanguageName, optionsOrCode, ignoreIllegals) { + let code = ""; + let languageName = ""; + if (typeof optionsOrCode === "object") { + code = codeOrLanguageName; + ignoreIllegals = optionsOrCode.ignoreIllegals; + languageName = optionsOrCode.language; + } else { + // old API + deprecated("10.7.0", "highlight(lang, code, ...args) has been deprecated."); + deprecated("10.7.0", "Please use highlight(code, options) instead.\nhttps://github.com/highlightjs/highlight.js/issues/2277"); + languageName = codeOrLanguageName; + code = optionsOrCode; + } + + // https://github.com/highlightjs/highlight.js/issues/3149 + // eslint-disable-next-line no-undefined + if (ignoreIllegals === undefined) { ignoreIllegals = true; } + + /** @type {BeforeHighlightContext} */ + const context = { + code, + language: languageName + }; + // the plugin can change the desired language or the code to be highlighted + // just be changing the object it was passed + fire("before:highlight", context); + + // a before plugin can usurp the result completely by providing it's own + // in which case we don't even need to call highlight + const result = context.result + ? context.result + : _highlight(context.language, context.code, ignoreIllegals); + + result.code = context.code; + // the plugin can change anything in result to suite it + fire("after:highlight", result); + + return result; + } + + /** + * private highlight that's used internally and does not fire callbacks + * + * @param {string} languageName - the language to use for highlighting + * @param {string} codeToHighlight - the code to highlight + * @param {boolean?} [ignoreIllegals] - whether to ignore illegal matches, default is to bail + * @param {CompiledMode?} [continuation] - current continuation mode, if any + * @returns {HighlightResult} - result of the highlight operation + */ + function _highlight(languageName, codeToHighlight, ignoreIllegals, continuation) { + const keywordHits = Object.create(null); + + /** + * Return keyword data if a match is a keyword + * @param {CompiledMode} mode - current mode + * @param {string} matchText - the textual match + * @returns {KeywordData | false} + */ + function keywordData(mode, matchText) { + return mode.keywords[matchText]; + } + + function processKeywords() { + if (!top.keywords) { + emitter.addText(modeBuffer); + return; + } + + let lastIndex = 0; + top.keywordPatternRe.lastIndex = 0; + let match = top.keywordPatternRe.exec(modeBuffer); + let buf = ""; + + while (match) { + buf += modeBuffer.substring(lastIndex, match.index); + const word = language.case_insensitive ? match[0].toLowerCase() : match[0]; + const data = keywordData(top, word); + if (data) { + const [kind, keywordRelevance] = data; + emitter.addText(buf); + buf = ""; + + keywordHits[word] = (keywordHits[word] || 0) + 1; + if (keywordHits[word] <= MAX_KEYWORD_HITS) relevance += keywordRelevance; + if (kind.startsWith("_")) { + // _ implied for relevance only, do not highlight + // by applying a class name + buf += match[0]; + } else { + const cssClass = language.classNameAliases[kind] || kind; + emitKeyword(match[0], cssClass); + } + } else { + buf += match[0]; + } + lastIndex = top.keywordPatternRe.lastIndex; + match = top.keywordPatternRe.exec(modeBuffer); + } + buf += modeBuffer.substring(lastIndex); + emitter.addText(buf); + } + + function processSubLanguage() { + if (modeBuffer === "") return; + /** @type HighlightResult */ + let result = null; + + if (typeof top.subLanguage === 'string') { + if (!languages[top.subLanguage]) { + emitter.addText(modeBuffer); + return; + } + result = _highlight(top.subLanguage, modeBuffer, true, continuations[top.subLanguage]); + continuations[top.subLanguage] = /** @type {CompiledMode} */ (result._top); + } else { + result = highlightAuto(modeBuffer, top.subLanguage.length ? top.subLanguage : null); + } + + // Counting embedded language score towards the host language may be disabled + // with zeroing the containing mode relevance. Use case in point is Markdown that + // allows XML everywhere and makes every XML snippet to have a much larger Markdown + // score. + if (top.relevance > 0) { + relevance += result.relevance; + } + emitter.__addSublanguage(result._emitter, result.language); + } + + function processBuffer() { + if (top.subLanguage != null) { + processSubLanguage(); + } else { + processKeywords(); + } + modeBuffer = ''; + } + + /** + * @param {string} text + * @param {string} scope + */ + function emitKeyword(keyword, scope) { + if (keyword === "") return; + + emitter.startScope(scope); + emitter.addText(keyword); + emitter.endScope(); + } + + /** + * @param {CompiledScope} scope + * @param {RegExpMatchArray} match + */ + function emitMultiClass(scope, match) { + let i = 1; + const max = match.length - 1; + while (i <= max) { + if (!scope._emit[i]) { i++; continue; } + const klass = language.classNameAliases[scope[i]] || scope[i]; + const text = match[i]; + if (klass) { + emitKeyword(text, klass); + } else { + modeBuffer = text; + processKeywords(); + modeBuffer = ""; + } + i++; + } + } + + /** + * @param {CompiledMode} mode - new mode to start + * @param {RegExpMatchArray} match + */ + function startNewMode(mode, match) { + if (mode.scope && typeof mode.scope === "string") { + emitter.openNode(language.classNameAliases[mode.scope] || mode.scope); + } + if (mode.beginScope) { + // beginScope just wraps the begin match itself in a scope + if (mode.beginScope._wrap) { + emitKeyword(modeBuffer, language.classNameAliases[mode.beginScope._wrap] || mode.beginScope._wrap); + modeBuffer = ""; + } else if (mode.beginScope._multi) { + // at this point modeBuffer should just be the match + emitMultiClass(mode.beginScope, match); + modeBuffer = ""; + } + } + + top = Object.create(mode, { parent: { value: top } }); + return top; + } + + /** + * @param {CompiledMode } mode - the mode to potentially end + * @param {RegExpMatchArray} match - the latest match + * @param {string} matchPlusRemainder - match plus remainder of content + * @returns {CompiledMode | void} - the next mode, or if void continue on in current mode + */ + function endOfMode(mode, match, matchPlusRemainder) { + let matched = startsWith(mode.endRe, matchPlusRemainder); + + if (matched) { + if (mode["on:end"]) { + const resp = new Response(mode); + mode["on:end"](match, resp); + if (resp.isMatchIgnored) matched = false; + } + + if (matched) { + while (mode.endsParent && mode.parent) { + mode = mode.parent; + } + return mode; + } + } + // even if on:end fires an `ignore` it's still possible + // that we might trigger the end node because of a parent mode + if (mode.endsWithParent) { + return endOfMode(mode.parent, match, matchPlusRemainder); + } + } + + /** + * Handle matching but then ignoring a sequence of text + * + * @param {string} lexeme - string containing full match text + */ + function doIgnore(lexeme) { + if (top.matcher.regexIndex === 0) { + // no more regexes to potentially match here, so we move the cursor forward one + // space + modeBuffer += lexeme[0]; + return 1; + } else { + // no need to move the cursor, we still have additional regexes to try and + // match at this very spot + resumeScanAtSamePosition = true; + return 0; + } + } + + /** + * Handle the start of a new potential mode match + * + * @param {EnhancedMatch} match - the current match + * @returns {number} how far to advance the parse cursor + */ + function doBeginMatch(match) { + const lexeme = match[0]; + const newMode = match.rule; + + const resp = new Response(newMode); + // first internal before callbacks, then the public ones + const beforeCallbacks = [newMode.__beforeBegin, newMode["on:begin"]]; + for (const cb of beforeCallbacks) { + if (!cb) continue; + cb(match, resp); + if (resp.isMatchIgnored) return doIgnore(lexeme); + } + + if (newMode.skip) { + modeBuffer += lexeme; + } else { + if (newMode.excludeBegin) { + modeBuffer += lexeme; + } + processBuffer(); + if (!newMode.returnBegin && !newMode.excludeBegin) { + modeBuffer = lexeme; + } + } + startNewMode(newMode, match); + return newMode.returnBegin ? 0 : lexeme.length; + } + + /** + * Handle the potential end of mode + * + * @param {RegExpMatchArray} match - the current match + */ + function doEndMatch(match) { + const lexeme = match[0]; + const matchPlusRemainder = codeToHighlight.substring(match.index); + + const endMode = endOfMode(top, match, matchPlusRemainder); + if (!endMode) { return NO_MATCH; } + + const origin = top; + if (top.endScope && top.endScope._wrap) { + processBuffer(); + emitKeyword(lexeme, top.endScope._wrap); + } else if (top.endScope && top.endScope._multi) { + processBuffer(); + emitMultiClass(top.endScope, match); + } else if (origin.skip) { + modeBuffer += lexeme; + } else { + if (!(origin.returnEnd || origin.excludeEnd)) { + modeBuffer += lexeme; + } + processBuffer(); + if (origin.excludeEnd) { + modeBuffer = lexeme; + } + } + do { + if (top.scope) { + emitter.closeNode(); + } + if (!top.skip && !top.subLanguage) { + relevance += top.relevance; + } + top = top.parent; + } while (top !== endMode.parent); + if (endMode.starts) { + startNewMode(endMode.starts, match); + } + return origin.returnEnd ? 0 : lexeme.length; + } + + function processContinuations() { + const list = []; + for (let current = top; current !== language; current = current.parent) { + if (current.scope) { + list.unshift(current.scope); + } + } + list.forEach(item => emitter.openNode(item)); + } + + /** @type {{type?: MatchType, index?: number, rule?: Mode}}} */ + let lastMatch = {}; + + /** + * Process an individual match + * + * @param {string} textBeforeMatch - text preceding the match (since the last match) + * @param {EnhancedMatch} [match] - the match itself + */ + function processLexeme(textBeforeMatch, match) { + const lexeme = match && match[0]; + + // add non-matched text to the current mode buffer + modeBuffer += textBeforeMatch; + + if (lexeme == null) { + processBuffer(); + return 0; + } + + // we've found a 0 width match and we're stuck, so we need to advance + // this happens when we have badly behaved rules that have optional matchers to the degree that + // sometimes they can end up matching nothing at all + // Ref: https://github.com/highlightjs/highlight.js/issues/2140 + if (lastMatch.type === "begin" && match.type === "end" && lastMatch.index === match.index && lexeme === "") { + // spit the "skipped" character that our regex choked on back into the output sequence + modeBuffer += codeToHighlight.slice(match.index, match.index + 1); + if (!SAFE_MODE) { + /** @type {AnnotatedError} */ + const err = new Error(`0 width match regex (${languageName})`); + err.languageName = languageName; + err.badRule = lastMatch.rule; + throw err; + } + return 1; + } + lastMatch = match; + + if (match.type === "begin") { + return doBeginMatch(match); + } else if (match.type === "illegal" && !ignoreIllegals) { + // illegal match, we do not continue processing + /** @type {AnnotatedError} */ + const err = new Error('Illegal lexeme "' + lexeme + '" for mode "' + (top.scope || '') + '"'); + err.mode = top; + throw err; + } else if (match.type === "end") { + const processed = doEndMatch(match); + if (processed !== NO_MATCH) { + return processed; + } + } + + // edge case for when illegal matches $ (end of line) which is technically + // a 0 width match but not a begin/end match so it's not caught by the + // first handler (when ignoreIllegals is true) + if (match.type === "illegal" && lexeme === "") { + // advance so we aren't stuck in an infinite loop + return 1; + } + + // infinite loops are BAD, this is a last ditch catch all. if we have a + // decent number of iterations yet our index (cursor position in our + // parsing) still 3x behind our index then something is very wrong + // so we bail + if (iterations > 100000 && iterations > match.index * 3) { + const err = new Error('potential infinite loop, way more iterations than matches'); + throw err; + } + + /* + Why might be find ourselves here? An potential end match that was + triggered but could not be completed. IE, `doEndMatch` returned NO_MATCH. + (this could be because a callback requests the match be ignored, etc) + + This causes no real harm other than stopping a few times too many. + */ + + modeBuffer += lexeme; + return lexeme.length; + } + + const language = getLanguage(languageName); + if (!language) { + error(LANGUAGE_NOT_FOUND.replace("{}", languageName)); + throw new Error('Unknown language: "' + languageName + '"'); + } + + const md = compileLanguage(language); + let result = ''; + /** @type {CompiledMode} */ + let top = continuation || md; + /** @type Record */ + const continuations = {}; // keep continuations for sub-languages + const emitter = new options.__emitter(options); + processContinuations(); + let modeBuffer = ''; + let relevance = 0; + let index = 0; + let iterations = 0; + let resumeScanAtSamePosition = false; + + try { + if (!language.__emitTokens) { + top.matcher.considerAll(); + + for (;;) { + iterations++; + if (resumeScanAtSamePosition) { + // only regexes not matched previously will now be + // considered for a potential match + resumeScanAtSamePosition = false; + } else { + top.matcher.considerAll(); + } + top.matcher.lastIndex = index; + + const match = top.matcher.exec(codeToHighlight); + // console.log("match", match[0], match.rule && match.rule.begin) + + if (!match) break; + + const beforeMatch = codeToHighlight.substring(index, match.index); + const processedCount = processLexeme(beforeMatch, match); + index = match.index + processedCount; + } + processLexeme(codeToHighlight.substring(index)); + } else { + language.__emitTokens(codeToHighlight, emitter); + } + + emitter.finalize(); + result = emitter.toHTML(); + + return { + language: languageName, + value: result, + relevance, + illegal: false, + _emitter: emitter, + _top: top + }; + } catch (err) { + if (err.message && err.message.includes('Illegal')) { + return { + language: languageName, + value: escape(codeToHighlight), + illegal: true, + relevance: 0, + _illegalBy: { + message: err.message, + index, + context: codeToHighlight.slice(index - 100, index + 100), + mode: err.mode, + resultSoFar: result + }, + _emitter: emitter + }; + } else if (SAFE_MODE) { + return { + language: languageName, + value: escape(codeToHighlight), + illegal: false, + relevance: 0, + errorRaised: err, + _emitter: emitter, + _top: top + }; + } else { + throw err; + } + } + } + + /** + * returns a valid highlight result, without actually doing any actual work, + * auto highlight starts with this and it's possible for small snippets that + * auto-detection may not find a better match + * @param {string} code + * @returns {HighlightResult} + */ + function justTextHighlightResult(code) { + const result = { + value: escape(code), + illegal: false, + relevance: 0, + _top: PLAINTEXT_LANGUAGE, + _emitter: new options.__emitter(options) + }; + result._emitter.addText(code); + return result; + } + + /** + Highlighting with language detection. Accepts a string with the code to + highlight. Returns an object with the following properties: + + - language (detected language) + - relevance (int) + - value (an HTML string with highlighting markup) + - secondBest (object with the same structure for second-best heuristically + detected language, may be absent) + + @param {string} code + @param {Array} [languageSubset] + @returns {AutoHighlightResult} + */ + function highlightAuto(code, languageSubset) { + languageSubset = languageSubset || options.languages || Object.keys(languages); + const plaintext = justTextHighlightResult(code); + + const results = languageSubset.filter(getLanguage).filter(autoDetection).map(name => + _highlight(name, code, false) + ); + results.unshift(plaintext); // plaintext is always an option + + const sorted = results.sort((a, b) => { + // sort base on relevance + if (a.relevance !== b.relevance) return b.relevance - a.relevance; + + // always award the tie to the base language + // ie if C++ and Arduino are tied, it's more likely to be C++ + if (a.language && b.language) { + if (getLanguage(a.language).supersetOf === b.language) { + return 1; + } else if (getLanguage(b.language).supersetOf === a.language) { + return -1; + } + } + + // otherwise say they are equal, which has the effect of sorting on + // relevance while preserving the original ordering - which is how ties + // have historically been settled, ie the language that comes first always + // wins in the case of a tie + return 0; + }); + + const [best, secondBest] = sorted; + + /** @type {AutoHighlightResult} */ + const result = best; + result.secondBest = secondBest; + + return result; + } + + /** + * Builds new class name for block given the language name + * + * @param {HTMLElement} element + * @param {string} [currentLang] + * @param {string} [resultLang] + */ + function updateClassName(element, currentLang, resultLang) { + const language = (currentLang && aliases[currentLang]) || resultLang; + + element.classList.add("hljs"); + element.classList.add(`language-${language}`); + } + + /** + * Applies highlighting to a DOM node containing code. + * + * @param {HighlightedHTMLElement} element - the HTML element to highlight + */ + function highlightElement(element) { + /** @type HTMLElement */ + let node = null; + const language = blockLanguage(element); + + if (shouldNotHighlight(language)) return; + + fire("before:highlightElement", + { el: element, language }); + + if (element.dataset.highlighted) { + console.log("Element previously highlighted. To highlight again, first unset `dataset.highlighted`.", element); + return; + } + + // we should be all text, no child nodes (unescaped HTML) - this is possibly + // an HTML injection attack - it's likely too late if this is already in + // production (the code has likely already done its damage by the time + // we're seeing it)... but we yell loudly about this so that hopefully it's + // more likely to be caught in development before making it to production + if (element.children.length > 0) { + if (!options.ignoreUnescapedHTML) { + console.warn("One of your code blocks includes unescaped HTML. This is a potentially serious security risk."); + console.warn("https://github.com/highlightjs/highlight.js/wiki/security"); + console.warn("The element with unescaped HTML:"); + console.warn(element); + } + if (options.throwUnescapedHTML) { + const err = new HTMLInjectionError( + "One of your code blocks includes unescaped HTML.", + element.innerHTML + ); + throw err; + } + } + + node = element; + const text = node.textContent; + const result = language ? highlight(text, { language, ignoreIllegals: true }) : highlightAuto(text); + + element.innerHTML = result.value; + element.dataset.highlighted = "yes"; + updateClassName(element, language, result.language); + element.result = { + language: result.language, + // TODO: remove with version 11.0 + re: result.relevance, + relevance: result.relevance + }; + if (result.secondBest) { + element.secondBest = { + language: result.secondBest.language, + relevance: result.secondBest.relevance + }; + } + + fire("after:highlightElement", { el: element, result, text }); + } + + /** + * Updates highlight.js global options with the passed options + * + * @param {Partial} userOptions + */ + function configure(userOptions) { + options = inherit(options, userOptions); + } + + // TODO: remove v12, deprecated + const initHighlighting = () => { + highlightAll(); + deprecated("10.6.0", "initHighlighting() deprecated. Use highlightAll() now."); + }; + + // TODO: remove v12, deprecated + function initHighlightingOnLoad() { + highlightAll(); + deprecated("10.6.0", "initHighlightingOnLoad() deprecated. Use highlightAll() now."); + } + + let wantsHighlight = false; + + /** + * auto-highlights all pre>code elements on the page + */ + function highlightAll() { + // if we are called too early in the loading process + if (document.readyState === "loading") { + wantsHighlight = true; + return; + } + + const blocks = document.querySelectorAll(options.cssSelector); + blocks.forEach(highlightElement); + } + + function boot() { + // if a highlight was requested before DOM was loaded, do now + if (wantsHighlight) highlightAll(); + } + + // make sure we are in the browser environment + if (typeof window !== 'undefined' && window.addEventListener) { + window.addEventListener('DOMContentLoaded', boot, false); + } + + /** + * Register a language grammar module + * + * @param {string} languageName + * @param {LanguageFn} languageDefinition + */ + function registerLanguage(languageName, languageDefinition) { + let lang = null; + try { + lang = languageDefinition(hljs); + } catch (error$1) { + error("Language definition for '{}' could not be registered.".replace("{}", languageName)); + // hard or soft error + if (!SAFE_MODE) { throw error$1; } else { error(error$1); } + // languages that have serious errors are replaced with essentially a + // "plaintext" stand-in so that the code blocks will still get normal + // css classes applied to them - and one bad language won't break the + // entire highlighter + lang = PLAINTEXT_LANGUAGE; + } + // give it a temporary name if it doesn't have one in the meta-data + if (!lang.name) lang.name = languageName; + languages[languageName] = lang; + lang.rawDefinition = languageDefinition.bind(null, hljs); + + if (lang.aliases) { + registerAliases(lang.aliases, { languageName }); + } + } + + /** + * Remove a language grammar module + * + * @param {string} languageName + */ + function unregisterLanguage(languageName) { + delete languages[languageName]; + for (const alias of Object.keys(aliases)) { + if (aliases[alias] === languageName) { + delete aliases[alias]; + } + } + } + + /** + * @returns {string[]} List of language internal names + */ + function listLanguages() { + return Object.keys(languages); + } + + /** + * @param {string} name - name of the language to retrieve + * @returns {Language | undefined} + */ + function getLanguage(name) { + name = (name || '').toLowerCase(); + return languages[name] || languages[aliases[name]]; + } + + /** + * + * @param {string|string[]} aliasList - single alias or list of aliases + * @param {{languageName: string}} opts + */ + function registerAliases(aliasList, { languageName }) { + if (typeof aliasList === 'string') { + aliasList = [aliasList]; + } + aliasList.forEach(alias => { aliases[alias.toLowerCase()] = languageName; }); + } + + /** + * Determines if a given language has auto-detection enabled + * @param {string} name - name of the language + */ + function autoDetection(name) { + const lang = getLanguage(name); + return lang && !lang.disableAutodetect; + } + + /** + * Upgrades the old highlightBlock plugins to the new + * highlightElement API + * @param {HLJSPlugin} plugin + */ + function upgradePluginAPI(plugin) { + // TODO: remove with v12 + if (plugin["before:highlightBlock"] && !plugin["before:highlightElement"]) { + plugin["before:highlightElement"] = (data) => { + plugin["before:highlightBlock"]( + Object.assign({ block: data.el }, data) + ); + }; + } + if (plugin["after:highlightBlock"] && !plugin["after:highlightElement"]) { + plugin["after:highlightElement"] = (data) => { + plugin["after:highlightBlock"]( + Object.assign({ block: data.el }, data) + ); + }; + } + } + + /** + * @param {HLJSPlugin} plugin + */ + function addPlugin(plugin) { + upgradePluginAPI(plugin); + plugins.push(plugin); + } + + /** + * @param {HLJSPlugin} plugin + */ + function removePlugin(plugin) { + const index = plugins.indexOf(plugin); + if (index !== -1) { + plugins.splice(index, 1); + } + } + + /** + * + * @param {PluginEvent} event + * @param {any} args + */ + function fire(event, args) { + const cb = event; + plugins.forEach(function(plugin) { + if (plugin[cb]) { + plugin[cb](args); + } + }); + } + + /** + * DEPRECATED + * @param {HighlightedHTMLElement} el + */ + function deprecateHighlightBlock(el) { + deprecated("10.7.0", "highlightBlock will be removed entirely in v12.0"); + deprecated("10.7.0", "Please use highlightElement now."); + + return highlightElement(el); + } + + /* Interface definition */ + Object.assign(hljs, { + highlight, + highlightAuto, + highlightAll, + highlightElement, + // TODO: Remove with v12 API + highlightBlock: deprecateHighlightBlock, + configure, + initHighlighting, + initHighlightingOnLoad, + registerLanguage, + unregisterLanguage, + listLanguages, + getLanguage, + registerAliases, + autoDetection, + inherit, + addPlugin, + removePlugin + }); + + hljs.debugMode = function() { SAFE_MODE = false; }; + hljs.safeMode = function() { SAFE_MODE = true; }; + hljs.versionString = version; + + hljs.regex = { + concat: concat, + lookahead: lookahead, + either: either, + optional: optional, + anyNumberOfTimes: anyNumberOfTimes + }; + + for (const key in MODES) { + // @ts-ignore + if (typeof MODES[key] === "object") { + // @ts-ignore + deepFreeze(MODES[key]); + } + } + + // merge all the modes/regexes into our main object + Object.assign(hljs, MODES); + + return hljs; +}; + +// Other names for the variable may break build script +const highlight = HLJS({}); + +// returns a new instance of the highlighter to be used for extensions +// check https://github.com/wooorm/lowlight/issues/47 +highlight.newInstance = () => HLJS({}); + +export { highlight as default }; diff --git a/docs/docs_project/docs_project/static/highlight/es/highlight.min.js b/docs/docs_project/docs_project/static/highlight/es/highlight.min.js new file mode 100755 index 0000000..c6d4ae5 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/highlight.min.js @@ -0,0 +1,307 @@ +/*! + Highlight.js v11.9.0 (git: b7ec4bfafc) + (c) 2006-2023 undefined and other contributors + License: BSD-3-Clause + */ +function e(t){return t instanceof Map?t.clear=t.delete=t.set=()=>{ +throw Error("map is read-only")}:t instanceof Set&&(t.add=t.clear=t.delete=()=>{ +throw Error("set is read-only") +}),Object.freeze(t),Object.getOwnPropertyNames(t).forEach((n=>{ +const i=t[n],s=typeof i;"object"!==s&&"function"!==s||Object.isFrozen(i)||e(i) +})),t}class t{constructor(e){ +void 0===e.data&&(e.data={}),this.data=e.data,this.isMatchIgnored=!1} +ignoreMatch(){this.isMatchIgnored=!0}}function n(e){ +return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'") +}function i(e,...t){const n=Object.create(null);for(const t in e)n[t]=e[t] +;return t.forEach((e=>{for(const t in e)n[t]=e[t]})),n}const s=e=>!!e.scope +;class r{constructor(e,t){ +this.buffer="",this.classPrefix=t.classPrefix,e.walk(this)}addText(e){ +this.buffer+=n(e)}openNode(e){if(!s(e))return;const t=((e,{prefix:t})=>{ +if(e.startsWith("language:"))return e.replace("language:","language-") +;if(e.includes(".")){const n=e.split(".") +;return[`${t}${n.shift()}`,...n.map(((e,t)=>`${e}${"_".repeat(t+1)}`))].join(" ") +}return`${t}${e}`})(e.scope,{prefix:this.classPrefix});this.span(t)} +closeNode(e){s(e)&&(this.buffer+="")}value(){return this.buffer}span(e){ +this.buffer+=``}}const o=(e={})=>{const t={children:[]} +;return Object.assign(t,e),t};class a{constructor(){ +this.rootNode=o(),this.stack=[this.rootNode]}get top(){ +return this.stack[this.stack.length-1]}get root(){return this.rootNode}add(e){ +this.top.children.push(e)}openNode(e){const t=o({scope:e}) +;this.add(t),this.stack.push(t)}closeNode(){ +if(this.stack.length>1)return this.stack.pop()}closeAllNodes(){ +for(;this.closeNode(););}toJSON(){return JSON.stringify(this.rootNode,null,4)} +walk(e){return this.constructor._walk(e,this.rootNode)}static _walk(e,t){ +return"string"==typeof t?e.addText(t):t.children&&(e.openNode(t), +t.children.forEach((t=>this._walk(e,t))),e.closeNode(t)),e}static _collapse(e){ +"string"!=typeof e&&e.children&&(e.children.every((e=>"string"==typeof e))?e.children=[e.children.join("")]:e.children.forEach((e=>{ +a._collapse(e)})))}}class c extends a{constructor(e){super(),this.options=e} +addText(e){""!==e&&this.add(e)}startScope(e){this.openNode(e)}endScope(){ +this.closeNode()}__addSublanguage(e,t){const n=e.root +;t&&(n.scope="language:"+t),this.add(n)}toHTML(){ +return new r(this,this.options).value()}finalize(){ +return this.closeAllNodes(),!0}}function l(e){ +return e?"string"==typeof e?e:e.source:null}function g(e){return h("(?=",e,")")} +function u(e){return h("(?:",e,")*")}function d(e){return h("(?:",e,")?")} +function h(...e){return e.map((e=>l(e))).join("")}function f(...e){const t=(e=>{ +const t=e[e.length-1] +;return"object"==typeof t&&t.constructor===Object?(e.splice(e.length-1,1),t):{} +})(e);return"("+(t.capture?"":"?:")+e.map((e=>l(e))).join("|")+")"} +function p(e){return RegExp(e.toString()+"|").exec("").length-1} +const b=/\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./ +;function m(e,{joinWith:t}){let n=0;return e.map((e=>{n+=1;const t=n +;let i=l(e),s="";for(;i.length>0;){const e=b.exec(i);if(!e){s+=i;break} +s+=i.substring(0,e.index), +i=i.substring(e.index+e[0].length),"\\"===e[0][0]&&e[1]?s+="\\"+(Number(e[1])+t):(s+=e[0], +"("===e[0]&&n++)}return s})).map((e=>`(${e})`)).join(t)} +const E="[a-zA-Z]\\w*",x="[a-zA-Z_]\\w*",w="\\b\\d+(\\.\\d+)?",y="(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",_="\\b(0b[01]+)",O={ +begin:"\\\\[\\s\\S]",relevance:0},k={scope:"string",begin:"'",end:"'", +illegal:"\\n",contains:[O]},v={scope:"string",begin:'"',end:'"',illegal:"\\n", +contains:[O]},N=(e,t,n={})=>{const s=i({scope:"comment",begin:e,end:t, +contains:[]},n);s.contains.push({scope:"doctag", +begin:"[ ]*(?=(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):)", +end:/(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):/,excludeBegin:!0,relevance:0}) +;const r=f("I","a","is","so","us","to","at","if","in","it","on",/[A-Za-z]+['](d|ve|re|ll|t|s|n)/,/[A-Za-z]+[-][a-z]+/,/[A-Za-z][a-z]{2,}/) +;return s.contains.push({begin:h(/[ ]+/,"(",r,/[.]?[:]?([.][ ]|[ ])/,"){3}")}),s +},S=N("//","$"),M=N("/\\*","\\*/"),R=N("#","$");var A=Object.freeze({ +__proto__:null,APOS_STRING_MODE:k,BACKSLASH_ESCAPE:O,BINARY_NUMBER_MODE:{ +scope:"number",begin:_,relevance:0},BINARY_NUMBER_RE:_,COMMENT:N, +C_BLOCK_COMMENT_MODE:M,C_LINE_COMMENT_MODE:S,C_NUMBER_MODE:{scope:"number", +begin:y,relevance:0},C_NUMBER_RE:y,END_SAME_AS_BEGIN:e=>Object.assign(e,{ +"on:begin":(e,t)=>{t.data._beginMatch=e[1]},"on:end":(e,t)=>{ +t.data._beginMatch!==e[1]&&t.ignoreMatch()}}),HASH_COMMENT_MODE:R,IDENT_RE:E, +MATCH_NOTHING_RE:/\b\B/,METHOD_GUARD:{begin:"\\.\\s*"+x,relevance:0}, +NUMBER_MODE:{scope:"number",begin:w,relevance:0},NUMBER_RE:w, +PHRASAL_WORDS_MODE:{ +begin:/\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/ +},QUOTE_STRING_MODE:v,REGEXP_MODE:{scope:"regexp",begin:/\/(?=[^/\n]*\/)/, +end:/\/[gimuy]*/,contains:[O,{begin:/\[/,end:/\]/,relevance:0,contains:[O]}]}, +RE_STARTERS_RE:"!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~", +SHEBANG:(e={})=>{const t=/^#![ ]*\// +;return e.binary&&(e.begin=h(t,/.*\b/,e.binary,/\b.*/)),i({scope:"meta",begin:t, +end:/$/,relevance:0,"on:begin":(e,t)=>{0!==e.index&&t.ignoreMatch()}},e)}, +TITLE_MODE:{scope:"title",begin:E,relevance:0},UNDERSCORE_IDENT_RE:x, +UNDERSCORE_TITLE_MODE:{scope:"title",begin:x,relevance:0}});function j(e,t){ +"."===e.input[e.index-1]&&t.ignoreMatch()}function I(e,t){ +void 0!==e.className&&(e.scope=e.className,delete e.className)}function T(e,t){ +t&&e.beginKeywords&&(e.begin="\\b("+e.beginKeywords.split(" ").join("|")+")(?!\\.)(?=\\b|\\s)", +e.__beforeBegin=j,e.keywords=e.keywords||e.beginKeywords,delete e.beginKeywords, +void 0===e.relevance&&(e.relevance=0))}function L(e,t){ +Array.isArray(e.illegal)&&(e.illegal=f(...e.illegal))}function B(e,t){ +if(e.match){ +if(e.begin||e.end)throw Error("begin & end are not supported with match") +;e.begin=e.match,delete e.match}}function P(e,t){ +void 0===e.relevance&&(e.relevance=1)}const D=(e,t)=>{if(!e.beforeMatch)return +;if(e.starts)throw Error("beforeMatch cannot be used with starts") +;const n=Object.assign({},e);Object.keys(e).forEach((t=>{delete e[t] +})),e.keywords=n.keywords,e.begin=h(n.beforeMatch,g(n.begin)),e.starts={ +relevance:0,contains:[Object.assign(n,{endsParent:!0})] +},e.relevance=0,delete n.beforeMatch +},H=["of","and","for","in","not","or","if","then","parent","list","value"],C="keyword" +;function $(e,t,n=C){const i=Object.create(null) +;return"string"==typeof e?s(n,e.split(" ")):Array.isArray(e)?s(n,e):Object.keys(e).forEach((n=>{ +Object.assign(i,$(e[n],t,n))})),i;function s(e,n){ +t&&(n=n.map((e=>e.toLowerCase()))),n.forEach((t=>{const n=t.split("|") +;i[n[0]]=[e,U(n[0],n[1])]}))}}function U(e,t){ +return t?Number(t):(e=>H.includes(e.toLowerCase()))(e)?0:1}const z={},W=e=>{ +console.error(e)},X=(e,...t)=>{console.log("WARN: "+e,...t)},G=(e,t)=>{ +z[`${e}/${t}`]||(console.log(`Deprecated as of ${e}. ${t}`),z[`${e}/${t}`]=!0) +},K=Error();function F(e,t,{key:n}){let i=0;const s=e[n],r={},o={} +;for(let e=1;e<=t.length;e++)o[e+i]=s[e],r[e+i]=!0,i+=p(t[e-1]) +;e[n]=o,e[n]._emit=r,e[n]._multi=!0}function Z(e){(e=>{ +e.scope&&"object"==typeof e.scope&&null!==e.scope&&(e.beginScope=e.scope, +delete e.scope)})(e),"string"==typeof e.beginScope&&(e.beginScope={ +_wrap:e.beginScope}),"string"==typeof e.endScope&&(e.endScope={_wrap:e.endScope +}),(e=>{if(Array.isArray(e.begin)){ +if(e.skip||e.excludeBegin||e.returnBegin)throw W("skip, excludeBegin, returnBegin not compatible with beginScope: {}"), +K +;if("object"!=typeof e.beginScope||null===e.beginScope)throw W("beginScope must be object"), +K;F(e,e.begin,{key:"beginScope"}),e.begin=m(e.begin,{joinWith:""})}})(e),(e=>{ +if(Array.isArray(e.end)){ +if(e.skip||e.excludeEnd||e.returnEnd)throw W("skip, excludeEnd, returnEnd not compatible with endScope: {}"), +K +;if("object"!=typeof e.endScope||null===e.endScope)throw W("endScope must be object"), +K;F(e,e.end,{key:"endScope"}),e.end=m(e.end,{joinWith:""})}})(e)}function V(e){ +function t(t,n){ +return RegExp(l(t),"m"+(e.case_insensitive?"i":"")+(e.unicodeRegex?"u":"")+(n?"g":"")) +}class n{constructor(){ +this.matchIndexes={},this.regexes=[],this.matchAt=1,this.position=0} +addRule(e,t){ +t.position=this.position++,this.matchIndexes[this.matchAt]=t,this.regexes.push([t,e]), +this.matchAt+=p(e)+1}compile(){0===this.regexes.length&&(this.exec=()=>null) +;const e=this.regexes.map((e=>e[1]));this.matcherRe=t(m(e,{joinWith:"|" +}),!0),this.lastIndex=0}exec(e){this.matcherRe.lastIndex=this.lastIndex +;const t=this.matcherRe.exec(e);if(!t)return null +;const n=t.findIndex(((e,t)=>t>0&&void 0!==e)),i=this.matchIndexes[n] +;return t.splice(0,n),Object.assign(t,i)}}class s{constructor(){ +this.rules=[],this.multiRegexes=[], +this.count=0,this.lastIndex=0,this.regexIndex=0}getMatcher(e){ +if(this.multiRegexes[e])return this.multiRegexes[e];const t=new n +;return this.rules.slice(e).forEach((([e,n])=>t.addRule(e,n))), +t.compile(),this.multiRegexes[e]=t,t}resumingScanAtSamePosition(){ +return 0!==this.regexIndex}considerAll(){this.regexIndex=0}addRule(e,t){ +this.rules.push([e,t]),"begin"===t.type&&this.count++}exec(e){ +const t=this.getMatcher(this.regexIndex);t.lastIndex=this.lastIndex +;let n=t.exec(e) +;if(this.resumingScanAtSamePosition())if(n&&n.index===this.lastIndex);else{ +const t=this.getMatcher(0);t.lastIndex=this.lastIndex+1,n=t.exec(e)} +return n&&(this.regexIndex+=n.position+1, +this.regexIndex===this.count&&this.considerAll()),n}} +if(e.compilerExtensions||(e.compilerExtensions=[]), +e.contains&&e.contains.includes("self"))throw Error("ERR: contains `self` is not supported at the top-level of a language. See documentation.") +;return e.classNameAliases=i(e.classNameAliases||{}),function n(r,o){const a=r +;if(r.isCompiled)return a +;[I,B,Z,D].forEach((e=>e(r,o))),e.compilerExtensions.forEach((e=>e(r,o))), +r.__beforeBegin=null,[T,L,P].forEach((e=>e(r,o))),r.isCompiled=!0;let c=null +;return"object"==typeof r.keywords&&r.keywords.$pattern&&(r.keywords=Object.assign({},r.keywords), +c=r.keywords.$pattern, +delete r.keywords.$pattern),c=c||/\w+/,r.keywords&&(r.keywords=$(r.keywords,e.case_insensitive)), +a.keywordPatternRe=t(c,!0), +o&&(r.begin||(r.begin=/\B|\b/),a.beginRe=t(a.begin),r.end||r.endsWithParent||(r.end=/\B|\b/), +r.end&&(a.endRe=t(a.end)), +a.terminatorEnd=l(a.end)||"",r.endsWithParent&&o.terminatorEnd&&(a.terminatorEnd+=(r.end?"|":"")+o.terminatorEnd)), +r.illegal&&(a.illegalRe=t(r.illegal)), +r.contains||(r.contains=[]),r.contains=[].concat(...r.contains.map((e=>(e=>(e.variants&&!e.cachedVariants&&(e.cachedVariants=e.variants.map((t=>i(e,{ +variants:null},t)))),e.cachedVariants?e.cachedVariants:q(e)?i(e,{ +starts:e.starts?i(e.starts):null +}):Object.isFrozen(e)?i(e):e))("self"===e?r:e)))),r.contains.forEach((e=>{n(e,a) +})),r.starts&&n(r.starts,o),a.matcher=(e=>{const t=new s +;return e.contains.forEach((e=>t.addRule(e.begin,{rule:e,type:"begin" +}))),e.terminatorEnd&&t.addRule(e.terminatorEnd,{type:"end" +}),e.illegal&&t.addRule(e.illegal,{type:"illegal"}),t})(a),a}(e)}function q(e){ +return!!e&&(e.endsWithParent||q(e.starts))}class J extends Error{ +constructor(e,t){super(e),this.name="HTMLInjectionError",this.html=t}} +const Y=n,Q=i,ee=Symbol("nomatch"),te=n=>{ +const i=Object.create(null),s=Object.create(null),r=[];let o=!0 +;const a="Could not find the language '{}', did you forget to load/include a language module?",l={ +disableAutodetect:!0,name:"Plain text",contains:[]};let p={ +ignoreUnescapedHTML:!1,throwUnescapedHTML:!1,noHighlightRe:/^(no-?highlight)$/i, +languageDetectRe:/\blang(?:uage)?-([\w-]+)\b/i,classPrefix:"hljs-", +cssSelector:"pre code",languages:null,__emitter:c};function b(e){ +return p.noHighlightRe.test(e)}function m(e,t,n){let i="",s="" +;"object"==typeof t?(i=e, +n=t.ignoreIllegals,s=t.language):(G("10.7.0","highlight(lang, code, ...args) has been deprecated."), +G("10.7.0","Please use highlight(code, options) instead.\nhttps://github.com/highlightjs/highlight.js/issues/2277"), +s=e,i=t),void 0===n&&(n=!0);const r={code:i,language:s};N("before:highlight",r) +;const o=r.result?r.result:E(r.language,r.code,n) +;return o.code=r.code,N("after:highlight",o),o}function E(e,n,s,r){ +const c=Object.create(null);function l(){if(!N.keywords)return void M.addText(R) +;let e=0;N.keywordPatternRe.lastIndex=0;let t=N.keywordPatternRe.exec(R),n="" +;for(;t;){n+=R.substring(e,t.index) +;const s=_.case_insensitive?t[0].toLowerCase():t[0],r=(i=s,N.keywords[i]);if(r){ +const[e,i]=r +;if(M.addText(n),n="",c[s]=(c[s]||0)+1,c[s]<=7&&(A+=i),e.startsWith("_"))n+=t[0];else{ +const n=_.classNameAliases[e]||e;u(t[0],n)}}else n+=t[0] +;e=N.keywordPatternRe.lastIndex,t=N.keywordPatternRe.exec(R)}var i +;n+=R.substring(e),M.addText(n)}function g(){null!=N.subLanguage?(()=>{ +if(""===R)return;let e=null;if("string"==typeof N.subLanguage){ +if(!i[N.subLanguage])return void M.addText(R) +;e=E(N.subLanguage,R,!0,S[N.subLanguage]),S[N.subLanguage]=e._top +}else e=x(R,N.subLanguage.length?N.subLanguage:null) +;N.relevance>0&&(A+=e.relevance),M.__addSublanguage(e._emitter,e.language) +})():l(),R=""}function u(e,t){ +""!==e&&(M.startScope(t),M.addText(e),M.endScope())}function d(e,t){let n=1 +;const i=t.length-1;for(;n<=i;){if(!e._emit[n]){n++;continue} +const i=_.classNameAliases[e[n]]||e[n],s=t[n];i?u(s,i):(R=s,l(),R=""),n++}} +function h(e,t){ +return e.scope&&"string"==typeof e.scope&&M.openNode(_.classNameAliases[e.scope]||e.scope), +e.beginScope&&(e.beginScope._wrap?(u(R,_.classNameAliases[e.beginScope._wrap]||e.beginScope._wrap), +R=""):e.beginScope._multi&&(d(e.beginScope,t),R="")),N=Object.create(e,{parent:{ +value:N}}),N}function f(e,n,i){let s=((e,t)=>{const n=e&&e.exec(t) +;return n&&0===n.index})(e.endRe,i);if(s){if(e["on:end"]){const i=new t(e) +;e["on:end"](n,i),i.isMatchIgnored&&(s=!1)}if(s){ +for(;e.endsParent&&e.parent;)e=e.parent;return e}} +if(e.endsWithParent)return f(e.parent,n,i)}function b(e){ +return 0===N.matcher.regexIndex?(R+=e[0],1):(T=!0,0)}function m(e){ +const t=e[0],i=n.substring(e.index),s=f(N,e,i);if(!s)return ee;const r=N +;N.endScope&&N.endScope._wrap?(g(), +u(t,N.endScope._wrap)):N.endScope&&N.endScope._multi?(g(), +d(N.endScope,e)):r.skip?R+=t:(r.returnEnd||r.excludeEnd||(R+=t), +g(),r.excludeEnd&&(R=t));do{ +N.scope&&M.closeNode(),N.skip||N.subLanguage||(A+=N.relevance),N=N.parent +}while(N!==s.parent);return s.starts&&h(s.starts,e),r.returnEnd?0:t.length} +let w={};function y(i,r){const a=r&&r[0];if(R+=i,null==a)return g(),0 +;if("begin"===w.type&&"end"===r.type&&w.index===r.index&&""===a){ +if(R+=n.slice(r.index,r.index+1),!o){const t=Error(`0 width match regex (${e})`) +;throw t.languageName=e,t.badRule=w.rule,t}return 1} +if(w=r,"begin"===r.type)return(e=>{ +const n=e[0],i=e.rule,s=new t(i),r=[i.__beforeBegin,i["on:begin"]] +;for(const t of r)if(t&&(t(e,s),s.isMatchIgnored))return b(n) +;return i.skip?R+=n:(i.excludeBegin&&(R+=n), +g(),i.returnBegin||i.excludeBegin||(R=n)),h(i,e),i.returnBegin?0:n.length})(r) +;if("illegal"===r.type&&!s){ +const e=Error('Illegal lexeme "'+a+'" for mode "'+(N.scope||"")+'"') +;throw e.mode=N,e}if("end"===r.type){const e=m(r);if(e!==ee)return e} +if("illegal"===r.type&&""===a)return 1 +;if(I>1e5&&I>3*r.index)throw Error("potential infinite loop, way more iterations than matches") +;return R+=a,a.length}const _=O(e) +;if(!_)throw W(a.replace("{}",e)),Error('Unknown language: "'+e+'"') +;const k=V(_);let v="",N=r||k;const S={},M=new p.__emitter(p);(()=>{const e=[] +;for(let t=N;t!==_;t=t.parent)t.scope&&e.unshift(t.scope) +;e.forEach((e=>M.openNode(e)))})();let R="",A=0,j=0,I=0,T=!1;try{ +if(_.__emitTokens)_.__emitTokens(n,M);else{for(N.matcher.considerAll();;){ +I++,T?T=!1:N.matcher.considerAll(),N.matcher.lastIndex=j +;const e=N.matcher.exec(n);if(!e)break;const t=y(n.substring(j,e.index),e) +;j=e.index+t}y(n.substring(j))}return M.finalize(),v=M.toHTML(),{language:e, +value:v,relevance:A,illegal:!1,_emitter:M,_top:N}}catch(t){ +if(t.message&&t.message.includes("Illegal"))return{language:e,value:Y(n), +illegal:!0,relevance:0,_illegalBy:{message:t.message,index:j, +context:n.slice(j-100,j+100),mode:t.mode,resultSoFar:v},_emitter:M};if(o)return{ +language:e,value:Y(n),illegal:!1,relevance:0,errorRaised:t,_emitter:M,_top:N} +;throw t}}function x(e,t){t=t||p.languages||Object.keys(i);const n=(e=>{ +const t={value:Y(e),illegal:!1,relevance:0,_top:l,_emitter:new p.__emitter(p)} +;return t._emitter.addText(e),t})(e),s=t.filter(O).filter(v).map((t=>E(t,e,!1))) +;s.unshift(n);const r=s.sort(((e,t)=>{ +if(e.relevance!==t.relevance)return t.relevance-e.relevance +;if(e.language&&t.language){if(O(e.language).supersetOf===t.language)return 1 +;if(O(t.language).supersetOf===e.language)return-1}return 0})),[o,a]=r,c=o +;return c.secondBest=a,c}function w(e){let t=null;const n=(e=>{ +let t=e.className+" ";t+=e.parentNode?e.parentNode.className:"" +;const n=p.languageDetectRe.exec(t);if(n){const t=O(n[1]) +;return t||(X(a.replace("{}",n[1])), +X("Falling back to no-highlight mode for this block.",e)),t?n[1]:"no-highlight"} +return t.split(/\s+/).find((e=>b(e)||O(e)))})(e);if(b(n))return +;if(N("before:highlightElement",{el:e,language:n +}),e.dataset.highlighted)return void console.log("Element previously highlighted. To highlight again, first unset `dataset.highlighted`.",e) +;if(e.children.length>0&&(p.ignoreUnescapedHTML||(console.warn("One of your code blocks includes unescaped HTML. This is a potentially serious security risk."), +console.warn("https://github.com/highlightjs/highlight.js/wiki/security"), +console.warn("The element with unescaped HTML:"), +console.warn(e)),p.throwUnescapedHTML))throw new J("One of your code blocks includes unescaped HTML.",e.innerHTML) +;t=e;const i=t.textContent,r=n?m(i,{language:n,ignoreIllegals:!0}):x(i) +;e.innerHTML=r.value,e.dataset.highlighted="yes",((e,t,n)=>{const i=t&&s[t]||n +;e.classList.add("hljs"),e.classList.add("language-"+i) +})(e,n,r.language),e.result={language:r.language,re:r.relevance, +relevance:r.relevance},r.secondBest&&(e.secondBest={ +language:r.secondBest.language,relevance:r.secondBest.relevance +}),N("after:highlightElement",{el:e,result:r,text:i})}let y=!1;function _(){ +"loading"!==document.readyState?document.querySelectorAll(p.cssSelector).forEach(w):y=!0 +}function O(e){return e=(e||"").toLowerCase(),i[e]||i[s[e]]} +function k(e,{languageName:t}){"string"==typeof e&&(e=[e]),e.forEach((e=>{ +s[e.toLowerCase()]=t}))}function v(e){const t=O(e) +;return t&&!t.disableAutodetect}function N(e,t){const n=e;r.forEach((e=>{ +e[n]&&e[n](t)}))} +"undefined"!=typeof window&&window.addEventListener&&window.addEventListener("DOMContentLoaded",(()=>{ +y&&_()}),!1),Object.assign(n,{highlight:m,highlightAuto:x,highlightAll:_, +highlightElement:w, +highlightBlock:e=>(G("10.7.0","highlightBlock will be removed entirely in v12.0"), +G("10.7.0","Please use highlightElement now."),w(e)),configure:e=>{p=Q(p,e)}, +initHighlighting:()=>{ +_(),G("10.6.0","initHighlighting() deprecated. Use highlightAll() now.")}, +initHighlightingOnLoad:()=>{ +_(),G("10.6.0","initHighlightingOnLoad() deprecated. Use highlightAll() now.") +},registerLanguage:(e,t)=>{let s=null;try{s=t(n)}catch(t){ +if(W("Language definition for '{}' could not be registered.".replace("{}",e)), +!o)throw t;W(t),s=l} +s.name||(s.name=e),i[e]=s,s.rawDefinition=t.bind(null,n),s.aliases&&k(s.aliases,{ +languageName:e})},unregisterLanguage:e=>{delete i[e] +;for(const t of Object.keys(s))s[t]===e&&delete s[t]}, +listLanguages:()=>Object.keys(i),getLanguage:O,registerAliases:k, +autoDetection:v,inherit:Q,addPlugin:e=>{(e=>{ +e["before:highlightBlock"]&&!e["before:highlightElement"]&&(e["before:highlightElement"]=t=>{ +e["before:highlightBlock"](Object.assign({block:t.el},t)) +}),e["after:highlightBlock"]&&!e["after:highlightElement"]&&(e["after:highlightElement"]=t=>{ +e["after:highlightBlock"](Object.assign({block:t.el},t))})})(e),r.push(e)}, +removePlugin:e=>{const t=r.indexOf(e);-1!==t&&r.splice(t,1)}}),n.debugMode=()=>{ +o=!1},n.safeMode=()=>{o=!0},n.versionString="11.9.0",n.regex={concat:h, +lookahead:g,either:f,optional:d,anyNumberOfTimes:u} +;for(const t in A)"object"==typeof A[t]&&e(A[t]);return Object.assign(n,A),n +},ne=te({});ne.newInstance=()=>te({});export{ne as default}; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/languages/django.js b/docs/docs_project/docs_project/static/highlight/es/languages/django.js new file mode 100755 index 0000000..eeea71e --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/languages/django.js @@ -0,0 +1,83 @@ +/*! `django` grammar compiled for Highlight.js 11.9.0 */ +var hljsGrammar = (function () { + 'use strict'; + + /* + Language: Django + Description: Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. + Requires: xml.js + Author: Ivan Sagalaev + Contributors: Ilya Baryshev + Website: https://www.djangoproject.com + Category: template + */ + + /** @type LanguageFn */ + function django(hljs) { + const FILTER = { + begin: /\|[A-Za-z]+:?/, + keywords: { name: + 'truncatewords removetags linebreaksbr yesno get_digit timesince random striptags ' + + 'filesizeformat escape linebreaks length_is ljust rjust cut urlize fix_ampersands ' + + 'title floatformat capfirst pprint divisibleby add make_list unordered_list urlencode ' + + 'timeuntil urlizetrunc wordcount stringformat linenumbers slice date dictsort ' + + 'dictsortreversed default_if_none pluralize lower join center default ' + + 'truncatewords_html upper length phone2numeric wordwrap time addslashes slugify first ' + + 'escapejs force_escape iriencode last safe safeseq truncatechars localize unlocalize ' + + 'localtime utc timezone' }, + contains: [ + hljs.QUOTE_STRING_MODE, + hljs.APOS_STRING_MODE + ] + }; + + return { + name: 'Django', + aliases: [ 'jinja' ], + case_insensitive: true, + subLanguage: 'xml', + contains: [ + hljs.COMMENT(/\{%\s*comment\s*%\}/, /\{%\s*endcomment\s*%\}/), + hljs.COMMENT(/\{#/, /#\}/), + { + className: 'template-tag', + begin: /\{%/, + end: /%\}/, + contains: [ + { + className: 'name', + begin: /\w+/, + keywords: { name: + 'comment endcomment load templatetag ifchanged endifchanged if endif firstof for ' + + 'endfor ifnotequal endifnotequal widthratio extends include spaceless ' + + 'endspaceless regroup ifequal endifequal ssi now with cycle url filter ' + + 'endfilter debug block endblock else autoescape endautoescape csrf_token empty elif ' + + 'endwith static trans blocktrans endblocktrans get_static_prefix get_media_prefix ' + + 'plural get_current_language language get_available_languages ' + + 'get_current_language_bidi get_language_info get_language_info_list localize ' + + 'endlocalize localtime endlocaltime timezone endtimezone get_current_timezone ' + + 'verbatim' }, + starts: { + endsWithParent: true, + keywords: 'in by as', + contains: [ FILTER ], + relevance: 0 + } + } + ] + }, + { + className: 'template-variable', + begin: /\{\{/, + end: /\}\}/, + contains: [ FILTER ] + } + ] + }; + } + + return django; + +})(); +; +export default hljsGrammar; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/languages/django.min.js b/docs/docs_project/docs_project/static/highlight/es/languages/django.min.js new file mode 100755 index 0000000..d94b22e --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/languages/django.min.js @@ -0,0 +1,13 @@ +/*! `django` grammar compiled for Highlight.js 11.9.0 */ +var hljsGrammar=(()=>{"use strict";return e=>{const a={begin:/\|[A-Za-z]+:?/, +keywords:{ +name:"truncatewords removetags linebreaksbr yesno get_digit timesince random striptags filesizeformat escape linebreaks length_is ljust rjust cut urlize fix_ampersands title floatformat capfirst pprint divisibleby add make_list unordered_list urlencode timeuntil urlizetrunc wordcount stringformat linenumbers slice date dictsort dictsortreversed default_if_none pluralize lower join center default truncatewords_html upper length phone2numeric wordwrap time addslashes slugify first escapejs force_escape iriencode last safe safeseq truncatechars localize unlocalize localtime utc timezone" +},contains:[e.QUOTE_STRING_MODE,e.APOS_STRING_MODE]};return{name:"Django", +aliases:["jinja"],case_insensitive:!0,subLanguage:"xml", +contains:[e.COMMENT(/\{%\s*comment\s*%\}/,/\{%\s*endcomment\s*%\}/),e.COMMENT(/\{#/,/#\}/),{ +className:"template-tag",begin:/\{%/,end:/%\}/,contains:[{className:"name", +begin:/\w+/,keywords:{ +name:"comment endcomment load templatetag ifchanged endifchanged if endif firstof for endfor ifnotequal endifnotequal widthratio extends include spaceless endspaceless regroup ifequal endifequal ssi now with cycle url filter endfilter debug block endblock else autoescape endautoescape csrf_token empty elif endwith static trans blocktrans endblocktrans get_static_prefix get_media_prefix plural get_current_language language get_available_languages get_current_language_bidi get_language_info get_language_info_list localize endlocalize localtime endlocaltime timezone endtimezone get_current_timezone verbatim" +},starts:{endsWithParent:!0,keywords:"in by as",contains:[a],relevance:0}}]},{ +className:"template-variable",begin:/\{\{/,end:/\}\}/,contains:[a]}]}}})() +;export default hljsGrammar; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/languages/http.js b/docs/docs_project/docs_project/static/highlight/es/languages/http.js new file mode 100755 index 0000000..58e2a76 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/languages/http.js @@ -0,0 +1,105 @@ +/*! `http` grammar compiled for Highlight.js 11.9.0 */ +var hljsGrammar = (function () { + 'use strict'; + + /* + Language: HTTP + Description: HTTP request and response headers with automatic body highlighting + Author: Ivan Sagalaev + Category: protocols, web + Website: https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview + */ + + function http(hljs) { + const regex = hljs.regex; + const VERSION = 'HTTP/([32]|1\\.[01])'; + const HEADER_NAME = /[A-Za-z][A-Za-z0-9-]*/; + const HEADER = { + className: 'attribute', + begin: regex.concat('^', HEADER_NAME, '(?=\\:\\s)'), + starts: { contains: [ + { + className: "punctuation", + begin: /: /, + relevance: 0, + starts: { + end: '$', + relevance: 0 + } + } + ] } + }; + const HEADERS_AND_BODY = [ + HEADER, + { + begin: '\\n\\n', + starts: { + subLanguage: [], + endsWithParent: true + } + } + ]; + + return { + name: 'HTTP', + aliases: [ 'https' ], + illegal: /\S/, + contains: [ + // response + { + begin: '^(?=' + VERSION + " \\d{3})", + end: /$/, + contains: [ + { + className: "meta", + begin: VERSION + }, + { + className: 'number', + begin: '\\b\\d{3}\\b' + } + ], + starts: { + end: /\b\B/, + illegal: /\S/, + contains: HEADERS_AND_BODY + } + }, + // request + { + begin: '(?=^[A-Z]+ (.*?) ' + VERSION + '$)', + end: /$/, + contains: [ + { + className: 'string', + begin: ' ', + end: ' ', + excludeBegin: true, + excludeEnd: true + }, + { + className: "meta", + begin: VERSION + }, + { + className: 'keyword', + begin: '[A-Z]+' + } + ], + starts: { + end: /\b\B/, + illegal: /\S/, + contains: HEADERS_AND_BODY + } + }, + // to allow headers to work even without a preamble + hljs.inherit(HEADER, { relevance: 0 }) + ] + }; + } + + return http; + +})(); +; +export default hljsGrammar; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/languages/http.min.js b/docs/docs_project/docs_project/static/highlight/es/languages/http.min.js new file mode 100755 index 0000000..956e43e --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/languages/http.min.js @@ -0,0 +1,14 @@ +/*! `http` grammar compiled for Highlight.js 11.9.0 */ +var hljsGrammar=(()=>{"use strict";return e=>{const a="HTTP/([32]|1\\.[01])",n={ +className:"attribute", +begin:e.regex.concat("^",/[A-Za-z][A-Za-z0-9-]*/,"(?=\\:\\s)"),starts:{ +contains:[{className:"punctuation",begin:/: /,relevance:0,starts:{end:"$", +relevance:0}}]}},s=[n,{begin:"\\n\\n",starts:{subLanguage:[],endsWithParent:!0} +}];return{name:"HTTP",aliases:["https"],illegal:/\S/,contains:[{ +begin:"^(?="+a+" \\d{3})",end:/$/,contains:[{className:"meta",begin:a},{ +className:"number",begin:"\\b\\d{3}\\b"}],starts:{end:/\b\B/,illegal:/\S/, +contains:s}},{begin:"(?=^[A-Z]+ (.*?) "+a+"$)",end:/$/,contains:[{ +className:"string",begin:" ",end:" ",excludeBegin:!0,excludeEnd:!0},{ +className:"meta",begin:a},{className:"keyword",begin:"[A-Z]+"}],starts:{ +end:/\b\B/,illegal:/\S/,contains:s}},e.inherit(n,{relevance:0})]}}})() +;export default hljsGrammar; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/languages/python.js b/docs/docs_project/docs_project/static/highlight/es/languages/python.js new file mode 100755 index 0000000..745df31 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/languages/python.js @@ -0,0 +1,443 @@ +/*! `python` grammar compiled for Highlight.js 11.9.0 */ +var hljsGrammar = (function () { + 'use strict'; + + /* + Language: Python + Description: Python is an interpreted, object-oriented, high-level programming language with dynamic semantics. + Website: https://www.python.org + Category: common + */ + + function python(hljs) { + const regex = hljs.regex; + const IDENT_RE = /[\p{XID_Start}_]\p{XID_Continue}*/u; + const RESERVED_WORDS = [ + 'and', + 'as', + 'assert', + 'async', + 'await', + 'break', + 'case', + 'class', + 'continue', + 'def', + 'del', + 'elif', + 'else', + 'except', + 'finally', + 'for', + 'from', + 'global', + 'if', + 'import', + 'in', + 'is', + 'lambda', + 'match', + 'nonlocal|10', + 'not', + 'or', + 'pass', + 'raise', + 'return', + 'try', + 'while', + 'with', + 'yield' + ]; + + const BUILT_INS = [ + '__import__', + 'abs', + 'all', + 'any', + 'ascii', + 'bin', + 'bool', + 'breakpoint', + 'bytearray', + 'bytes', + 'callable', + 'chr', + 'classmethod', + 'compile', + 'complex', + 'delattr', + 'dict', + 'dir', + 'divmod', + 'enumerate', + 'eval', + 'exec', + 'filter', + 'float', + 'format', + 'frozenset', + 'getattr', + 'globals', + 'hasattr', + 'hash', + 'help', + 'hex', + 'id', + 'input', + 'int', + 'isinstance', + 'issubclass', + 'iter', + 'len', + 'list', + 'locals', + 'map', + 'max', + 'memoryview', + 'min', + 'next', + 'object', + 'oct', + 'open', + 'ord', + 'pow', + 'print', + 'property', + 'range', + 'repr', + 'reversed', + 'round', + 'set', + 'setattr', + 'slice', + 'sorted', + 'staticmethod', + 'str', + 'sum', + 'super', + 'tuple', + 'type', + 'vars', + 'zip' + ]; + + const LITERALS = [ + '__debug__', + 'Ellipsis', + 'False', + 'None', + 'NotImplemented', + 'True' + ]; + + // https://docs.python.org/3/library/typing.html + // TODO: Could these be supplemented by a CamelCase matcher in certain + // contexts, leaving these remaining only for relevance hinting? + const TYPES = [ + "Any", + "Callable", + "Coroutine", + "Dict", + "List", + "Literal", + "Generic", + "Optional", + "Sequence", + "Set", + "Tuple", + "Type", + "Union" + ]; + + const KEYWORDS = { + $pattern: /[A-Za-z]\w+|__\w+__/, + keyword: RESERVED_WORDS, + built_in: BUILT_INS, + literal: LITERALS, + type: TYPES + }; + + const PROMPT = { + className: 'meta', + begin: /^(>>>|\.\.\.) / + }; + + const SUBST = { + className: 'subst', + begin: /\{/, + end: /\}/, + keywords: KEYWORDS, + illegal: /#/ + }; + + const LITERAL_BRACKET = { + begin: /\{\{/, + relevance: 0 + }; + + const STRING = { + className: 'string', + contains: [ hljs.BACKSLASH_ESCAPE ], + variants: [ + { + begin: /([uU]|[bB]|[rR]|[bB][rR]|[rR][bB])?'''/, + end: /'''/, + contains: [ + hljs.BACKSLASH_ESCAPE, + PROMPT + ], + relevance: 10 + }, + { + begin: /([uU]|[bB]|[rR]|[bB][rR]|[rR][bB])?"""/, + end: /"""/, + contains: [ + hljs.BACKSLASH_ESCAPE, + PROMPT + ], + relevance: 10 + }, + { + begin: /([fF][rR]|[rR][fF]|[fF])'''/, + end: /'''/, + contains: [ + hljs.BACKSLASH_ESCAPE, + PROMPT, + LITERAL_BRACKET, + SUBST + ] + }, + { + begin: /([fF][rR]|[rR][fF]|[fF])"""/, + end: /"""/, + contains: [ + hljs.BACKSLASH_ESCAPE, + PROMPT, + LITERAL_BRACKET, + SUBST + ] + }, + { + begin: /([uU]|[rR])'/, + end: /'/, + relevance: 10 + }, + { + begin: /([uU]|[rR])"/, + end: /"/, + relevance: 10 + }, + { + begin: /([bB]|[bB][rR]|[rR][bB])'/, + end: /'/ + }, + { + begin: /([bB]|[bB][rR]|[rR][bB])"/, + end: /"/ + }, + { + begin: /([fF][rR]|[rR][fF]|[fF])'/, + end: /'/, + contains: [ + hljs.BACKSLASH_ESCAPE, + LITERAL_BRACKET, + SUBST + ] + }, + { + begin: /([fF][rR]|[rR][fF]|[fF])"/, + end: /"/, + contains: [ + hljs.BACKSLASH_ESCAPE, + LITERAL_BRACKET, + SUBST + ] + }, + hljs.APOS_STRING_MODE, + hljs.QUOTE_STRING_MODE + ] + }; + + // https://docs.python.org/3.9/reference/lexical_analysis.html#numeric-literals + const digitpart = '[0-9](_?[0-9])*'; + const pointfloat = `(\\b(${digitpart}))?\\.(${digitpart})|\\b(${digitpart})\\.`; + // Whitespace after a number (or any lexical token) is needed only if its absence + // would change the tokenization + // https://docs.python.org/3.9/reference/lexical_analysis.html#whitespace-between-tokens + // We deviate slightly, requiring a word boundary or a keyword + // to avoid accidentally recognizing *prefixes* (e.g., `0` in `0x41` or `08` or `0__1`) + const lookahead = `\\b|${RESERVED_WORDS.join('|')}`; + const NUMBER = { + className: 'number', + relevance: 0, + variants: [ + // exponentfloat, pointfloat + // https://docs.python.org/3.9/reference/lexical_analysis.html#floating-point-literals + // optionally imaginary + // https://docs.python.org/3.9/reference/lexical_analysis.html#imaginary-literals + // Note: no leading \b because floats can start with a decimal point + // and we don't want to mishandle e.g. `fn(.5)`, + // no trailing \b for pointfloat because it can end with a decimal point + // and we don't want to mishandle e.g. `0..hex()`; this should be safe + // because both MUST contain a decimal point and so cannot be confused with + // the interior part of an identifier + { + begin: `(\\b(${digitpart})|(${pointfloat}))[eE][+-]?(${digitpart})[jJ]?(?=${lookahead})` + }, + { + begin: `(${pointfloat})[jJ]?` + }, + + // decinteger, bininteger, octinteger, hexinteger + // https://docs.python.org/3.9/reference/lexical_analysis.html#integer-literals + // optionally "long" in Python 2 + // https://docs.python.org/2.7/reference/lexical_analysis.html#integer-and-long-integer-literals + // decinteger is optionally imaginary + // https://docs.python.org/3.9/reference/lexical_analysis.html#imaginary-literals + { + begin: `\\b([1-9](_?[0-9])*|0+(_?0)*)[lLjJ]?(?=${lookahead})` + }, + { + begin: `\\b0[bB](_?[01])+[lL]?(?=${lookahead})` + }, + { + begin: `\\b0[oO](_?[0-7])+[lL]?(?=${lookahead})` + }, + { + begin: `\\b0[xX](_?[0-9a-fA-F])+[lL]?(?=${lookahead})` + }, + + // imagnumber (digitpart-based) + // https://docs.python.org/3.9/reference/lexical_analysis.html#imaginary-literals + { + begin: `\\b(${digitpart})[jJ](?=${lookahead})` + } + ] + }; + const COMMENT_TYPE = { + className: "comment", + begin: regex.lookahead(/# type:/), + end: /$/, + keywords: KEYWORDS, + contains: [ + { // prevent keywords from coloring `type` + begin: /# type:/ + }, + // comment within a datatype comment includes no keywords + { + begin: /#/, + end: /\b\B/, + endsWithParent: true + } + ] + }; + const PARAMS = { + className: 'params', + variants: [ + // Exclude params in functions without params + { + className: "", + begin: /\(\s*\)/, + skip: true + }, + { + begin: /\(/, + end: /\)/, + excludeBegin: true, + excludeEnd: true, + keywords: KEYWORDS, + contains: [ + 'self', + PROMPT, + NUMBER, + STRING, + hljs.HASH_COMMENT_MODE + ] + } + ] + }; + SUBST.contains = [ + STRING, + NUMBER, + PROMPT + ]; + + return { + name: 'Python', + aliases: [ + 'py', + 'gyp', + 'ipython' + ], + unicodeRegex: true, + keywords: KEYWORDS, + illegal: /(<\/|\?)|=>/, + contains: [ + PROMPT, + NUMBER, + { + // very common convention + begin: /\bself\b/ + }, + { + // eat "if" prior to string so that it won't accidentally be + // labeled as an f-string + beginKeywords: "if", + relevance: 0 + }, + { match: /\bor\b/, scope: "keyword" }, + STRING, + COMMENT_TYPE, + hljs.HASH_COMMENT_MODE, + { + match: [ + /\bdef/, /\s+/, + IDENT_RE, + ], + scope: { + 1: "keyword", + 3: "title.function" + }, + contains: [ PARAMS ] + }, + { + variants: [ + { + match: [ + /\bclass/, /\s+/, + IDENT_RE, /\s*/, + /\(\s*/, IDENT_RE,/\s*\)/ + ], + }, + { + match: [ + /\bclass/, /\s+/, + IDENT_RE + ], + } + ], + scope: { + 1: "keyword", + 3: "title.class", + 6: "title.class.inherited", + } + }, + { + className: 'meta', + begin: /^[\t ]*@/, + end: /(?=#)|$/, + contains: [ + NUMBER, + PARAMS, + STRING + ] + } + ] + }; + } + + return python; + +})(); +; +export default hljsGrammar; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/languages/python.min.js b/docs/docs_project/docs_project/static/highlight/es/languages/python.min.js new file mode 100755 index 0000000..458b78c --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/languages/python.min.js @@ -0,0 +1,41 @@ +/*! `python` grammar compiled for Highlight.js 11.9.0 */ +var hljsGrammar=(()=>{"use strict";return e=>{ +const n=e.regex,a=/[\p{XID_Start}_]\p{XID_Continue}*/u,s=["and","as","assert","async","await","break","case","class","continue","def","del","elif","else","except","finally","for","from","global","if","import","in","is","lambda","match","nonlocal|10","not","or","pass","raise","return","try","while","with","yield"],t={ +$pattern:/[A-Za-z]\w+|__\w+__/,keyword:s, +built_in:["__import__","abs","all","any","ascii","bin","bool","breakpoint","bytearray","bytes","callable","chr","classmethod","compile","complex","delattr","dict","dir","divmod","enumerate","eval","exec","filter","float","format","frozenset","getattr","globals","hasattr","hash","help","hex","id","input","int","isinstance","issubclass","iter","len","list","locals","map","max","memoryview","min","next","object","oct","open","ord","pow","print","property","range","repr","reversed","round","set","setattr","slice","sorted","staticmethod","str","sum","super","tuple","type","vars","zip"], +literal:["__debug__","Ellipsis","False","None","NotImplemented","True"], +type:["Any","Callable","Coroutine","Dict","List","Literal","Generic","Optional","Sequence","Set","Tuple","Type","Union"] +},i={className:"meta",begin:/^(>>>|\.\.\.) /},r={className:"subst",begin:/\{/, +end:/\}/,keywords:t,illegal:/#/},l={begin:/\{\{/,relevance:0},b={ +className:"string",contains:[e.BACKSLASH_ESCAPE],variants:[{ +begin:/([uU]|[bB]|[rR]|[bB][rR]|[rR][bB])?'''/,end:/'''/, +contains:[e.BACKSLASH_ESCAPE,i],relevance:10},{ +begin:/([uU]|[bB]|[rR]|[bB][rR]|[rR][bB])?"""/,end:/"""/, +contains:[e.BACKSLASH_ESCAPE,i],relevance:10},{ +begin:/([fF][rR]|[rR][fF]|[fF])'''/,end:/'''/, +contains:[e.BACKSLASH_ESCAPE,i,l,r]},{begin:/([fF][rR]|[rR][fF]|[fF])"""/, +end:/"""/,contains:[e.BACKSLASH_ESCAPE,i,l,r]},{begin:/([uU]|[rR])'/,end:/'/, +relevance:10},{begin:/([uU]|[rR])"/,end:/"/,relevance:10},{ +begin:/([bB]|[bB][rR]|[rR][bB])'/,end:/'/},{begin:/([bB]|[bB][rR]|[rR][bB])"/, +end:/"/},{begin:/([fF][rR]|[rR][fF]|[fF])'/,end:/'/, +contains:[e.BACKSLASH_ESCAPE,l,r]},{begin:/([fF][rR]|[rR][fF]|[fF])"/,end:/"/, +contains:[e.BACKSLASH_ESCAPE,l,r]},e.APOS_STRING_MODE,e.QUOTE_STRING_MODE] +},o="[0-9](_?[0-9])*",c=`(\\b(${o}))?\\.(${o})|\\b(${o})\\.`,d="\\b|"+s.join("|"),m={ +className:"number",relevance:0,variants:[{ +begin:`(\\b(${o})|(${c}))[eE][+-]?(${o})[jJ]?(?=${d})`},{begin:`(${c})[jJ]?`},{ +begin:`\\b([1-9](_?[0-9])*|0+(_?0)*)[lLjJ]?(?=${d})`},{ +begin:`\\b0[bB](_?[01])+[lL]?(?=${d})`},{begin:`\\b0[oO](_?[0-7])+[lL]?(?=${d})` +},{begin:`\\b0[xX](_?[0-9a-fA-F])+[lL]?(?=${d})`},{begin:`\\b(${o})[jJ](?=${d})` +}]},g={className:"comment",begin:n.lookahead(/# type:/),end:/$/,keywords:t, +contains:[{begin:/# type:/},{begin:/#/,end:/\b\B/,endsWithParent:!0}]},p={ +className:"params",variants:[{className:"",begin:/\(\s*\)/,skip:!0},{begin:/\(/, +end:/\)/,excludeBegin:!0,excludeEnd:!0,keywords:t, +contains:["self",i,m,b,e.HASH_COMMENT_MODE]}]};return r.contains=[b,m,i],{ +name:"Python",aliases:["py","gyp","ipython"],unicodeRegex:!0,keywords:t, +illegal:/(<\/|\?)|=>/,contains:[i,m,{begin:/\bself\b/},{beginKeywords:"if", +relevance:0},{match:/\bor\b/,scope:"keyword"},b,g,e.HASH_COMMENT_MODE,{ +match:[/\bdef/,/\s+/,a],scope:{1:"keyword",3:"title.function"},contains:[p]},{ +variants:[{match:[/\bclass/,/\s+/,a,/\s*/,/\(\s*/,a,/\s*\)/]},{ +match:[/\bclass/,/\s+/,a]}],scope:{1:"keyword",3:"title.class", +6:"title.class.inherited"}},{className:"meta",begin:/^[\t ]*@/,end:/(?=#)|$/, +contains:[m,p,b]}]}}})();export default hljsGrammar; \ No newline at end of file diff --git a/docs/docs_project/docs_project/static/highlight/es/languages/xml.js b/docs/docs_project/docs_project/static/highlight/es/languages/xml.js new file mode 100755 index 0000000..c4e1353 --- /dev/null +++ b/docs/docs_project/docs_project/static/highlight/es/languages/xml.js @@ -0,0 +1,249 @@ +/*! `xml` grammar compiled for Highlight.js 11.9.0 */ +var hljsGrammar = (function () { + 'use strict'; + + /* + Language: HTML, XML + Website: https://www.w3.org/XML/ + Category: common, web + Audit: 2020 + */ + + /** @type LanguageFn */ + function xml(hljs) { + const regex = hljs.regex; + // XML names can have the following additional letters: https://www.w3.org/TR/xml/#NT-NameChar + // OTHER_NAME_CHARS = /[:\-.0-9\u00B7\u0300-\u036F\u203F-\u2040]/; + // Element names start with NAME_START_CHAR followed by optional other Unicode letters, ASCII digits, hyphens, underscores, and periods + // const TAG_NAME_RE = regex.concat(/[A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD]/, regex.optional(/[A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD\-.0-9\u00B7\u0300-\u036F\u203F-\u2040]*:/), /[A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD\-.0-9\u00B7\u0300-\u036F\u203F-\u2040]*/);; + // const XML_IDENT_RE = /[A-Z_a-z:\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD\-.0-9\u00B7\u0300-\u036F\u203F-\u2040]+/; + // const TAG_NAME_RE = regex.concat(/[A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD]/, regex.optional(/[A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD\-.0-9\u00B7\u0300-\u036F\u203F-\u2040]*:/), /[A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD\-.0-9\u00B7\u0300-\u036F\u203F-\u2040]*/); + // however, to cater for performance and more Unicode support rely simply on the Unicode letter class + const TAG_NAME_RE = regex.concat(/[\p{L}_]/u, regex.optional(/[\p{L}0-9_.-]*:/u), /[\p{L}0-9_.-]*/u); + const XML_IDENT_RE = /[\p{L}0-9._:-]+/u; + const XML_ENTITIES = { + className: 'symbol', + begin: /&[a-z]+;|&#[0-9]+;|&#x[a-f0-9]+;/ + }; + const XML_META_KEYWORDS = { + begin: /\s/, + contains: [ + { + className: 'keyword', + begin: /#?[a-z_][a-z1-9_-]+/, + illegal: /\n/ + } + ] + }; + const XML_META_PAR_KEYWORDS = hljs.inherit(XML_META_KEYWORDS, { + begin: /\(/, + end: /\)/ + }); + const APOS_META_STRING_MODE = hljs.inherit(hljs.APOS_STRING_MODE, { className: 'string' }); + const QUOTE_META_STRING_MODE = hljs.inherit(hljs.QUOTE_STRING_MODE, { className: 'string' }); + const TAG_INTERNALS = { + endsWithParent: true, + illegal: /`]+/ } + ] + } + ] + } + ] + }; + return { + name: 'HTML, XML', + aliases: [ + 'html', + 'xhtml', + 'rss', + 'atom', + 'xjb', + 'xsd', + 'xsl', + 'plist', + 'wsf', + 'svg' + ], + case_insensitive: true, + unicodeRegex: true, + contains: [ + { + className: 'meta', + begin: //, + relevance: 10, + contains: [ + XML_META_KEYWORDS, + QUOTE_META_STRING_MODE, + APOS_META_STRING_MODE, + XML_META_PAR_KEYWORDS, + { + begin: /\[/, + end: /\]/, + contains: [ + { + className: 'meta', + begin: //, + contains: [ + XML_META_KEYWORDS, + XML_META_PAR_KEYWORDS, + QUOTE_META_STRING_MODE, + APOS_META_STRING_MODE + ] + } + ] + } + ] + }, + hljs.COMMENT( + //, + { relevance: 10 } + ), + { + begin: //, + relevance: 10 + }, + XML_ENTITIES, + // xml processing instructions + { + className: 'meta', + end: /\?>/, + variants: [ + { + begin: /<\?xml/, + relevance: 10, + contains: [ + QUOTE_META_STRING_MODE + ] + }, + { + begin: /<\?[a-z][a-z0-9]+/, + } + ] + + }, + { + className: 'tag', + /* + The lookahead pattern (?=...) ensures that 'begin' only matches + ')/, + end: />/, + keywords: { name: 'style' }, + contains: [ TAG_INTERNALS ], + starts: { + end: /<\/style>/, + returnEnd: true, + subLanguage: [ + 'css', + 'xml' + ] + } + }, + { + className: 'tag', + // See the comment in the