This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new a0588cc806 [docs]: added `alternative_syntax` function for docs
(#13140)
a0588cc806 is described below
commit a0588cc806e310b01151f91a028ab79929194647
Author: Jonathan Chen <[email protected]>
AuthorDate: Mon Oct 28 07:35:19 2024 -0400
[docs]: added `alternative_syntax` function for docs (#13140)
* Add alternative syntax function.
* fmt check
---
datafusion/core/src/bin/print_functions_docs.rs | 7 +++++++
datafusion/expr/src/udf_docs.rs | 13 +++++++++++++
datafusion/functions/src/unicode/strpos.rs | 1 +
docs/source/user-guide/sql/scalar_functions_new.md | 6 ++++++
4 files changed, 27 insertions(+)
diff --git a/datafusion/core/src/bin/print_functions_docs.rs
b/datafusion/core/src/bin/print_functions_docs.rs
index 598574c070..3aedcbc2aa 100644
--- a/datafusion/core/src/bin/print_functions_docs.rs
+++ b/datafusion/core/src/bin/print_functions_docs.rs
@@ -195,6 +195,13 @@ fn print_docs(
);
}
+ if let Some(alt_syntax) = &documentation.alternative_syntax {
+ let _ = writeln!(docs, "#### Alternative Syntax\n");
+ for syntax in alt_syntax {
+ let _ = writeln!(docs, "```sql\n{}\n```", syntax);
+ }
+ }
+
// next, aliases
if !f.get_aliases().is_empty() {
let _ = writeln!(docs, "#### Aliases");
diff --git a/datafusion/expr/src/udf_docs.rs b/datafusion/expr/src/udf_docs.rs
index 63d1a96434..a124361e42 100644
--- a/datafusion/expr/src/udf_docs.rs
+++ b/datafusion/expr/src/udf_docs.rs
@@ -47,6 +47,8 @@ pub struct Documentation {
/// Left member of a pair is the argument name, right is a
/// description for the argument
pub arguments: Option<Vec<(String, String)>>,
+ /// A list of alternative syntax examples for a function
+ pub alternative_syntax: Option<Vec<String>>,
/// Related functions if any. Values should match the related
/// udf's name exactly. Related udf's must be of the same
/// UDF type (scalar, aggregate or window) for proper linking to
@@ -96,6 +98,7 @@ pub struct DocumentationBuilder {
pub syntax_example: Option<String>,
pub sql_example: Option<String>,
pub arguments: Option<Vec<(String, String)>>,
+ pub alternative_syntax: Option<Vec<String>>,
pub related_udfs: Option<Vec<String>>,
}
@@ -107,6 +110,7 @@ impl DocumentationBuilder {
syntax_example: None,
sql_example: None,
arguments: None,
+ alternative_syntax: None,
related_udfs: None,
}
}
@@ -172,6 +176,13 @@ impl DocumentationBuilder {
self.with_argument(arg_name, description)
}
+ pub fn with_alternative_syntax(mut self, syntax_name: impl Into<String>)
-> Self {
+ let mut alternative_syntax_array =
self.alternative_syntax.unwrap_or_default();
+ alternative_syntax_array.push(syntax_name.into());
+ self.alternative_syntax = Some(alternative_syntax_array);
+ self
+ }
+
pub fn with_related_udf(mut self, related_udf: impl Into<String>) -> Self {
let mut related = self.related_udfs.unwrap_or_default();
related.push(related_udf.into());
@@ -186,6 +197,7 @@ impl DocumentationBuilder {
syntax_example,
sql_example,
arguments,
+ alternative_syntax,
related_udfs,
} = self;
@@ -205,6 +217,7 @@ impl DocumentationBuilder {
syntax_example: syntax_example.unwrap(),
sql_example,
arguments,
+ alternative_syntax,
related_udfs,
})
}
diff --git a/datafusion/functions/src/unicode/strpos.rs
b/datafusion/functions/src/unicode/strpos.rs
index 152623b0e5..9c84590f7f 100644
--- a/datafusion/functions/src/unicode/strpos.rs
+++ b/datafusion/functions/src/unicode/strpos.rs
@@ -97,6 +97,7 @@ fn get_strpos_doc() -> &'static Documentation {
```"#)
.with_standard_argument("str", Some("String"))
.with_argument("substr", "Substring expression to search for.")
+ .with_alternative_syntax("position(substr in origstr)")
.build()
.unwrap()
})
diff --git a/docs/source/user-guide/sql/scalar_functions_new.md
b/docs/source/user-guide/sql/scalar_functions_new.md
index c15821ac89..6031a68d40 100644
--- a/docs/source/user-guide/sql/scalar_functions_new.md
+++ b/docs/source/user-guide/sql/scalar_functions_new.md
@@ -1465,6 +1465,12 @@ strpos(str, substr)
+----------------------------------------+
```
+#### Alternative Syntax
+
+```sql
+position(substr in origstr)
+```
+
#### Aliases
- instr
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
