Language Management

/**
 * Register a new language definition
 * @param languageName - Unique identifier for the language
 * @param languageDefinition - Function that returns language definition
 */
function registerLanguage(languageName: string, languageDefinition: LanguageFn): void;

type LanguageFn = (hljs: HLJSApi) => Language;

import hljs from 'highlight.js';

// Register a simple custom language
hljs.registerLanguage('mylang', function(hljs) {
  return {
    keywords: 'if else while for function',
    contains: [
      hljs.QUOTE_STRING_MODE,
      hljs.C_LINE_COMMENT_MODE,
      hljs.C_NUMBER_MODE
    ]
  };
});

// Register with advanced features
hljs.registerLanguage('advanced-lang', function(hljs) {
  return {
    aliases: ['adv', 'al'],
    case_insensitive: false,
    keywords: {
      keyword: 'def class if else while for try catch',
      built_in: 'print input len str int float',
      literal: 'true false null'
    },
    contains: [
      {
        className: 'string',
        begin: '"',
        end: '"',
        contains: [hljs.BACKSLASH_ESCAPE]
      },
      {
        className: 'comment',
        begin: '//',
        end: '$'
      },
      {
        className: 'number',
        begin: '\\b\\d+(\\.\\d+)?',
        relevance: 0
      },
      {
        className: 'function',
        beginKeywords: 'def',
        end: ':',
        contains: [
          {
            className: 'title',
            begin: '[a-zA-Z_][a-zA-Z0-9_]*'
          }
        ]
      }
    ]
  };
});

// Load language from external module
import customLang from './my-custom-language.js';
hljs.registerLanguage('custom', customLang);

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

// Remove a language
hljs.unregisterLanguage('brainfuck');

// Remove custom language
hljs.unregisterLanguage('mylang');

// Clean up unused languages to reduce memory
const unusedLanguages = ['cobol', 'fortran', 'ada'];
unusedLanguages.forEach(lang => {
  hljs.unregisterLanguage(lang);
});

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

// Get all available languages
const languages = hljs.listLanguages();
console.log('Supported languages:', languages);
// Output: ['javascript', 'python', 'html', 'css', ...]

// Check language availability
function isLanguageSupported(lang) {
  return hljs.listLanguages().includes(lang);
}

// Filter by category
const webLanguages = hljs.listLanguages().filter(lang => 
  ['html', 'css', 'javascript', 'typescript', 'scss', 'less'].includes(lang)
);

// Dynamic language selection UI
function createLanguageSelector() {
  const select = document.createElement('select');
  const languages = hljs.listLanguages().sort();
  
  languages.forEach(lang => {
    const option = document.createElement('option');
    option.value = lang;
    option.textContent = lang;
    select.appendChild(option);
  });
  
  return select;
}

/**
 * Get language definition by name
 * @param name - Language name or alias
 * @returns Language definition or undefined if not found
 */
function getLanguage(name: string): Language | undefined;

// Get language definition
const jsLang = hljs.getLanguage('javascript');
if (jsLang) {
  console.log('JavaScript aliases:', jsLang.aliases);
  console.log('Case insensitive:', jsLang.case_insensitive);
  console.log('Auto-detection:', !jsLang.disableAutodetect);
}

// Check language features
function checkLanguageFeatures(langName) {
  const lang = hljs.getLanguage(langName);
  if (!lang) {
    console.log(`Language ${langName} not found`);
    return;
  }
  
  return {
    hasAliases: lang.aliases && lang.aliases.length > 0,
    caseInsensitive: lang.case_insensitive || false,
    autoDetectable: !lang.disableAutodetect,
    hasKeywords: !!lang.keywords,
    modeCount: lang.contains ? lang.contains.length : 0
  };
}

// Inspect language capabilities
const pythonInfo = checkLanguageFeatures('python');
console.log('Python language info:', pythonInfo);

/**
 * Register language aliases
 * @param aliasList - String or array of alias names
 * @param options - Configuration with target language name
 */
function registerAliases(aliasList: string | string[], options: {languageName: string}): void;

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

// Register multiple aliases
hljs.registerAliases(['py', 'python3'], { languageName: 'python' });

// Register aliases for custom languages
hljs.registerLanguage('mylang', myLanguageDefinition);
hljs.registerAliases(['ml', 'custom'], { languageName: 'mylang' });

// Common alias registrations
const aliasMap = {
  'javascript': ['js', 'jsx', 'mjs'],
  'typescript': ['ts', 'tsx'],
  'python': ['py', 'python3'],
  'markdown': ['md', 'mkd'],
  'yaml': ['yml'],
  'shell': ['sh', 'bash', 'zsh']
};

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

/**
 * Check if language has auto-detection enabled
 * @param languageName - Language name to check
 * @returns Whether auto-detection is available
 */
function autoDetection(languageName: string): boolean;

// Check single language
if (hljs.autoDetection('javascript')) {
  console.log('JavaScript supports auto-detection');
}

// Filter auto-detectable languages
const allLanguages = hljs.listLanguages();
const autoDetectable = allLanguages.filter(lang => hljs.autoDetection(lang));
console.log('Auto-detectable languages:', autoDetectable);

// Optimization: prefer manual detection for non-auto-detectable languages
function smartHighlight(code, suggestedLanguage) {
  if (suggestedLanguage && hljs.getLanguage(suggestedLanguage)) {
    return hljs.highlight(code, { language: suggestedLanguage });
  } else if (autoDetectable.length > 0) {
    return hljs.highlightAuto(code, autoDetectable);
  } else {
    return hljs.highlightAuto(code);
  }
}

interface Language {
  /** Language display name */
  name?: string;
  
  /** Alternative names for the language */
  aliases?: string[];
  
  /** Disable automatic language detection */
  disableAutodetect?: boolean;
  
  /** Array of mode definitions */
  contains: Mode[];
  
  /** Case-insensitive keyword matching */
  case_insensitive?: boolean;
  
  /** Keywords definition */
  keywords?: string | string[] | Record<string, string | string[]>;
  
  /** Whether language definition is compiled */
  isCompiled?: boolean;
  
  /** Exported utilities from language definition */
  exports?: any;
  
  /** CSS class name aliases */
  classNameAliases?: Record<string, string>;
  
  /** Compiler extensions */
  compilerExtensions?: CompilerExt[];
  
  /** Parent language this is a subset of */
  supersetOf?: string;
}

interface Mode {
  /** Pattern to match beginning of mode */
  begin?: RegExp | string | (RegExp | string)[];
  
  /** Pattern to match end of mode */
  end?: RegExp | string | (RegExp | string)[];
  
  /** CSS scope/class name */
  scope?: string;
  
  /** Sub-modes contained within this mode */
  contains?: ('self' | Mode)[];
  
  /** Keywords for this mode */
  keywords?: string | string[] | Record<string, string | string[]>;
  
  /** Relevance score for this mode */
  relevance?: number;
  
  /** Illegal patterns that invalidate this mode */
  illegal?: string | RegExp | Array<string | RegExp>;
  
  /** Various other mode options... */
  excludeBegin?: boolean;
  excludeEnd?: boolean;
  returnBegin?: boolean;
  returnEnd?: boolean;
  endsWithParent?: boolean;
  endsParent?: boolean;
}