toml: deprecate input.auto_config() and toml.parse() (#13770)

cmd/tools/vgret.v

@@ -354,7 +354,11 @@ fn vexe() string {
 }
 
 fn new_config(root_path string, toml_config string) ?Config {
-	doc := toml.parse(toml_config) ?
+	doc := if os.is_file(toml_config) {
+		toml.parse_file(toml_config) ?
+	} else {
+		toml.parse_text(toml_config) ?
+	}
 
 	path := os.real_path(root_path).trim_right('/')
 

vlib/toml/checker/checker.v

@@ -415,7 +415,7 @@ pub fn (c Checker) check_quoted(q ast.Quoted) ? {
 // \UXXXXXXXX - Unicode         (U+XXXXXXXX)
 fn (c Checker) check_quoted_escapes(q ast.Quoted) ? {
 	// Setup a scanner in stack memory for easier navigation.
-	mut s := scanner.new_simple(q.text) ?
+	mut s := scanner.new_simple_text(q.text) ?
 
 	// See https://toml.io/en/v1.0.0#string for more info on string types.
 	is_basic := q.quote == `\"`
@@ -552,7 +552,7 @@ fn (c Checker) check_unicode_escape(esc_unicode string) ? {
 pub fn (c Checker) check_comment(comment ast.Comment) ? {
 	lit := comment.text
 	// Setup a scanner in stack memory for easier navigation.
-	mut s := scanner.new_simple(lit) ?
+	mut s := scanner.new_simple_text(lit) ?
 	for {
 		ch := s.next()
 		if ch == scanner.end_of_text {

vlib/toml/decoder/decoder.v

@@ -84,7 +84,7 @@ pub fn decode_quoted_escapes(mut q ast.Quoted) ? {
 		return
 	}
 
-	mut s := scanner.new_simple(q.text) ?
+	mut s := scanner.new_simple_text(q.text) ?
 	q.text = q.text.replace('\\"', '"')
 
 	for {

vlib/toml/input/input.v

@@ -15,6 +15,10 @@ pub:
 
 // auto_config returns an, automatic determined, input Config based on heuristics
 // found in `toml`
+// One example of several of why it's deprecated:
+// https://discord.com/channels/592103645835821068/592114487759470596/954101934988615721
+[deprecated: 'will be removed and not replaced due to flaky heuristics that leads to hard to find bugs']
+[deprecated_after: '2022-06-18']
 pub fn auto_config(toml string) ?Config {
 	mut config := Config{}
 	if !toml.contains('\n') && os.is_file(toml) {
@@ -32,7 +36,7 @@ pub fn auto_config(toml string) ?Config {
 
 // validate returns an optional error if more than one of the fields
 // in `Config` has a non-default value (empty string).
-pub fn (c Config) validate() ? {
+fn (c Config) validate() ? {
 	if c.file_path != '' && c.text != '' {
 		error(@MOD + '.' + @FN +
 			' ${typeof(c).name} should contain only one of the fields `file_path` OR `text` filled out')
@@ -42,9 +46,12 @@ pub fn (c Config) validate() ? {
 	}
 }
 
+// read_input returns either Config.text or the read file contents of Config.file_path
+// depending on which one is not empty.
 pub fn (c Config) read_input() ?string {
+	c.validate() ?
 	mut text := c.text
-	if os.is_file(c.file_path) {
+	if text == '' && os.is_file(c.file_path) {
 		text = os.read_file(c.file_path) or {
 			return error(@MOD + '.' + @STRUCT + '.' + @FN +
 				' Could not read "$c.file_path": "$err.msg()"')

vlib/toml/scanner/scanner.v

@@ -3,7 +3,6 @@
 // that can be found in the LICENSE file.
 module scanner
 
-import os
 import math
 import toml.input
 import toml.token
@@ -50,28 +49,44 @@ pub:
 // new_scanner returns a new *heap* allocated `Scanner` instance, based on the file in config.input.file_path,
 // or based on the text in config.input.text .
 pub fn new_scanner(config Config) ?&Scanner {
-	config.input.validate() ?
-	mut text := config.input.text
-	file_path := config.input.file_path
-	if os.is_file(file_path) {
-		text = os.read_file(file_path) or {
-			return error(@MOD + '.' + @STRUCT + '.' + @FN +
-				' Could not read "$file_path": "$err.msg()"')
-		}
-	}
 	mut s := &Scanner{
 		config: config
-		text: text
+		text: config.input.read_input() ?
 	}
 	return s
 }
 
-// new_simple returns a new *stack* allocated `Scanner` instance, that will work on the text in `toml_input`.
-pub fn new_simple(toml_input string) ?Scanner {
+// new_simple returns a new *stack* allocated `Scanner` instance.
+pub fn new_simple(config Config) ?Scanner {
+	return Scanner{
+		config: config
+		text: config.input.read_input() ?
+	}
+}
+
+// new_simple_text returns a new *stack* allocated `Scanner` instance
+// ready for parsing TOML in `text`.
+pub fn new_simple_text(text string) ?Scanner {
+	in_config := input.Config{
+		text: text
+	}
 	config := Config{
-		input: input.Config{
-			text: toml_input
-		}
+		input: in_config
+	}
+	return Scanner{
+		config: config
+		text: config.input.read_input() ?
+	}
+}
+
+// new_simple_file returns a new *stack* allocated `Scanner` instance
+// ready for parsing TOML in file read from `path`.
+pub fn new_simple_file(path string) ?Scanner {
+	in_config := input.Config{
+		file_path: path
+	}
+	config := Config{
+		input: in_config
 	}
 	return Scanner{
 		config: config

vlib/toml/toml.v

@@ -108,6 +108,8 @@ pub fn parse_text(text string) ?Doc {
 // parse parses the TOML document provided in `toml`.
 // parse automatically try to determine if the type of `toml` is a file or text.
 // For explicit parsing of input types see `parse_file` or `parse_text`.
+[deprecated: 'use parse_file or parse_text instead']
+[deprecated_after: '2022-06-18']
 pub fn parse(toml string) ?Doc {
 	mut input_config := input.auto_config(toml) ?
 	scanner_config := scanner.Config{