Merge branch 'aleksm/mkenums-since' into 'master'

glib-mkenums: allow optional 'since' tag

See merge request GNOME/glib!1492
This commit is contained in:
Philip Withnall 2020-05-14 16:10:33 +00:00
commit 85f8efae0f
3 changed files with 87 additions and 17 deletions

View File

@ -172,25 +172,62 @@ in your templates, to improve the reproducibility of the build. (Since: 2.22)
Some C comments are treated specially in the parsed enum definitions, Some C comments are treated specially in the parsed enum definitions,
such comments start out with the trigraph sequence <literal>/*&lt;</literal> such comments start out with the trigraph sequence <literal>/*&lt;</literal>
and end with the trigraph sequence <literal>&gt;*/</literal>. and end with the trigraph sequence <literal>&gt;*/</literal>.
Per enum definition, the options <literal>skip</literal> and <literal>flags</literal> can be specified, to </para>
indicate this enum definition to be skipped, or for it to be treated as
a flags definition, or to specify the common prefix to be stripped from <para>The following options can be specified per enum definition:</para>
all values to generate value nicknames, respectively. The <literal>underscore_name</literal> <variablelist>
option can be used to specify the word separation used in the <function>*_get_type()</function> <varlistentry>
<term><literal>skip</literal></term>
<listitem><para>
Indicates this enum definition should be skipped.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>flags</literal></term>
<listitem><para>
Indicates this enum should be treated as a flags definition.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>underscore_name</literal></term>
<listitem><para>
Specifies the word separation used in the <function>*_get_type()</function>
function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>. function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>.
</para> </para></listitem>
<para> </varlistentry>
Per value definition, the options <literal>skip</literal> and <literal>nick</literal> are supported. <varlistentry>
The former causes the value to be skipped, and the latter can be used to <term><literal>since</literal></term>
specify the otherwise auto-generated nickname. <listitem><para>
Examples: Specifies the version tag that will be used to substitute the <literal>@enumsince@</literal>
</para> keyword in the template, useful when documenting methods generated from the enums
(e.g. <literal>Since: @enumsince@</literal>). (Since: 2.66)
</para></listitem>
</varlistentry>
</variablelist>
<para>The following options can be specified per value definition:</para>
<variablelist>
<varlistentry>
<term><literal>skip</literal></term>
<listitem><para>
Indicates the value should be skipped.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>nick</literal></term>
<listitem><para>
Specifies the otherwise auto-generated nickname.
</para></listitem>
</varlistentry>
</variablelist>
<para>Examples:</para>
<informalexample><programlisting> <informalexample><programlisting>
typedef enum /*&lt; skip &gt;*/ typedef enum /*&lt; skip &gt;*/
{ {
PREFIX_FOO PREFIX_FOO
} PrefixThisEnumWillBeSkipped; } PrefixThisEnumWillBeSkipped;
typedef enum /*&lt; flags,prefix=PREFIX &gt;*/ typedef enum /*&lt; flags,prefix=PREFIX,since=1.0 &gt;*/
{ {
PREFIX_THE_ZEROTH_VALUE, /*&lt; skip &gt;*/ PREFIX_THE_ZEROTH_VALUE, /*&lt; skip &gt;*/
PREFIX_THE_FIRST_VALUE, PREFIX_THE_FIRST_VALUE,

View File

@ -130,6 +130,7 @@ option_lowercase_name = '' # DEPRECATED. A lower case name to use as part
# one that we guess. For instance, when an enum # one that we guess. For instance, when an enum
# uses abnormal capitalization and we can not # uses abnormal capitalization and we can not
# guess where to put the underscores. # guess where to put the underscores.
option_since = '' # User provided version info for the enum.
seenbitshift = 0 # Have we seen bitshift operators? seenbitshift = 0 # Have we seen bitshift operators?
enum_prefix = None # Prefix for this enumeration enum_prefix = None # Prefix for this enumeration
enumname = '' # Name for this enumeration enumname = '' # Name for this enumeration
@ -256,6 +257,7 @@ help_epilog = '''Production text substitutions:
\u0040ENUMNAME\u0040 PREFIX_THE_XENUM \u0040ENUMNAME\u0040 PREFIX_THE_XENUM
\u0040ENUMSHORT\u0040 THE_XENUM \u0040ENUMSHORT\u0040 THE_XENUM
\u0040ENUMPREFIX\u0040 PREFIX \u0040ENUMPREFIX\u0040 PREFIX
\u0040enumsince\u0040 the user-provided since value given
\u0040VALUENAME\u0040 PREFIX_THE_XVALUE \u0040VALUENAME\u0040 PREFIX_THE_XVALUE
\u0040valuenick\u0040 the-xvalue \u0040valuenick\u0040 the-xvalue
\u0040valuenum\u0040 the integer value (limited support, Since: 2.26) \u0040valuenum\u0040 the integer value (limited support, Since: 2.26)
@ -515,11 +517,13 @@ def process_file(curfilename):
flags = int(flags) flags = int(flags)
option_lowercase_name = options.get('lowercase_name', None) option_lowercase_name = options.get('lowercase_name', None)
option_underscore_name = options.get('underscore_name', None) option_underscore_name = options.get('underscore_name', None)
option_since = options.get('since', None)
else: else:
enum_prefix = None enum_prefix = None
flags = None flags = None
option_lowercase_name = None option_lowercase_name = None
option_underscore_name = None option_underscore_name = None
option_since = None
if option_lowercase_name is not None: if option_lowercase_name is not None:
if option_underscore_name is not None: if option_underscore_name is not None:
@ -620,6 +624,11 @@ def process_file(curfilename):
enumlong = enumname_prefix + "_" + enumshort enumlong = enumname_prefix + "_" + enumshort
enumsym = enumlong.lower() enumsym = enumlong.lower()
if option_since is not None:
enumsince = option_since
else:
enumsince = ""
if firstenum: if firstenum:
firstenum = False firstenum = False
@ -641,6 +650,7 @@ def process_file(curfilename):
prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort) prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort)
prod = prod.replace('\u0040ENUMNAME\u0040', enumlong) prod = prod.replace('\u0040ENUMNAME\u0040', enumlong)
prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix) prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix)
prod = prod.replace('\u0040enumsince\u0040', enumsince)
if flags: if flags:
prod = prod.replace('\u0040type\u0040', 'flags') prod = prod.replace('\u0040type\u0040', 'flags')
else: else:
@ -663,6 +673,7 @@ def process_file(curfilename):
prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort) prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort)
prod = prod.replace('\u0040ENUMNAME\u0040', enumlong) prod = prod.replace('\u0040ENUMNAME\u0040', enumlong)
prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix) prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix)
prod = prod.replace('\u0040enumsince\u0040', enumsince)
if flags: if flags:
prod = prod.replace('\u0040type\u0040', 'flags') prod = prod.replace('\u0040type\u0040', 'flags')
else: else:
@ -729,6 +740,7 @@ def process_file(curfilename):
prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort) prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort)
prod = prod.replace('\u0040ENUMNAME\u0040', enumlong) prod = prod.replace('\u0040ENUMNAME\u0040', enumlong)
prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix) prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix)
prod = prod.replace('\u0040enumsince\u0040', enumsince)
if flags: if flags:
prod = prod.replace('\u0040type\u0040', 'flags') prod = prod.replace('\u0040type\u0040', 'flags')
else: else:

View File

@ -153,6 +153,7 @@ enum_name: @enum_name@
ENUMNAME: @ENUMNAME@ ENUMNAME: @ENUMNAME@
ENUMSHORT: @ENUMSHORT@ ENUMSHORT: @ENUMSHORT@
ENUMPREFIX: @ENUMPREFIX@ ENUMPREFIX: @ENUMPREFIX@
enumsince: @enumsince@
type: @type@ type: @type@
Type: @Type@ Type: @Type@
TYPE: @TYPE@ TYPE: @TYPE@
@ -165,6 +166,7 @@ enum_name: @enum_name@
ENUMNAME: @ENUMNAME@ ENUMNAME: @ENUMNAME@
ENUMSHORT: @ENUMSHORT@ ENUMSHORT: @ENUMSHORT@
ENUMPREFIX: @ENUMPREFIX@ ENUMPREFIX: @ENUMPREFIX@
enumsince: @enumsince@
type: @type@ type: @type@
Type: @Type@ Type: @Type@
TYPE: @TYPE@ TYPE: @TYPE@
@ -187,6 +189,7 @@ enum_name: @enum_name@
ENUMNAME: @ENUMNAME@ ENUMNAME: @ENUMNAME@
ENUMSHORT: @ENUMSHORT@ ENUMSHORT: @ENUMSHORT@
ENUMPREFIX: @ENUMPREFIX@ ENUMPREFIX: @ENUMPREFIX@
enumsince: @enumsince@
type: @type@ type: @type@
Type: @Type@ Type: @Type@
TYPE: @TYPE@ TYPE: @TYPE@
@ -225,7 +228,7 @@ file-tail
def assertSingleEnum(self, result, enum_name_camel, enum_name_lower, def assertSingleEnum(self, result, enum_name_camel, enum_name_lower,
enum_name_upper, enum_name_short, enum_prefix, enum_name_upper, enum_name_short, enum_prefix,
type_lower, type_camel, type_upper, enum_since, type_lower, type_camel, type_upper,
value_name, value_nick, value_num): value_name, value_nick, value_num):
"""Assert that out (from runMkenumsWithHeader()) contains a single """Assert that out (from runMkenumsWithHeader()) contains a single
enum and value matching the given arguments.""" enum and value matching the given arguments."""
@ -235,6 +238,7 @@ file-tail
'enum_name_upper': enum_name_upper, 'enum_name_upper': enum_name_upper,
'enum_name_short': enum_name_short, 'enum_name_short': enum_name_short,
'enum_prefix': enum_prefix, 'enum_prefix': enum_prefix,
'enum_since': enum_since,
'type_lower': type_lower, 'type_lower': type_lower,
'type_camel': type_camel, 'type_camel': type_camel,
'type_upper': type_upper, 'type_upper': type_upper,
@ -258,6 +262,7 @@ enum_name: {enum_name_lower}
ENUMNAME: {enum_name_upper} ENUMNAME: {enum_name_upper}
ENUMSHORT: {enum_name_short} ENUMSHORT: {enum_name_short}
ENUMPREFIX: {enum_prefix} ENUMPREFIX: {enum_prefix}
enumsince: {enum_since}
type: {type_lower} type: {type_lower}
Type: {type_camel} Type: {type_camel}
TYPE: {type_upper} TYPE: {type_upper}
@ -267,6 +272,7 @@ enum_name: {enum_name_lower}
ENUMNAME: {enum_name_upper} ENUMNAME: {enum_name_upper}
ENUMSHORT: {enum_name_short} ENUMSHORT: {enum_name_short}
ENUMPREFIX: {enum_prefix} ENUMPREFIX: {enum_prefix}
enumsince: {enum_since}
type: {type_lower} type: {type_lower}
Type: {type_camel} Type: {type_camel}
TYPE: {type_upper} TYPE: {type_upper}
@ -283,6 +289,7 @@ enum_name: {enum_name_lower}
ENUMNAME: {enum_name_upper} ENUMNAME: {enum_name_upper}
ENUMSHORT: {enum_name_short} ENUMSHORT: {enum_name_short}
ENUMPREFIX: {enum_prefix} ENUMPREFIX: {enum_prefix}
enumsince: {enum_since}
type: {type_lower} type: {type_lower}
Type: {type_camel} Type: {type_camel}
TYPE: {type_upper} TYPE: {type_upper}
@ -360,7 +367,7 @@ comment: {standard_bottom_comment}
self.assertEqual('', result.err) self.assertEqual('', result.err)
self.assertSingleEnum(result, 'SomeEnumIdentifier', self.assertSingleEnum(result, 'SomeEnumIdentifier',
'some_enum_identifier', 'SOME_ENUM_IDENTIFIER', 'some_enum_identifier', 'SOME_ENUM_IDENTIFIER',
'ENUM_IDENTIFIER', 'SOME', 'enum', 'Enum', 'ENUM_IDENTIFIER', 'SOME', '', 'enum', 'Enum',
'ENUM', 'ENUM_VALUE', 'value', '0') 'ENUM', 'ENUM_VALUE', 'value', '0')
def test_non_utf8_encoding(self): def test_non_utf8_encoding(self):
@ -375,7 +382,7 @@ comment: {standard_bottom_comment}
self.assertIn('WARNING: UnicodeWarning: ', result.err) self.assertIn('WARNING: UnicodeWarning: ', result.err)
self.assertSingleEnum(result, 'SomeEnumIdentifier', self.assertSingleEnum(result, 'SomeEnumIdentifier',
'some_enum_identifier', 'SOME_ENUM_IDENTIFIER', 'some_enum_identifier', 'SOME_ENUM_IDENTIFIER',
'ENUM_IDENTIFIER', 'SOME', 'enum', 'Enum', 'ENUM_IDENTIFIER', 'SOME', '', 'enum', 'Enum',
'ENUM', 'ENUM_VALUE', 'value', '0') 'ENUM', 'ENUM_VALUE', 'value', '0')
def test_reproducible(self): def test_reproducible(self):
@ -430,7 +437,7 @@ comment: {standard_bottom_comment}
self.assertEqual('', result.err) self.assertEqual('', result.err)
self.assertSingleEnum(result, 'GeglSamplerType', self.assertSingleEnum(result, 'GeglSamplerType',
'gegl_sampler_type', 'GEGL_SAMPLER_TYPE', 'gegl_sampler_type', 'GEGL_SAMPLER_TYPE',
'SAMPLER_TYPE', 'GEGL', 'enum', 'Enum', 'SAMPLER_TYPE', 'GEGL', '', 'enum', 'Enum',
'ENUM', 'GEGL_SAMPLER_NEAREST', 'nearest', '0') 'ENUM', 'GEGL_SAMPLER_NEAREST', 'nearest', '0')
def test_filename_basename_in_fhead_ftail(self): def test_filename_basename_in_fhead_ftail(self):
@ -477,6 +484,20 @@ comment
comment: {standard_bottom_comment} comment: {standard_bottom_comment}
'''.format(**result.subs).strip(), result.out) '''.format(**result.subs).strip(), result.out)
def test_since(self):
"""Test user-provided 'since' version handling
https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1492"""
h_contents = '''
typedef enum { /*< since=1.0 >*/
QMI_WMS_MESSAGE_PROTOCOL_CDMA = 0,
} QmiWmsMessageProtocol;
'''
result = self.runMkenumsWithHeader(h_contents)
self.assertEqual('', result.err)
self.assertSingleEnum(result, 'QmiWmsMessageProtocol',
'qmi_wms_message_protocol', 'QMI_WMS_MESSAGE_PROTOCOL',
'WMS_MESSAGE_PROTOCOL', 'QMI', '1.0', 'enum', 'Enum',
'ENUM', 'QMI_WMS_MESSAGE_PROTOCOL_CDMA', 'cdma', '0')
class TestRspMkenums(TestMkenums): class TestRspMkenums(TestMkenums):
'''Run all tests again in @rspfile mode''' '''Run all tests again in @rspfile mode'''