#!/usr/bin/env python3
 
 
 ## Help
 """
 glregistry 1.0
 
 Cache and query the OpenGL registry locally.
 
 Usage:
   glregistry xml
   glregistry xml-path
   glregistry ext            <extension>
   glregistry ext-path       <extension>
   glregistry exts
   glregistry exts-download
   glregistry exts-all       <name>

   glregistry vendors

   glregistry type           <type>

   glregistry aliases        <enum>

   glregistry value          <enum>
   glregistry enum           <value>
   glregistry supports       <name>
   glregistry names          [<support>]
   glregistry groups         [<enum>]
   glregistry enums          [<group>]
   glregistry enums-tree     [<group>]
   glregistry params         [<group>]
   glregistry params-tree    [<group>]
   glregistry audit          [<path>]
   glregistry audit-tree     [<path>]

   glregistry refs           <name>
   glregistry refs-all       <name>

   glregistry -h|--help
 
 Commands:
   xml
     Download the registry XML and open it with an editor.
   xml-path
     Download the registry XML and print its local path.
   ext <extension>
     Download the <extension> spec and open it with an editor.
   ext-path <extension>
     Download the <extension> spec and print its local path.
   exts
     Print the names of all extension specs.
   exts-download
     Download all extension specs.
   exts-all <name>
     Print all downloaded extensions that mention <name>.

   vendors
     Print all vendor abbreviations.

   type <type>
     Print the definition of <type>.

   aliases <enum>
     Print the KHR, ARB, and EXT aliases of <enum>.

   value <enum>
     Print the value of <enum>.
   enum <value>

     Print the enum(s) that has the given <value>.

   supports <name>
     Print the OpenGL version or extension required to use <name>.
   names [<support>]
     Print the names introduced by the OpenGL version or extension <support> if
     given, or all names if omitted. The special values VERSION and EXTENSION
     print the names introduced by all versions or all extensions respectively.
   groups [<enum>]
     Print the groups of <enum> if given, or all groups if omitted.
   enums [<group>]
     Print the enums in <group> if given, or all enums if omitted.
   enums-tree [<group>]
     Print the enums in <group> if given, or all enums if omitted, sorted on
     support, in a tree.
   params [<group>]
     Print the parameter names of <group> if given, or all parameter names if
     omitted.
   params-tree [<group>]
     Print the parameter names of <group> if given, or all parameter names if
     omitted, sorted on count, together with the commands sorted on support, in
     a tree.
   audit [<path>]
     Search files in <path> if given, or the current directory if omitted,
     recursively for OpenGL API names and print them sorted on location,
     support, and name, in a list.
   audit-tree [<path>]
     Search files in <path> if given, or the current directory if omitted,
     recursively for OpenGL API names and print them sorted on support, name,
     and location, in a tree.

   refs <name>
     Print all URLs of all reference pages with name <name>.
   refs-all <name>
     Print all URLs of all reference pages that mention <name>, sorted on
     support, in a tree.

 
 Environment variables:
   GLREGISTRY_CACHE
     The directory to cache files in. Defaults to `$XDG_CACHE_HOME/glregistry`
     or, if `$XDG_CACHE_HOME` is not defined, `$HOME/.cache/glregistry`.
   GLREGISTRY_EDITOR
     The editor to use when opening files. Defaults to `$EDITOR` or, if
     `$EDITOR` is not defined, `editor` if it exists in `$PATH`, else `vi`. The
     value is interpreted by the shell.
   GLREGISTRY_PAGER
     The pager to use when viewing output. Defaults to `$PAGER` or, if `$PAGER`
     is not defined, `pager` if it exists in `$PATH`, else `less` . The value is
     interpreted by the shell. If the `$LESS` environment variable is unset, it
     is set to `FR`.

   GLREGISTRY_COLORS
     If standard out is a terminal, the colors used in output of the `enums`,
     `enums-tree`, `params`, `params-tree`, `audit,` and `audit-tree` commands.
     It uses the same format (and defaults) as GREP_COLORS, i.e. a
     colon-separated list of capabilties: `ms` (matching selected), `fn` (file

     name), `ln` (line and column number), `se` (separators). Added custom
     capabilities are: `ve` (version), `ex` (extension), `un` (unsupported).
     Defaults to `ms=01;31:fn=35:ln=32:se=36:ve=01;34:ex=34:un=01;33`.

 """
 
 
 ## Imports
 import os
 import sys
 import collections
 import re

 import functools

 import subprocess
 import shutil
 import shlex

 import fnmatch

 import urllib.request
 import docopt
 from lxml import etree
 
 
 ## Constants

 REFPAGES_URL  = 'https://registry.khronos.org/OpenGL-Refpages/'

 REGISTRY_URL  = 'https://github.com/KhronosGroup/OpenGL-Registry/raw/main/'

 REFPAGES_GIT  = 'https://github.com/KhronosGroup/OpenGL-Refpages'

 XML_PATH      = 'xml/gl.xml'

 USER_AGENT    = 'Mozilla/5.0'

 REGEX         = r'\b(gl|GL_)[0-9A-Z][0-9A-Za-z_]+\b'
 EXCLUDE_DIRS  = ['.?*', '_*']
 EXCLUDE_FILES = ['README*', 'TODO*']

 BINARY_PEEK   = 1024

 INDENT        = 2
 ENV_XDG = lambda var, default: (
     os.environ.get(f'GLREGISTRY_{var}') or
     os.path.join(
         (
             os.environ.get(f'XDG_{var}_HOME') or
             os.path.expanduser(default)
         ),
         'glregistry',
     )
 )
 ENV_PRG = lambda var, default: (
     os.environ.get(f'GLREGISTRY_{var}') or
     os.environ.get(var) or
     shutil.which(var.lower()) or
     default
 )
 CACHE  = ENV_XDG('CACHE',  os.path.join('~', '.cache'))
 EDITOR = ENV_PRG('EDITOR', 'vi')
 PAGER  = ENV_PRG('PAGER',  'less')
 LESS   = os.environ.get('LESS') or 'FR'

 COLORS = collections.defaultdict(str, [
     (color.split('=') + [''])[:2]
     for color in
     filter(None, (
         os.environ.get('GLREGISTRY_COLORS') or
         (lambda x, y: ':'.join([x, x and y]))(
             (
                 os.environ.get('GREP_COLORS') or
                 'ms=01;31:fn=35:ln=32:se=36'
             ),
             've=01;34:ex=34:un=01;33',
         )
     ).split(':'))
 ])

 IN    = lambda a, v, s: f"contains(concat('{s}',@{a},'{s}'),'{s}{v}{s}')"
 MAYBE = lambda a, v:    f"(@{a}='{v}' or not(@{a}))"
 TYPES    = "/registry/types"
 ENUMS    = "/registry/enums"
 COMMANDS = "/registry/commands"
 CATEGORY_ATTRIBS = {
     'VERSION': [
         "/registry/feature[@api='gl']",
         'number',
     ],
     'EXTENSION': [
         f"/registry/extensions/extension[{IN('supported','gl','|')}]",
         'name',
     ],
 }
 REQUIRE = f"require[{MAYBE('api','gl')} and {MAYBE('profile','core')}]"

 REMOVE  = f"remove[{ MAYBE('api','gl')} and {MAYBE('profile','core')}]"
 CHANGE_PREFIXES = [
     [REQUIRE, '' ],
     [REMOVE,  '<'],
 ]

 VENDORS = ['KHR', 'ARB', 'EXT']

 KEY_SUBS = [

     *[[f'^{   prefix}',  f''       ] for _, prefix in CHANGE_PREFIXES],
     *[[f'{    vendor}$', f'{   i}' ] for i, vendor in enumerate(VENDORS)],
     *[[f'^GL_{vendor}_', f'GL_{i}_'] for i, vendor in enumerate(VENDORS)],

 ]

 
 
 ## Helpers
 
 
 ### `log`
 def log(*args, **kwargs):
     print(*args, file=sys.stderr, flush=True, **kwargs)
 
 
 ### `edit`
 def edit(paths):
     if EDITOR and sys.stdout.isatty():
         args = ' '.join([EDITOR, *map(shlex.quote, paths)])
         subprocess.run(args, shell=True)
     else:
         for path in paths:
             with open(path) as f:
                 shutil.copyfileobj(f, sys.stdout)
 
 
 ### `page`
 def page(lines):
     lines = ''.join(f'{line}\n' for line in lines)
     if lines and PAGER and sys.stdout.isatty():
         args = f'LESS={shlex.quote(LESS)} {PAGER}'
         subprocess.run(args, shell=True, text=True, input=lines)
     else:
         sys.stdout.write(lines)
 
 

 ### `color`
 def color(capability, string):
     if not sys.stdout.isatty():
         return string
     return f'\x1b[{COLORS[capability]}m{string}\x1b[m'
 
 
 ### `color_supports`
 def color_supports(supports):
     for support in supports:
         if support == 'UNSUPPORTED' or support.startswith('<'):
             yield color('un', support)
         elif support.startswith('GL_'):
             yield color('ex', support)
         else:
             yield color('ve', support)
 
 

 ### `indentjoin`
 def indentjoin(indent, sep, parts):

     return ' ' * INDENT * indent + color('se', sep).join(map(str, parts))

 
 
 ### `removeprefix`
 def removeprefix(prefix, string):
     if string.startswith(prefix):
         return string[len(prefix):]
     return string
 
 

 ### `key`
 def key(item):
     for sub in KEY_SUBS:
         item = re.sub(*sub, item)
     return item
 
 

 ### `download`
 def download(path, exit_on_failure=True):
     remote = urllib.parse.urljoin(REGISTRY_URL, path)
     local  = os.path.join        (CACHE,        path)
     if not os.path.exists(local):
         try:
             log(f"Downloading '{path}' ... ", end='')
             with urllib.request.urlopen(remote) as response:
                 os.makedirs(os.path.dirname(local), exist_ok=True)
                 with open(local, 'wb') as f:
                     shutil.copyfileobj(response, f)
         except urllib.error.URLError as error:
             log(error.reason)
             if exit_on_failure:
                 exit(1)
         else:
             log(response.reason)
     return local
 
 
 ### `grep`
 def grep(
     path=None,
     regex=REGEX,
     exclude_dirs=EXCLUDE_DIRS,
     exclude_files=EXCLUDE_FILES,
     silent=False,
 ):

     path = path if path else '.'
     def onerror(error, file=None):
         file = removeprefix(f'.{os.path.sep}', file or error.filename)
         if silent:
             pass
         elif isinstance(error, OSError):
             log(f"{file}: {error.strerror}")
         elif isinstance(error, UnicodeDecodeError):
             log(f"{file}: {error.reason}")
         else:
             log(f"{file}: {error}")
     def exclude(excludes, names):
         names = set(names)
         for exclude in excludes:
             names -= set(fnmatch.filter(names, exclude))
         return sorted(names)
     def grep_file(file):
         try:
             with open(file, 'rb') as f:
                 if 0 in f.read(BINARY_PEEK):
                     return
             with open(file, errors='ignore') as f:
                 file = removeprefix(f'.{os.path.sep}', file)
                 for line, string in enumerate(f):
                     for match in re.finditer(regex, string):
                         column, name = match.start(), match.group()
                         yield file, line+1, column+1, name
         except Exception as error:
             onerror(error, file)
     if os.path.isfile(path):
         for match in grep_file(path):
             yield match
     else:
         for root, dirs, files in os.walk(path, onerror=onerror):
             dirs [:] = exclude(exclude_dirs,  dirs)
             files[:] = exclude(exclude_files, files)
             for file in files:
                 for match in grep_file(os.path.join(root, file)):
                     yield match

 
 
 ## Commands
 
 
 ### `xml_`
 def xml_():
     return etree.parse(download(XML_PATH))
 
 
 ### `xml`
 def xml():
     return [download(XML_PATH)]
 
 
 ### `ext_`
 def ext_(extension):
     prefix, vendor, name = extension.split('_', 2)
     if prefix != 'GL':
         log("Extension names must start with 'GL_'.")
         exit(1)
     return f'extensions/{vendor}/{vendor}_{name}.txt'
 
 
 ### `ext`
 def ext(extension):
     return [download(ext_(extension))]
 
 
 ### `exts`
 def exts(xml):
     category, attrib = CATEGORY_ATTRIBS['EXTENSION']
     exts = xml.xpath(f"{category}/@{attrib}")

     return sorted(exts, key=key)

 
 
 ### `exts_download`
 def exts_download(xml):
     for ext in exts(xml):
         download(ext_(ext), exit_on_failure=False)
     return []
 
 
 ### `exts_all`
 def exts_all(xml, name):
     # exts_download(xml)
     exts_all = set(
         'GL_' + os.path.splitext(os.path.basename(file))[0]
         for name in set([
             name,
             removeprefix('gl',  name),
             removeprefix('GL_', name),
         ])
         for file, *_ in
         grep(os.path.join(CACHE, 'extensions'), rf'\b{name}\b', [], [])
     )

     return sorted(exts_all, key=key)
 
 
 ### `vendors`
 def vendors(xml):
     vendors = set(extension.split('_')[1] for extension in exts(xml))
     return sorted(vendors, key=key)

 
 
 ### `type`
 def type(xml, type):
     return [xml.xpath(f"string({TYPES}/type/name[text()='{type}']/..)")]
 
 

 ### `aliases`
 def aliases(xml, name, supports_=None, vendors_=[]):
     if not vendors_:
         vendors_[:] = vendors(xml)
     for vendor in vendors_:
         if name.endswith(f'_{vendor}'):
             return []
     value_  = value(xml, name)
     if not value_:
         return []
     if not supports_:
         supports_ = supports(xml, name, False)
     if not supports_:
         return []
     aliases = []
     # for vendor in vendors_:
     for vendor in VENDORS:
         alias = f'{name}_{vendor}'
         if supports(xml, alias, False) and value(xml, alias) == value_:
             aliases.append(alias)
     return sorted(aliases, key=key)
 
 

 ### `value`
 def value(xml, enum):
     return xml.xpath(f"{ENUMS}/enum[@name='{enum}']/@value")
 
 
 ### `enum`
 def enum(xml, value):

     def conv(s):
         return int(s, 16 if s.startswith('0x') else 10)
     value = conv(value)
     enum = (
         enum.get('name')
         for enum in xml.xpath(f"{ENUMS}/enum")
         if conv(enum.get('value')) == value
     )

     return sorted(enum, key=key)

 
 
 ### `supports`

 @functools.cache

 def supports(xml, name, use_aliases=True):

     category, attrib = CATEGORY_ATTRIBS['EXTENSION']
     if xml.xpath(f"{category}[@{attrib}='{name}']"):
         return ['EXTENSION']
     supports_ = [

         f'{prefix}{support}'

         for category, attrib in CATEGORY_ATTRIBS.values()

         for change, prefix   in CHANGE_PREFIXES

         for support in

         xml.xpath(f"{category}/{change}/*[@name='{name}']/../../@{attrib}")

     ]

     if supports_ and use_aliases:
         supports_.extend(
             support
             for alias   in aliases (xml, name, supports_)
             for support in supports(xml, alias, False)
         )

     return sorted(supports_, key=key)

 
 
 ### `names`
 def names(xml, support=None):
     if support in CATEGORY_ATTRIBS.keys():
         category_attribs = [
             [category, ""]
             for category, _ in [CATEGORY_ATTRIBS[support]]
         ]
     elif support:
         category_attribs = [
             [category, f"[@{attrib}='{support}']"]
             for category, attrib in CATEGORY_ATTRIBS.values()
         ]
     else:
         category_attribs = [
             [category, ""]
             for category, _ in CATEGORY_ATTRIBS.values()
         ]
     names = set(
         name
         for category, attrib in category_attribs
         for name in
         xml.xpath(f"{category}{attrib}/{REQUIRE}/*/@name")
     )

     return sorted(names, key=key)

 
 
 ### `groups`
 def groups(xml, enum=None):
     name = f"[@name='{enum}']" if enum else ""
     return sorted(set(
         group
         for groups in xml.xpath(f"{ENUMS}/enum{name}/@group")
         for group  in groups.split(',')
     ))
 
 
 ### `enums_`
 def enums_(xml, group=None):
     group = f"[{IN('group',group,',')}]" if group else ""
     enums_ = collections.defaultdict(list)
     for enum in xml.xpath(f"{ENUMS}/enum{group}/@name"):
         supports_ = supports(xml, enum)
         if supports_:
             enums_[tuple(supports_)].append(enum)
     return enums_
 
 
 ### `enums`
 def enums(xml, group=None):
     enums = [
         enum
         for _, enums in enums_(xml, group).items()
         for enum     in enums
     ]

     return sorted(enums, key=key)

 
 
 ### `enums_tree`
 def enums_tree(xml, group=None):
     for supports, enums in sorted(enums_(xml, group).items()):

         yield indentjoin(0, ',', color_supports(supports))

         for enum in sorted(enums):

             yield indentjoin(1, '', [color('ms', enum)])

 
 
 ### `params_`
 def params_(xml, group=None):
     group   = f"[@group='{group}']" if group else ""
     counts  = collections.defaultdict(int)
     params_ = collections.defaultdict(lambda: collections.defaultdict(list))
     for xmlcommand in xml.xpath(f"{COMMANDS}/command/param{group}/.."):
         command   = xmlcommand.xpath(f"string(proto/name)")
         supports_ = supports(xml, command)
         if supports_:
             for xmlparam in xmlcommand.xpath(f"param{group}"):
                 param = xmlparam.xpath(f"string(name)")
                 params_[param][tuple(supports_)].append(command)
                 counts[param] -= 1
     return {
         (count, param): params_[param]
         for param, count in counts.items()
     }
 
 
 ### `params`
 def params(xml, group=None):
     params = [param for (_, param), _ in params_(xml, group).items()]
     return sorted(params)
 
 
 ### `params_tree`
 def params_tree(xml, group=None):
     for (count, param), occurences in sorted(params_(xml, group).items()):
         yield indentjoin(0, ':', [

             color('ms', param),
             color('ln', -count),

         ])
         for supports_, commands in sorted(occurences.items()):

             yield indentjoin(1, ',', color_supports(supports_))

             for command in sorted(commands):

                 yield indentjoin(2, '', [color('fn', command)])

 
 
 ### `audit_`
 def audit_(xml, path=None):
     audit_ = collections.defaultdict(lambda: collections.defaultdict(list))

     for file, line, column, name in grep(path):

         supports_ = supports(xml, name)
         if not supports_:
             supports_ = ['UNSUPPORTED']

         audit_[tuple(supports_)][name].append([file, line, column])

     return audit_
 
 
 ### `audit`
 def audit(xml, path=None):

     for file, line, column, supports, name in sorted(
         [file, line, column, supports, name]
         for supports, names    in audit_(xml, path).items()
         for name, locations    in names.items()
         for file, line, column in locations

     ):
         yield indentjoin(0, ':', [

             color('fn', file),
             color('ln', line),

             color('ln', column),

             indentjoin(0, ',', color_supports(supports)),
             color('ms', name),

         ])
 
 
 ### `audit_tree`
 def audit_tree(xml, path=None):
     for supports, names in sorted(audit_(xml, path).items()):

         yield indentjoin(0, ',', color_supports(supports))

         for name, locations in sorted(names.items()):

             yield indentjoin(1, '', [color('ms', name)])

             for file, line, column in sorted(locations):

                 yield indentjoin(2, ':', [

                     color('fn', file),
                     color('ln', line),

                     color('ln', column),

                 ])
 
 

 ### `refs_`
 def refs_(name):
     local = os.path.join(CACHE, os.path.basename(REFPAGES_GIT))
     if not os.path.exists(local):
         os.makedirs(os.path.dirname(local), exist_ok=True)
         subprocess.run(['git', 'clone', REFPAGES_GIT, local])
     refs_ = collections.defaultdict(set)
     for file, *_ in grep(local, rf'\b{name}\b', [], [], True):
         file = removeprefix(f'{local}{os.path.sep}', file)
         try:
             support, *_, dir, base = os.path.normpath(file).split(os.path.sep)
         except:
             continue
         if support.startswith('gl') and dir.endswith('html'):
             support   = removeprefix('gl', support)
             name, ext = os.path.splitext(base)
             url       = urllib.parse.urljoin(REFPAGES_URL, file)
             if ext in ['.xml', '.xhtml']:
                 refs_[support].add((name, url))
     return refs_
 
 
 ### `refs`
 def refs(name):
     return sorted(
         url
         for support, locations in refs_(name).items()
         for name_, url         in locations
         if name_ == name
     )
 
 
 ### `refs_all`
 def refs_all(name):
     for support, locations in sorted(refs_(name).items()):

         yield indentjoin(0, ',', color_supports([support]))

         for name_, url in sorted(locations):
             yield indentjoin(1, ':', [

                 color('ms', name_),
                 color('fn', url),

             ])
 
 

 ## Main
 def main():

     opener = urllib.request.build_opener()
     opener.addheaders = [('User-Agent', USER_AGENT)]
     urllib.request.install_opener(opener)

     args = docopt.docopt(__doc__)
     if args['xml']:           edit(xml          ())
     if args['xml-path']:      page(xml          ())
     if args['ext']:           edit(ext          (args['<extension>']))
     if args['ext-path']:      page(ext          (args['<extension>']))
     if args['exts']:          page(exts         (xml_()))
     if args['exts-download']: page(exts_download(xml_()))
     if args['exts-all']:      page(exts_all     (xml_(), args['<name>']))

     if args['vendors']:       page(vendors      (xml_()))

     if args['type']:          page(type         (xml_(), args['<type>']))

     if args['aliases']:       page(aliases      (xml_(), args['<enum>']))

     if args['value']:         page(value        (xml_(), args['<enum>']))
     if args['enum']:          page(enum         (xml_(), args['<value>']))
     if args['supports']:      page(supports     (xml_(), args['<name>']))
     if args['names']:         page(names        (xml_(), args['<support>']))
     if args['groups']:        page(groups       (xml_(), args['<enum>']))
     if args['enums']:         page(enums        (xml_(), args['<group>']))
     if args['enums-tree']:    page(enums_tree   (xml_(), args['<group>']))
     if args['params']:        page(params       (xml_(), args['<group>']))
     if args['params-tree']:   page(params_tree  (xml_(), args['<group>']))
     if args['audit']:         page(audit        (xml_(), args['<path>']))
     if args['audit-tree']:    page(audit_tree   (xml_(), args['<path>']))

     if args['refs']:          page(refs         (args['<name>']))
     if args['refs-all']:      page(refs_all     (args['<name>']))

 
 
 if __name__ == '__main__':
     main()