1. rcrnstn/glregistry
  2. README.md
Browse code

Add readme example

Robert Cranston authored on 12/02/2023 18:51:14
Showing 1 changed files
README.md
History View file @ b76b386
... ... 
@@ -158,6 +158,48 @@ Environment variables:
158 158 
     Defaults to `ms=01;31:fn=35:ln=32:se=36:ve=01;34:ex=34:un=01;33`.
159 159 
 ```
160 160
161 
+## Examples
162 
+
163 
+The following example demonstrates exploring the OpenGL API starting from code
164 
+in a repository.
165 
+
166 
+```
167 
+$ glregistry audit-tree example-repo
168 
+4.6,GL_ARB_texture_filter_anisotropic,GL_EXT_texture_filter_anisotropic
169 
+  GL_TEXTURE_MAX_ANISOTROPY
170 
+    src/gltexture.cpp:3:17
171 
+
172 
+$ glregistry exts-all GL_TEXTURE_MAX_ANISOTROPY
173 
+GL_ARB_sampler_objects
174 
+GL_ARB_texture_filter_anisotropic
175 
+GL_EXT_texture_filter_anisotropic
176 
+
177 
+$ glregistry groups GL_TEXTURE_MAX_ANISOTROPY
178 
+SamplerParameterF
179 
+TextureParameterName
180 
+
181 
+$ glregistry enums-tree SamplerParameterF
182 
+1.0
183 
+  GL_TEXTURE_BORDER_COLOR
184 
+1.2
185 
+  GL_TEXTURE_MAX_LOD
186 
+  GL_TEXTURE_MIN_LOD
187 
+1.4,GL_EXT_texture_lod_bias
188 
+  GL_TEXTURE_LOD_BIAS
189 
+4.6,GL_ARB_texture_filter_anisotropic,GL_EXT_texture_filter_anisotropic
190 
+  GL_TEXTURE_MAX_ANISOTROPY
191 
+
192 
+$ glregistry params-tree SamplerParameterF
193 
+pname:3
194 
+  3.3,GL_ARB_sampler_objects
195 
+    glGetSamplerParameterfv
196 
+    glSamplerParameterf
197 
+    glSamplerParameterfv
198 
+
199 
+$ glregistry refs glSamplerParameter
200 
+https://registry.khronos.org/OpenGL-Refpages/gl4/html/glSamplerParameter.xhtml
201 
+```
202 
+
161 203 
 ## References
162 204
163 205 
 Note that some of these might be out of date.
Browse code

Change grep to internal

Robert Cranston authored on 22/01/2023 00:33:32
Showing 1 changed files
README.md
History View file @ 3aff6da
... ... 
@@ -153,9 +153,9 @@ Environment variables:
153 153 
     `enums-tree`, `params`, `params-tree`, `audit,` and `audit-tree` commands.
154 154 
     It uses the same format (and defaults) as GREP_COLORS, i.e. a
155 155 
     colon-separated list of capabilties: `ms` (matching selected), `fn` (file
156 
-    name), `ln` (line number), `se` (separators). Added custom capabilities
157 
-    are: `ve` (version), `ex` (extension), `un` (unsupported). Defaults to
158 
-    `ms=01;31:fn=35:ln=32:se=36:ve=01;34:ex=34:un=01;33`.
156 
+    name), `ln` (line and column number), `se` (separators). Added custom
157 
+    capabilities are: `ve` (version), `ex` (extension), `un` (unsupported).
158 
+    Defaults to `ms=01;31:fn=35:ln=32:se=36:ve=01;34:ex=34:un=01;33`.
159 159 
 ```
160 160
161 161 
 ## References
Browse code

Change enum to be number format agnostic

Robert Cranston authored on 16/09/2023 17:40:57
Showing 1 changed files
README.md
History View file @ 6248f9b
... ... 
@@ -100,7 +100,7 @@ Commands:
100 100 
   value <enum>
101 101 
     Print the value of <enum>.
102 102 
   enum <value>
103 
-    Print the enum(s) that has the given <value>, using exact string matching.
103 
+    Print the enum(s) that has the given <value>.
104 104 
   supports <name>
105 105 
     Print the OpenGL version or extension required to use <name>.
106 106 
   names [<support>]
Browse code

Add colors

Robert Cranston authored on 11/01/2023 14:29:21
Showing 1 changed files
README.md
History View file @ 320a682
... ... 
@@ -148,6 +148,14 @@ Environment variables:
148 148 
     is not defined, `pager` if it exists in `$PATH`, else `less` . The value is
149 149 
     interpreted by the shell. If the `$LESS` environment variable is unset, it
150 150 
     is set to `FR`.
151 
+  GLREGISTRY_COLORS
152 
+    If standard out is a terminal, the colors used in output of the `enums`,
153 
+    `enums-tree`, `params`, `params-tree`, `audit,` and `audit-tree` commands.
154 
+    It uses the same format (and defaults) as GREP_COLORS, i.e. a
155 
+    colon-separated list of capabilties: `ms` (matching selected), `fn` (file
156 
+    name), `ln` (line number), `se` (separators). Added custom capabilities
157 
+    are: `ve` (version), `ex` (extension), `un` (unsupported). Defaults to
158 
+    `ms=01;31:fn=35:ln=32:se=36:ve=01;34:ex=34:un=01;33`.
151 159 
 ```
152 160
153 161 
 ## References
Browse code

Add vendors

Robert Cranston authored on 11/01/2023 14:29:12
Showing 1 changed files
README.md
History View file @ 034e094
... ... 
@@ -13,6 +13,12 @@ appropriate each line is in a widely supported format, usable with e.g.
13 13 
 -q`][]` <(glregistry audit)`) and [GNU Emacs][]' [Compilation Mode][] ([`M-x
14 14 
 compile`][]` glregistry audit`).
15 15
16 
+The vendors `KHR` (Khronos), `ARB` (Architecture Review Board), and `EXT`
17 
+(Extension) are treated specially and are sorted before other vendors. When
18 
+querying for enums, either directly or indirectly, enums with the same name,
19 
+except for one of these vendors added as a suffix, and the same value is
20 
+matched as well.
21 
+
16 22 
 Note that only the OpenGL (not OpenGL ES) API, and only the core (not
17 23 
 compatibility) [profile][] is considered.
18 24
... ... 
@@ -52,7 +58,9 @@ Usage:
52 58 
   glregistry exts
53 59 
   glregistry exts-download
54 60 
   glregistry exts-all       <name>
61 
+  glregistry vendors
55 62 
   glregistry type           <type>
63 
+  glregistry aliases        <enum>
56 64 
   glregistry value          <enum>
57 65 
   glregistry enum           <value>
58 66 
   glregistry supports       <name>
... ... 
@@ -83,8 +91,12 @@ Commands:
83 91 
     Download all extension specs.
84 92 
   exts-all <name>
85 93 
     Print all downloaded extensions that mention <name>.
94 
+  vendors
95 
+    Print all vendor abbreviations.
86 96 
   type <type>
87 97 
     Print the definition of <type>.
98 
+  aliases <enum>
99 
+    Print the KHR, ARB, and EXT aliases of <enum>.
88 100 
   value <enum>
89 101 
     Print the value of <enum>.
90 102 
   enum <value>
Browse code

Add refs

Robert Cranston authored on 16/02/2023 02:22:15
Showing 1 changed files
README.md
History View file @ 295d1b6
... ... 
@@ -64,6 +64,8 @@ Usage:
64 64 
   glregistry params-tree    [<group>]
65 65 
   glregistry audit          [<path>]
66 66 
   glregistry audit-tree     [<path>]
67 
+  glregistry refs           <name>
68 
+  glregistry refs-all       <name>
67 69 
   glregistry -h|--help
68 70
69 71 
 Commands:
... ... 
@@ -115,6 +117,11 @@ Commands:
115 117 
     Search files in <path> if given, or the current directory if omitted,
116 118 
     recursively for OpenGL API names and print them sorted on support, name,
117 119 
     and location, in a tree.
120 
+  refs <name>
121 
+    Print the URLs of all reference pages with name <name>.
122 
+  refs-all <name>
123 
+    Print the URLs of all reference pages that mention <name>, sorted on
124 
+    support, in a tree.
118 125
119 126 
 Environment variables:
120 127 
   GLREGISTRY_CACHE
Browse code

Add implementation

Robert Cranston authored on 11/03/2022 20:46:26
Showing 1 changed files
README.md
History View file @ 3969d95
... ... 
@@ -2,9 +2,154 @@
2 2
3 3 
 Cache and query the [OpenGL][] [registry][] locally.
4 4
5 
+`glregistry` is a Python program that glues together [HTTPS][] downloading,
6 
+[XPath][] querying, data accumulation/sorting, [`grep`][]ing, [color][] output,
7 
+and launching external [editor][]/[pager][] programs.
8 
+
9 
+It tries to be a good Unix citizen by obeying relevant environment variables
10 
+and being [pipe][]-friendly, outputting newline-separated entries. Where
11 
+appropriate each line is in a widely supported format, usable with e.g.
12 
+[Vim][]'s [QuickFix][] ([`:cexpr`][]` system('glregistry audit')` or [`vim
13 
+-q`][]` <(glregistry audit)`) and [GNU Emacs][]' [Compilation Mode][] ([`M-x
14 
+compile`][]` glregistry audit`).
15 
+
16 
+Note that only the OpenGL (not OpenGL ES) API, and only the core (not
17 
+compatibility) [profile][] is considered.
18 
+
5 19 
 [`glregistry`]: https://git.rcrnstn.net/rcrnstn/glregistry
6 20 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
7 21 
 [registry]: https://registry.khronos.org/OpenGL/
22 
+[HTTPS]: https://en.wikipedia.org/wiki/HTTPS
23 
+[XPath]: https://en.wikipedia.org/wiki/XPath
24 
+[`grep`]: https://en.wikipedia.org/wiki/Grep
25 
+[color]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
26 
+[editor]: https://en.wikipedia.org/wiki/Text_editor
27 
+[pager]: https://en.wikipedia.org/wiki/Terminal_pager
28 
+[pipe]: https://en.wikipedia.org/wiki/Pipeline_(Unix)
29 
+[Vim]: https://en.wikipedia.org/wiki/Vim_(text_editor)
30 
+[QuickFix]: https://vimhelp.org/quickfix.txt.html
31 
+[`:cexpr`]: https://vimhelp.org/quickfix.txt.html#%3Acexpr
32 
+[`vim -q`]: https://vimhelp.org/starting.txt.html#-q
33 
+[GNU Emacs]: https://en.wikipedia.org/wiki/GNU_Emacs
34 
+[Compilation Mode]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation-Mode.html
35 
+[`M-x compile`]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation.html#index-compile-2624
36 
+[profile]: https://www.khronos.org/opengl/wiki/OpenGL_Context#OpenGL_3.2_and_Profiles
37 
+
38 
+## Usage
39 
+
40 
+`glregistry --help`:
41 
+
42 
+```
43 
+glregistry 1.0
44 
+
45 
+Cache and query the OpenGL registry locally.
46 
+
47 
+Usage:
48 
+  glregistry xml
49 
+  glregistry xml-path
50 
+  glregistry ext            <extension>
51 
+  glregistry ext-path       <extension>
52 
+  glregistry exts
53 
+  glregistry exts-download
54 
+  glregistry exts-all       <name>
55 
+  glregistry type           <type>
56 
+  glregistry value          <enum>
57 
+  glregistry enum           <value>
58 
+  glregistry supports       <name>
59 
+  glregistry names          [<support>]
60 
+  glregistry groups         [<enum>]
61 
+  glregistry enums          [<group>]
62 
+  glregistry enums-tree     [<group>]
63 
+  glregistry params         [<group>]
64 
+  glregistry params-tree    [<group>]
65 
+  glregistry audit          [<path>]
66 
+  glregistry audit-tree     [<path>]
67 
+  glregistry -h|--help
68 
+
69 
+Commands:
70 
+  xml
71 
+    Download the registry XML and open it with an editor.
72 
+  xml-path
73 
+    Download the registry XML and print its local path.
74 
+  ext <extension>
75 
+    Download the <extension> spec and open it with an editor.
76 
+  ext-path <extension>
77 
+    Download the <extension> spec and print its local path.
78 
+  exts
79 
+    Print the names of all extension specs.
80 
+  exts-download
81 
+    Download all extension specs.
82 
+  exts-all <name>
83 
+    Print all downloaded extensions that mention <name>.
84 
+  type <type>
85 
+    Print the definition of <type>.
86 
+  value <enum>
87 
+    Print the value of <enum>.
88 
+  enum <value>
89 
+    Print the enum(s) that has the given <value>, using exact string matching.
90 
+  supports <name>
91 
+    Print the OpenGL version or extension required to use <name>.
92 
+  names [<support>]
93 
+    Print the names introduced by the OpenGL version or extension <support> if
94 
+    given, or all names if omitted. The special values VERSION and EXTENSION
95 
+    print the names introduced by all versions or all extensions respectively.
96 
+  groups [<enum>]
97 
+    Print the groups of <enum> if given, or all groups if omitted.
98 
+  enums [<group>]
99 
+    Print the enums in <group> if given, or all enums if omitted.
100 
+  enums-tree [<group>]
101 
+    Print the enums in <group> if given, or all enums if omitted, sorted on
102 
+    support, in a tree.
103 
+  params [<group>]
104 
+    Print the parameter names of <group> if given, or all parameter names if
105 
+    omitted.
106 
+  params-tree [<group>]
107 
+    Print the parameter names of <group> if given, or all parameter names if
108 
+    omitted, sorted on count, together with the commands sorted on support, in
109 
+    a tree.
110 
+  audit [<path>]
111 
+    Search files in <path> if given, or the current directory if omitted,
112 
+    recursively for OpenGL API names and print them sorted on location,
113 
+    support, and name, in a list.
114 
+  audit-tree [<path>]
115 
+    Search files in <path> if given, or the current directory if omitted,
116 
+    recursively for OpenGL API names and print them sorted on support, name,
117 
+    and location, in a tree.
118 
+
119 
+Environment variables:
120 
+  GLREGISTRY_CACHE
121 
+    The directory to cache files in. Defaults to `$XDG_CACHE_HOME/glregistry`
122 
+    or, if `$XDG_CACHE_HOME` is not defined, `$HOME/.cache/glregistry`.
123 
+  GLREGISTRY_EDITOR
124 
+    The editor to use when opening files. Defaults to `$EDITOR` or, if
125 
+    `$EDITOR` is not defined, `editor` if it exists in `$PATH`, else `vi`. The
126 
+    value is interpreted by the shell.
127 
+  GLREGISTRY_PAGER
128 
+    The pager to use when viewing output. Defaults to `$PAGER` or, if `$PAGER`
129 
+    is not defined, `pager` if it exists in `$PATH`, else `less` . The value is
130 
+    interpreted by the shell. If the `$LESS` environment variable is unset, it
131 
+    is set to `FR`.
132 
+```
133 
+
134 
+## References
135 
+
136 
+Note that some of these might be out of date.
137 
+
138 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/readme.pdf>
139 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/registry.rnc>
140 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/reg.py>
141 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/genheaders.py>
142 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/extensions/registry.py>
143 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/docs/syntaxrules.txt>
144 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/docs/promoting.html>
145 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/docs/enums.html>
146 
+-   <https://github.com/KhronosGroup/OpenGL-Registry/issues/481>
147 
+
148 
+See also:
149 
+
150 
+-   The community-driven [OpenGL Hardware Database][].
151 
+
152 
+[OpenGL Hardware Database]: https://opengl.gpuinfo.org
8 153
9 154 
 ## Install
10 155
Browse code

Add installation

Robert Cranston authored on 11/03/2022 18:57:51
Showing 1 changed files
README.md
History View file @ ee21125
... ... 
@@ -6,6 +6,68 @@ Cache and query the [OpenGL][] [registry][] locally.
6 6 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
7 7 
 [registry]: https://registry.khronos.org/OpenGL/
8 8
9 
+## Install
10 
+
11 
+Make sure [Python is installed][Python download], [`pip`][] is available and
12 
+the [`pip`][], [`setuptools`][] and [`wheel`][] packages are up to date:
13 
+
14 
+```sh
15 
+python3 -m pip install --user --upgrade pip setuptools wheel
16 
+```
17 
+
18 
+Reference: [Python Packaging User Guide: Requirements for Installing
19 
+Packages][].
20 
+
21 
+[Python download]: https://python.org/download
22 
+[`pip`]: https://pip.readthedocs.io
23 
+[`setuptools`]: https://setuptools.readthedocs.io
24 
+[`wheel`]: https://wheel.readthedocs.io
25 
+[Python Packaging User Guide: Requirements for Installing Packages]: https://packaging.python.org/tutorials/installing-packages/#requirements-for-installing-packages
26 
+
27 
+### With [`pipx`][], for users
28 
+
29 
+Make sure [`pipx`][] is installed:
30 
+
31 
+```sh
32 
+python3 -m pip install --user pipx
33 
+```
34 
+
35 
+Install `glregistry`:
36 
+
37 
+```sh
38 
+pipx install "git+https://git.rcrnstn.net/rcrnstn/glregistry"
39 
+```
40 
+
41 
+`glregistry` should now be in your [`PATH`][] (if not, run `python3 -m pipx
42 
+ensurepath`).
43 
+
44 
+Reference: [Python Packaging User Guide: Installing stand alone command line
45 
+tools][].
46 
+
47 
+[`pipx`]: https://pipxproject.github.io/pipx/
48 
+[`PATH`]: https://en.wikipedia.org/wiki/PATH_(variable)
49 
+[Python Packaging User Guide: Installing stand alone command line tools]: https://packaging.python.org/guides/installing-stand-alone-command-line-tools/
50 
+
51 
+### Into [`venv`][], for developers
52 
+
53 
+Clone and install into a repository [`venv`][] virtual environment:
54 
+
55 
+```sh
56 
+git clone "https://git.rcrnstn.net/rcrnstn/glregistry"
57 
+cd "glregistry"
58 
+python3 -m venv .venv
59 
+. .venv/bin/activate
60 
+python3 -m pip install --editable .
61 
+```
62 
+
63 
+`glregistry` should now be in your (virtual environment) [`PATH`][].
64 
+
65 
+Reference: [Python Packaging User Guide: Installing packages using pip and
66 
+virtual environments][].
67 
+
68 
+[`venv`]: https://docs.python.org/3/library/venv.html
69 
+[Python Packaging User Guide: Installing packages using pip and virtual environments]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/
70 
+
9 71 
 ## License
10 72
11 73 
 Licensed under the [ISC License][] unless otherwise noted, see the
Browse code

Add license

Robert Cranston authored on 11/03/2022 18:48:01
Showing 1 changed files
README.md
History View file @ 50b941b
... ... 
@@ -5,3 +5,11 @@ Cache and query the [OpenGL][] [registry][] locally.
5 5 
 [`glregistry`]: https://git.rcrnstn.net/rcrnstn/glregistry
6 6 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
7 7 
 [registry]: https://registry.khronos.org/OpenGL/
8 
+
9 
+## License
10 
+
11 
+Licensed under the [ISC License][] unless otherwise noted, see the
12 
+[`LICENSE`][] file.
13 
+
14 
+[ISC License]: https://choosealicense.com/licenses/isc/
15 
+[`LICENSE`]: LICENSE
Browse code

Add readme

Robert Cranston authored on 11/03/2022 18:48:00
Showing 1 changed files
README.md
History View file @ 2910b3b
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,7 @@
1 
+# [`glregistry`][]
2 
+
3 
+Cache and query the [OpenGL][] [registry][] locally.
4 
+
5 
+[`glregistry`]: https://git.rcrnstn.net/rcrnstn/glregistry
6 
+[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
7 
+[registry]: https://registry.khronos.org/OpenGL/