Language Management

/**
 * Registers a new language definition
 * @param languageName - Unique name for the language
 * @param language - Language definition function that returns Language object
 */
function registerLanguage(languageName: string, language: LanguageFn): void;

/**
 * Language definition function type
 * @param hljs - Optional reference to the hljs API for accessing modes and utilities
 * @returns Language definition object with syntax rules
 */
type LanguageFn = (hljs?: HLJSApi) => Language;

interface Language {
  /** Language display name */
  name?: string;
  /** Alternative names for the language */
  aliases?: string[];
  /** Whether to disable auto-detection for this language */
  disableAutodetect?: boolean;
  /** Array of syntax mode definitions */
  contains: Mode[];
  /** Whether the language is case-insensitive */
  case_insensitive?: boolean;
  /** Keywords and their classifications */
  keywords?: Record<string, any> | string;
  /** CSS class name aliases */
  classNameAliases?: Record<string, string>;
  /** Language this is a superset of */
  supersetOf?: string;
}

import hljs from "highlight.js/lib/core";
import javascript from "highlight.js/lib/languages/javascript";
import python from "highlight.js/lib/languages/python";
import xml from "highlight.js/lib/languages/xml";

// Register individual languages
hljs.registerLanguage('javascript', javascript);
hljs.registerLanguage('python', python);
hljs.registerLanguage('xml', xml);

// Register with custom name
hljs.registerLanguage('js', javascript);

// Register multiple languages programmatically
const languages = [
  ['javascript', javascript],
  ['python', python],
  ['html', xml], // XML handles HTML
];

languages.forEach(([name, lang]) => {
  hljs.registerLanguage(name, lang);
});

/**
 * Removes a language definition from the registry
 * @param languageName - Name of the language to remove
 */
function unregisterLanguage(languageName: string): void;

import hljs from "highlight.js";

// Remove a language to save memory
hljs.unregisterLanguage('fortran');
hljs.unregisterLanguage('cobol');

// Remove before re-registering with custom definition
hljs.unregisterLanguage('javascript');
hljs.registerLanguage('javascript', myCustomJavaScript);

// Conditional registration
if (!needsLegacySupport) {
  hljs.unregisterLanguage('pascal');
  hljs.unregisterLanguage('ada');
}

/**
 * Returns list of all registered language names
 * @returns Array of language name strings
 */
function listLanguages(): string[];

import hljs from "highlight.js";

// Check what languages are available
const languages = hljs.listLanguages();
console.log(`${languages.length} languages available:`, languages);

// Build a language selector
const selector = document.getElementById('language-select');
hljs.listLanguages().forEach(lang => {
  const option = document.createElement('option');
  option.value = lang;
  option.textContent = lang;
  selector.appendChild(option);
});

// Verify specific language is registered
if (hljs.listLanguages().includes('typescript')) {
  console.log('TypeScript support is available');
}

undefined

/**
 * Gets a registered language definition
 * @param languageName - Name of the language to retrieve
 * @returns Language definition object or undefined if not found
 */
function getLanguage(languageName: string): Language | undefined;

import hljs from "highlight.js";

// Check if language exists before using
const jsLang = hljs.getLanguage('javascript');
if (jsLang) {
  console.log('JavaScript language:', jsLang.name);
  console.log('Aliases:', jsLang.aliases);
  console.log('Case insensitive:', jsLang.case_insensitive);
}

// Safely get language info
function getLanguageInfo(langName) {
  const lang = hljs.getLanguage(langName);
  return lang ? {
    name: lang.name || langName,
    aliases: lang.aliases || [],
    autodetect: !lang.disableAutodetect
  } : null;
}

// Language validation
function isLanguageSupported(langName) {
  return hljs.getLanguage(langName) !== undefined;
}

getLanguage()

/**
 * Gets a language definition, throws if not found
 * @deprecated Since v10.4.0, will be removed in v11.0. Use getLanguage() instead.
 * @param languageName - Name of the language to retrieve
 * @returns Language definition object
 * @throws Error if language is not registered
 */
function requireLanguage(languageName: string): Language | never;

import hljs from "highlight.js/lib/core";

// Ensure required languages are loaded
try {
  const js = hljs.requireLanguage('javascript');
  const py = hljs.requireLanguage('python');
  console.log('All required languages loaded');
} catch (error) {
  console.error('Missing language:', error.message);
  // Load missing languages dynamically
}

// Fail fast if critical language missing
function highlightCode(code, language) {
  try {
    hljs.requireLanguage(language); // Throws if not available
    return hljs.highlight(code, {language});
  } catch (error) {
    throw new Error(`Language '${language}' not available: ${error.message}`);
  }
}

// Validation in configuration
const requiredLanguages = ['javascript', 'python', 'java'];
requiredLanguages.forEach(lang => {
  try {
    hljs.requireLanguage(lang);
  } catch (error) {
    throw new Error(`Configuration error: ${error.message}`);
  }
});

/**
 * Registers aliases for an existing language
 * @param aliasList - Single alias string or array of alias strings
 * @param options - Object containing the target language name
 */
function registerAliases(
  aliasList: string | string[], 
  {languageName}: {languageName: string}
): void;

import hljs from "highlight.js";

// Register single alias
hljs.registerAliases('js', {languageName: 'javascript'});
hljs.registerAliases('py', {languageName: 'python'});

// Register multiple aliases
hljs.registerAliases(['js', 'ecmascript', 'es6'], {languageName: 'javascript'});
hljs.registerAliases(['py', 'py3'], {languageName: 'python'});

// Common aliases for web languages
hljs.registerAliases(['htm'], {languageName: 'xml'}); // xml handles html
hljs.registerAliases(['scss', 'sass'], {languageName: 'css'});

// Custom alias registration
const aliasMap = {
  'javascript': ['js', 'jsx', 'ecmascript'],
  'typescript': ['ts', 'tsx'],
  'python': ['py', 'python3'],
  'shell': ['bash', 'sh', 'zsh']
};

Object.entries(aliasMap).forEach(([lang, aliases]) => {
  hljs.registerAliases(aliases, {languageName: lang});
});

/**
 * Checks if auto-detection is enabled for a language
 * @param languageName - Name of the language to check
 * @returns True if auto-detection is enabled, false otherwise
 */
function autoDetection(languageName: string): boolean;

import hljs from "highlight.js";

// Check which languages support auto-detection
const allLanguages = hljs.listLanguages();
const autoDetectLanguages = allLanguages.filter(lang => 
  hljs.autoDetection(lang)
);
console.log('Auto-detection enabled for:', autoDetectLanguages);

// Build subset for auto-detection
function getAutoDetectSubset(preferredLanguages) {
  return preferredLanguages.filter(lang => {
    return hljs.getLanguage(lang) && hljs.autoDetection(lang);
  });
}

// Conditional auto-detection
function smartHighlight(code, preferredLanguages = []) {
  const autoLanguages = preferredLanguages.filter(lang => 
    hljs.autoDetection(lang)
  );
  
  if (autoLanguages.length > 0) {
    return hljs.highlightAuto(code, autoLanguages);
  } else {
    return hljs.highlightAuto(code);
  }
}

// Load languages on demand
async function loadLanguage(languageName) {
  if (!hljs.getLanguage(languageName)) {
    try {
      const langModule = await import(`highlight.js/lib/languages/${languageName}`);
      hljs.registerLanguage(languageName, langModule.default);
      return true;
    } catch (error) {
      console.error(`Failed to load language ${languageName}:`, error);
      return false;
    }
  }
  return true;
}

// Usage
if (await loadLanguage('rust')) {
  const result = hljs.highlight(rustCode, {language: 'rust'});
}

// Define a simple custom language
function myLanguage(hljs) {
  return {
    name: 'MyLanguage',
    aliases: ['mylang', 'ml'],
    keywords: {
      keyword: 'if else while for function',
      built_in: 'print console log',
      literal: 'true false null'
    },
    contains: [
      hljs.QUOTE_STRING_MODE,
      hljs.C_LINE_COMMENT_MODE,
      hljs.C_NUMBER_MODE
    ]
  };
}

// Register custom language
hljs.registerLanguage('mylanguage', myLanguage);