feat: extensions_options macro

datafusion-examples/examples/config_extension.rs

@@ -0,0 +1,52 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! This example demonstrates how to extend the DataFusion configs with custom extensions.
+
+use datafusion::{
+ common::{config::ConfigExtension, extensions_options},
+ config::ConfigOptions,
+};
+
+extensions_options! {
+ /// My own config options.
+ pub struct MyConfig {
+ /// Should "foo" be replaced by "bar"?
+ pub foo_to_bar: bool, default = true
+
+ /// How many "baz" should be created?
+ pub baz_count: usize, default = 1337
+ }
+}
+
+impl ConfigExtension for MyConfig {
+ const PREFIX: &'static str = "my_config";
+}
+
+fn main() {
+ // set up config struct and register extension
+ let mut config = ConfigOptions::default();
+ config.extensions.insert(MyConfig::default());
+
+ // overwrite config default
+ config.set("my_config.baz_count", "42").unwrap();
+
+ // check config state
+ let my_config = config.extensions.get::<MyConfig>().unwrap();
+ assert!(my_config.foo_to_bar,);
+ assert_eq!(my_config.baz_count, 42,);
+}

datafusion/common/src/config.rs

@@ -634,3 +634,129 @@ trait Visit {
 
  fn none(&mut self, key: &str, description: &'static str);
 }
+
+/// Convenience macro to create [`ExtensionsOptions`].
+///
+/// The created structure implements the following traits:
+///
+/// - [`Clone`]
+/// - [`Debug`]
+/// - [`Default`]
+/// - [`ExtensionOptions`]
+///
+/// # Usage
+/// The syntax is:
+///
+/// ```text
+/// extensions_options! {
+/// /// Struct docs (optional).
+/// [<vis>] struct <StructName> {
+/// /// Field docs (optional)
+/// [<vis>] <field_name>: <field_type>, default = <default_value>
+///
+/// ... more fields
+/// }
+/// }
+/// ```
+///
+/// The placeholders are:
+/// - `[<vis>]`: Optional visibility modifier like `pub` or `pub(crate)`.
+/// - `<StructName>`: Struct name like `MyStruct`.
+/// - `<field_name>`: Field name like `my_field`.
+/// - `<field_type>`: Field type like `u8`.
+/// - `<default_value>`: Default value matching the field type like `42`.
+///
+/// # Example
+/// ```
+/// use datafusion_common::extensions_options;
+///
+/// extensions_options! {
+/// /// My own config options.
+/// pub struct MyConfig {
+/// /// Should "foo" be replaced by "bar"?
+/// pub foo_to_bar: bool, default = true
+///
+/// /// How many "baz" should be created?
+/// pub baz_count: usize, default = 1337
+/// }
+/// }
+/// ```
+///
+///
+/// [`Debug`]: std::fmt::Debug
+/// [`ExtensionsOptions`]: crate::config::ExtensionsOptions
+#[macro_export]
+macro_rules! extensions_options {
+ (
+ $(#[doc = $struct_d:tt])*
+ $vis:vis struct $struct_name:ident {
+ $(
+ $(#[doc = $d:tt])*
+ $field_vis:vis $field_name:ident : $field_type:ty, default = $default:expr
+ )*$(,)*
+ }
+ ) => {
+ $(#[doc = $struct_d])*
+ #[derive(Debug, Clone)]
+ #[non_exhaustive]
+ $vis struct $struct_name{
+ $(
+ $(#[doc = $d])*
+ $field_vis $field_name : $field_type,
+ )*
+ }
+
+ impl Default for $struct_name {
+ fn default() -> Self {
+ Self {
+ $($field_name: $default),*
+ }
+ }
+ }
+
+ impl $crate::config::ExtensionOptions for $struct_name {
+ fn as_any(&self) -> &dyn ::std::any::Any {
+ self
+ }
+
+ fn as_any_mut(&mut self) -> &mut dyn ::std::any::Any {
+ self
+ }
+
+ fn cloned(&self) -> Box<dyn $crate::config::ExtensionOptions> {
+ Box::new(self.clone())
+ }
+
+ fn set(&mut self, key: &str, value: &str) -> $crate::Result<()> {
+ match key {
+ $(
+ stringify!($field_name) => {
+ self.$field_name = value.parse().map_err(|e| {
+ $crate::DataFusionError::Context(
+ format!(concat!("Error parsing {} as ", stringify!($t),), value),
+ Box::new($crate::DataFusionError::External(Box::new(e))),
+ )
+ })?;
+ Ok(())
+ }
+ )*
+ _ => Err($crate::DataFusionError::Internal(
+ format!(concat!("Config value \"{}\" not found on ", stringify!($struct_name)), key)
+ ))
+ }
+ }
+
+ fn entries(&self) -> Vec<$crate::config::ConfigEntry> {
+ vec![
+ $(
+ $crate::config::ConfigEntry {
+ key: stringify!($field_name).to_owned(),
+ value: (self.$field_name != $default).then(|| self.$field_name.to_string()),
+ description: concat!($($d),*).trim(),
+ },
+ )*
+ ]
+ }
+ }
+ }
+}