From 4d1132a945429ce56a58c79215c9bc277282bd66 Mon Sep 17 00:00:00 2001 From: Aleksander Morgado Date: Thu, 14 May 2020 16:02:32 +0200 Subject: [PATCH 1/2] docs,glib-mkenums: setup lists for enum/value trigraph extensions Signed-off-by: Aleksander Morgado --- docs/reference/gobject/glib-mkenums.xml | 53 +++++++++++++++++++------ 1 file changed, 41 insertions(+), 12 deletions(-) diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml index 9dac8217d..e1683860a 100644 --- a/docs/reference/gobject/glib-mkenums.xml +++ b/docs/reference/gobject/glib-mkenums.xml @@ -172,19 +172,48 @@ in your templates, to improve the reproducibility of the build. (Since: 2.22) Some C comments are treated specially in the parsed enum definitions, such comments start out with the trigraph sequence /*< and end with the trigraph sequence >*/. -Per enum definition, the options skip and flags can be specified, to -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 -all values to generate value nicknames, respectively. The underscore_name -option can be used to specify the word separation used in the *_get_type() + + +The following options can be specified per enum definition: + + +skip + +Indicates this enum definition should be skipped. + + + +flags + +Indicates this enum should be treated as a flags definition. + + + +underscore_name + +Specifies the word separation used in the *_get_type() function. For instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/. - - -Per value definition, the options skip and nick are supported. -The former causes the value to be skipped, and the latter can be used to -specify the otherwise auto-generated nickname. -Examples: - + + + + +The following options can be specified per value definition: + + +skip + +Indicates the value should be skipped. + + + +nick + +Specifies the otherwise auto-generated nickname. + + + + +Examples: typedef enum /*< skip >*/ { From ec6056e3ab65ecde033c16b0e87f0b14c51b3d19 Mon Sep 17 00:00:00 2001 From: Aleksander Morgado Date: Tue, 12 May 2020 21:56:02 +0200 Subject: [PATCH 2/2] glib-mkenums: allow optional 'since' tag The glib-mkenums program allows generating code to handle enums/flags with very different purposes. One of its purposes could be generating per-enum/flag methods to be exposed in a library API, and while doing that, it would be nice to have a way to specify in which API version the enum/flag was introduced, so that the same version could be shown in the generated API methods. E.g. From the following code: /** * QmiWmsMessageProtocol: * @QMI_WMS_MESSAGE_PROTOCOL_CDMA: CDMA. * @QMI_WMS_MESSAGE_PROTOCOL_WCDMA: WCDMA. * * Type of message protocol. * * Since: 1.0 */ typedef enum { /*< since=1.0 >*/ QMI_WMS_MESSAGE_PROTOCOL_CDMA = 0x00, QMI_WMS_MESSAGE_PROTOCOL_WCDMA = 0x01 } QmiWmsMessageProtocol; The template would allow us to generate a method documented like this, including the Since tag with the value given in the mkenums 'since' tag. /** * qmi_wms_message_protocol_get_string: * @val: a QmiWmsMessageProtocol. * * Gets the nickname string for the #QmiWmsMessageProtocol specified at @val. * * Returns: (transfer none): a string with the nickname, or %NULL if not found. Do not free the returned value. * Since: 1.0 */ const gchar *qmi_wms_message_protocol_get_string (QmiWmsMessageProtocol val); Signed-off-by: Aleksander Morgado --- docs/reference/gobject/glib-mkenums.xml | 10 ++++++++- gobject/glib-mkenums.in | 12 ++++++++++ gobject/tests/mkenums.py | 29 +++++++++++++++++++++---- 3 files changed, 46 insertions(+), 5 deletions(-) diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml index e1683860a..2200328ed 100644 --- a/docs/reference/gobject/glib-mkenums.xml +++ b/docs/reference/gobject/glib-mkenums.xml @@ -195,6 +195,14 @@ Specifies the word separation used in the *_get_type() function. For instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/. + +since + +Specifies the version tag that will be used to substitute the @enumsince@ +keyword in the template, useful when documenting methods generated from the enums +(e.g. Since: @enumsince@). (Since: 2.66) + + The following options can be specified per value definition: @@ -219,7 +227,7 @@ typedef enum /*< skip >*/ { PREFIX_FOO } PrefixThisEnumWillBeSkipped; -typedef enum /*< flags,prefix=PREFIX >*/ +typedef enum /*< flags,prefix=PREFIX,since=1.0 >*/ { PREFIX_THE_ZEROTH_VALUE, /*< skip >*/ PREFIX_THE_FIRST_VALUE, diff --git a/gobject/glib-mkenums.in b/gobject/glib-mkenums.in index 91ad77942..a44efed19 100755 --- a/gobject/glib-mkenums.in +++ b/gobject/glib-mkenums.in @@ -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 # uses abnormal capitalization and we can not # guess where to put the underscores. +option_since = '' # User provided version info for the enum. seenbitshift = 0 # Have we seen bitshift operators? enum_prefix = None # Prefix for this enumeration enumname = '' # Name for this enumeration @@ -256,6 +257,7 @@ help_epilog = '''Production text substitutions: \u0040ENUMNAME\u0040 PREFIX_THE_XENUM \u0040ENUMSHORT\u0040 THE_XENUM \u0040ENUMPREFIX\u0040 PREFIX + \u0040enumsince\u0040 the user-provided since value given \u0040VALUENAME\u0040 PREFIX_THE_XVALUE \u0040valuenick\u0040 the-xvalue \u0040valuenum\u0040 the integer value (limited support, Since: 2.26) @@ -515,11 +517,13 @@ def process_file(curfilename): flags = int(flags) option_lowercase_name = options.get('lowercase_name', None) option_underscore_name = options.get('underscore_name', None) + option_since = options.get('since', None) else: enum_prefix = None flags = None option_lowercase_name = None option_underscore_name = None + option_since = None if option_lowercase_name is not None: if option_underscore_name is not None: @@ -620,6 +624,11 @@ def process_file(curfilename): enumlong = enumname_prefix + "_" + enumshort enumsym = enumlong.lower() + if option_since is not None: + enumsince = option_since + else: + enumsince = "" + if firstenum: firstenum = False @@ -641,6 +650,7 @@ def process_file(curfilename): prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort) prod = prod.replace('\u0040ENUMNAME\u0040', enumlong) prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix) + prod = prod.replace('\u0040enumsince\u0040', enumsince) if flags: prod = prod.replace('\u0040type\u0040', 'flags') else: @@ -663,6 +673,7 @@ def process_file(curfilename): prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort) prod = prod.replace('\u0040ENUMNAME\u0040', enumlong) prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix) + prod = prod.replace('\u0040enumsince\u0040', enumsince) if flags: prod = prod.replace('\u0040type\u0040', 'flags') else: @@ -729,6 +740,7 @@ def process_file(curfilename): prod = prod.replace('\u0040ENUMSHORT\u0040', enumshort) prod = prod.replace('\u0040ENUMNAME\u0040', enumlong) prod = prod.replace('\u0040ENUMPREFIX\u0040', enumname_prefix) + prod = prod.replace('\u0040enumsince\u0040', enumsince) if flags: prod = prod.replace('\u0040type\u0040', 'flags') else: diff --git a/gobject/tests/mkenums.py b/gobject/tests/mkenums.py index 5f28b9cc6..22a100505 100644 --- a/gobject/tests/mkenums.py +++ b/gobject/tests/mkenums.py @@ -153,6 +153,7 @@ enum_name: @enum_name@ ENUMNAME: @ENUMNAME@ ENUMSHORT: @ENUMSHORT@ ENUMPREFIX: @ENUMPREFIX@ +enumsince: @enumsince@ type: @type@ Type: @Type@ TYPE: @TYPE@ @@ -165,6 +166,7 @@ enum_name: @enum_name@ ENUMNAME: @ENUMNAME@ ENUMSHORT: @ENUMSHORT@ ENUMPREFIX: @ENUMPREFIX@ +enumsince: @enumsince@ type: @type@ Type: @Type@ TYPE: @TYPE@ @@ -187,6 +189,7 @@ enum_name: @enum_name@ ENUMNAME: @ENUMNAME@ ENUMSHORT: @ENUMSHORT@ ENUMPREFIX: @ENUMPREFIX@ +enumsince: @enumsince@ type: @type@ Type: @Type@ TYPE: @TYPE@ @@ -225,7 +228,7 @@ file-tail def assertSingleEnum(self, result, enum_name_camel, enum_name_lower, 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): """Assert that out (from runMkenumsWithHeader()) contains a single enum and value matching the given arguments.""" @@ -235,6 +238,7 @@ file-tail 'enum_name_upper': enum_name_upper, 'enum_name_short': enum_name_short, 'enum_prefix': enum_prefix, + 'enum_since': enum_since, 'type_lower': type_lower, 'type_camel': type_camel, 'type_upper': type_upper, @@ -258,6 +262,7 @@ enum_name: {enum_name_lower} ENUMNAME: {enum_name_upper} ENUMSHORT: {enum_name_short} ENUMPREFIX: {enum_prefix} +enumsince: {enum_since} type: {type_lower} Type: {type_camel} TYPE: {type_upper} @@ -267,6 +272,7 @@ enum_name: {enum_name_lower} ENUMNAME: {enum_name_upper} ENUMSHORT: {enum_name_short} ENUMPREFIX: {enum_prefix} +enumsince: {enum_since} type: {type_lower} Type: {type_camel} TYPE: {type_upper} @@ -283,6 +289,7 @@ enum_name: {enum_name_lower} ENUMNAME: {enum_name_upper} ENUMSHORT: {enum_name_short} ENUMPREFIX: {enum_prefix} +enumsince: {enum_since} type: {type_lower} Type: {type_camel} TYPE: {type_upper} @@ -360,7 +367,7 @@ comment: {standard_bottom_comment} self.assertEqual('', result.err) self.assertSingleEnum(result, 'SomeEnumIdentifier', 'some_enum_identifier', 'SOME_ENUM_IDENTIFIER', - 'ENUM_IDENTIFIER', 'SOME', 'enum', 'Enum', + 'ENUM_IDENTIFIER', 'SOME', '', 'enum', 'Enum', 'ENUM', 'ENUM_VALUE', 'value', '0') def test_non_utf8_encoding(self): @@ -375,7 +382,7 @@ comment: {standard_bottom_comment} self.assertIn('WARNING: UnicodeWarning: ', result.err) self.assertSingleEnum(result, 'SomeEnumIdentifier', 'some_enum_identifier', 'SOME_ENUM_IDENTIFIER', - 'ENUM_IDENTIFIER', 'SOME', 'enum', 'Enum', + 'ENUM_IDENTIFIER', 'SOME', '', 'enum', 'Enum', 'ENUM', 'ENUM_VALUE', 'value', '0') def test_reproducible(self): @@ -430,7 +437,7 @@ comment: {standard_bottom_comment} self.assertEqual('', result.err) self.assertSingleEnum(result, 'GeglSamplerType', 'gegl_sampler_type', 'GEGL_SAMPLER_TYPE', - 'SAMPLER_TYPE', 'GEGL', 'enum', 'Enum', + 'SAMPLER_TYPE', 'GEGL', '', 'enum', 'Enum', 'ENUM', 'GEGL_SAMPLER_NEAREST', 'nearest', '0') def test_filename_basename_in_fhead_ftail(self): @@ -477,6 +484,20 @@ comment comment: {standard_bottom_comment} '''.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): '''Run all tests again in @rspfile mode'''