=encoding utf8

=head1 NAME

std/config - High-level configuration loading, merging, and querying.

=head1 SYNOPSIS

  from std/config import Config;
  from std/io import Path;

  let cfg := Config.load( [
    Path.join( [ "config", "base.toml" ] ),
    Path.join( [ "config", "local.json" ] ),
  ] );

  cfg.merge_flat(
    {
      "APP__port": "8080",
      "APP__debug": "true",
    },
    {
      prefix: "APP__",
      separator: "__",
      coerce: true,
    },
  );

  let host := cfg @ "/database/host";
  let port := cfg.get( "/port", 3000 );

=head1 IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and
Electron. It is partially supported by zuzu-js in the browser: environment
override and multi-format branch selection coverage passes, but the main
filesystem-backed configuration coverage is unsupported.

=head1 DESCRIPTION

This module provides a C<Config> object for application-style
configuration loading and overlaying.

Use C<Config.from_data(...)> when you want to wrap an already-built
Zuzu value instead of loading from files.

It is intentionally geared toward patterns common in higher-level config
frameworks:

=over

=item *

load one or more files with format auto-detection,

=item *

deep-merge config layers,

=item *

apply flat overlays such as env-style C<FOO__BAR__BAZ> keys,

=item *

query config using ZPath and the C<@>, C<@@>, and C<@?> operators.

=back

The object itself is path-aware, so this works directly:

  let city := cfg @ "/service/address/city";

=head1 EXPORTS

=head2 Classes

=over

=item C<Config>

Static methods:

=over

=item * C<from_data(data, options?)>

Parameters: C<data> is configuration data and C<options> controls
metadata. Returns: C<Config>. Wraps data in a config object.

=item * C<parse(text, format, options?)>

Parameters: C<text> is config text, C<format> is a format name, and
C<options> configures parsing. Returns: C<Config>. Parses text into a
config object.

=item * C<load(path_or_paths, options?)>

Parameters: C<path_or_paths> is one source or an array of sources.
Returns: C<Config>. Loads and layers config files.

=item * C<detect_format(path_or_name, fallback?)>

Parameters: C<path_or_name> is a path-like value and C<fallback> is
optional. Returns: C<String> or C<null>. Detects the config format.

=back

Instance methods:

=over

=item * C<type()>, C<can_have_named_children()>, C<can_have_indexed_children()>, C<can_have_named_indexed_children()>, C<children()>, C<attributes()>

Parameters: none. Returns: ZPath node metadata. Provides the inherited
node API used when a C<Config> is queried as a path root.

=item * C<do_action_on_child(child, action)>, C<ref_on_child(child)>

Parameters: C<child> is a selected node and C<action> is a path action.
Returns: value or C<Function>. Provides inherited mutation and reference
support for path assignments.

=item * C<to_data()>, C<clone()>

Parameters: none. Returns: value or C<Config>. Returns raw data or a
copy of the config.

=item * C<source()>, C<format()>, C<layers()>

Parameters: none. Returns: value. Returns config source metadata.

=item * C<get(path, fallback?)>, C<get_all(path)>, C<select(path)>

Parameters: C<path> is a path expression and C<fallback> is optional.
Returns: value or C<Array>. Reads config values.

=item * C<exists(path)>, C<require(path, message?)>

Parameters: C<path> is a path expression and C<message> is optional.
Returns: C<Boolean> or value. Tests for or requires a config value.

=item * C<query(path)>, C<first(path, fallback?)>

Parameters: C<path> is a path expression and C<fallback> is optional.
Returns: C<Array> or value. Queries config values.

=item * C<assign_first(path, value, op?)>

Parameters: C<path> selects values, C<value> is assigned, and C<op> is
optional. Returns: value. Updates the first match.

=item * C<assign_all(path, value, op?)>

Parameters: C<path> selects values, C<value> is assigned, and C<op> is
optional. Returns: value. Updates every match.

=item * C<assign_maybe(path, value, op?)>

Parameters: C<path> selects values, C<value> is assigned, and C<op> is
optional. Returns: C<Boolean>. Updates the first match when present.

=item * C<ref_first(path)>, C<ref_all(path)>, C<ref_maybe(path)>

Parameters: C<path> is a path expression. Returns: C<Function>,
C<Array>, or C<null>. Returns reference-like accessors.

=item * C<merge(data_or_config, options?)>, C<overlay(data_or_config, options?)>

Parameters: C<data_or_config> is incoming data and C<options> controls
merge behaviour. Returns: C<Config>. Merges configuration data.

=item * C<merge_flat(values, options?)>, C<merge_env(values, options?)>

Parameters: C<values> is flat config data and C<options> controls key
mapping. Returns: C<Config>. Merges flat or environment-style values.

=item * C<set(path, value)>, C<set_default(path, value)>

Parameters: C<path> is a simple path and C<value> is any value. Returns:
C<Config>. Sets or defaults a config value.

=item * C<encode(format?, options?)>, C<save(path, options?)>

Parameters: C<format>, C<path>, and C<options> control output. Returns:
C<String> or C<Config>. Encodes or saves configuration data.

=item * C<load_file(path, options?)>

Parameters: C<path> is a config source and C<options> controls parsing.
Returns: C<Config>. Loads one additional config file into the object.

=back

=back

=head1 NOTES

=over

=item *

C<merge> performs a deep merge for dictionaries.

=item *

Arrays are replaced by default; pass C<< { array_merge: "append" } >>
to append instead.

=item *

C<set> and C<set_default> create missing parent dictionaries, but only
for simple absolute paths such as C</server/port>. They intentionally do
not try to create missing nodes for complex selectors or filters.

=back

=head1 COPYRIGHT AND LICENCE

B<< std/config >> is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.

=cut

from std/cache/lru import Cache;
from std/path/z import ZPath;
from std/path/z/node import Node;
from std/string import join, split, substr, trim;


const _PATH_CACHE := new Cache( capacity: 50 );

function _opt ( options, key, fallback := null ) {
	if ( options instanceof Dict and options.exists(key) ) {
		return options.get(key);
	}
	return fallback;
}

function _unwrap_config_value ( value ) {
	if (
		value ≢ null and
		value can raw and
		value can query and
		value can merge
	) {
		return value.raw();
	}
	return value;
}

function _stringify_pathish ( pathish ) {
	from std/io import Path;
	if ( pathish instanceof Path ) {
		return pathish.to_String();
	}
	return "" _ pathish;
}

function _normalize_format ( raw_format ) {
	if ( raw_format ≡ null ) {
		return null;
	}

	let fmt := lc( "" _ raw_format );
	if ( fmt ≡ "yml" ) {
		return "yaml";
	}
	return fmt;
}

function _detect_format_from_name ( source, fallback := null ) {
	let text := lc( _stringify_pathish(source) );
	let dot := null;
	let i := length text - 1;
	while ( i >= 0 ) {
		let ch := substr( text, i, 1 );
		if ( ch ≡ "." ) {
			dot := i;
			last;
		}
		if ( ch ≡ "/" or ch ≡ "\\" ) {
			last;
		}
		i--;
	}

	if ( dot ≡ null or dot = length text - 1 ) {
		return fallback;
	}

	return _normalize_format( substr( text, dot + 1 ) ) ?: fallback;
}

function _codec_for_format ( raw_format, options? ) {
	let format := _normalize_format(raw_format);
	if ( _opt( options, "codec", null ) ≢ null ) {
		return _opt( options, "codec", null );
	}

	if ( format ≡ "json" ) {
		from std/data/json import JSON;
		return new JSON();
	}
	if ( format ≡ "yaml" ) {
		from std/data/yaml import YAML;
		return new YAML();
	}
	if ( format ≡ "toml" ) {
		from std/data/toml import TOML;
		return new TOML();
	}
	if ( format ≡ "ini" ) {
		from std/data/ini import INI;
		return new INI();
	}
	if ( format ≡ "toon" ) {
		from std/data/toon import TOON;
		return new TOON();
	}

	die `std/config does not know how to handle format '${format}'`;
}

function _ensure_path_object ( source ) {
	from std/io import Path;
	return source instanceof Path ? source : new Path( "" _ source );
}

function _compile_path ( pathish ) {
	if ( pathish instanceof ZPath ) {
		return pathish;
	}
	if (
		pathish can query and
		pathish can first and
		pathish can exists and
		pathish can assign_first and
		pathish can ref_first
	) {
		return pathish;
	}

	let expression := "" _ pathish;
	return _PATH_CACHE.get(
		expression,
		fn path_text -> new ZPath( path: path_text ),
	);
}

function _coerce_scalar_text ( raw_value, options? ) {
	if ( not _opt( options, "coerce", false ) ) {
		return raw_value;
	}

	if ( not( raw_value instanceof String ) ) {
		return raw_value;
	}

	let text := trim(raw_value);
	let lowered := lc(text);

	if ( lowered ≡ "true" ) {
		return true;
	}
	if ( lowered ≡ "false" ) {
		return false;
	}
	if ( lowered ≡ "null" or lowered ≡ "~" ) {
		return null;
	}
	if ( text ~ /^-?[0-9]+$/ ) {
		return int(text);
	}
	if ( text ~ /^-?(?:[0-9]+\.[0-9]+|\.[0-9]+)$/ ) {
		return 0 + text;
	}
	if (
		length text >= 2 and
		(
			(
				substr( text, 0, 1 ) ≡ "{" and
				substr( text, length text - 1, 1 ) ≡ "}"
			) or
			(
				substr( text, 0, 1 ) ≡ "[" and
				substr( text, length text - 1, 1 ) ≡ "]"
			)
		)
	) {
		try {
			from std/data/json import JSON;
			return new JSON().decode(text);
		}
		catch {
		}
	}

	return raw_value;
}

function _merge_values ( left, right, options? ) {
	let left_value := _unwrap_config_value(left);
	let right_value := _unwrap_config_value(right);

	if ( left_value instanceof Dict and right_value instanceof Dict ) {
		for ( let key in right_value.keys() ) {
			if ( left_value.exists(key) ) {
				left_value{(key)} := _merge_values(
					left_value.get(key),
					right_value.get(key),
					options,
				);
			}
			else {
				left_value{(key)} := right_value.get(key);
			}
		}
		return left_value;
	}

	if (
		left_value instanceof Array and
		right_value instanceof Array and
		_opt( options, "array_merge", "replace" ) ≡ "append"
	) {
		for ( let item in right_value ) {
			left_value.push(item);
		}
		return left_value;
	}

	return right_value;
}

function _simple_path_parts ( raw_path ) {
	let text := "" _ raw_path;
	if ( text ≡ "" ) {
		return [];
	}
	if ( substr( text, 0, 1 ) ≡ "/" ) {
		text := substr( text, 1 );
	}
	if ( text ≡ "" ) {
		return [];
	}

	let parts := [];
	for ( let part in split( text, "/" ) ) {
		next if part ≡ "";
		die `std/config simple path cannot contain complex selector '${part}'`
			if part ~ /[\*\[\]#@\(\)]/;
		parts.push(part);
	}
	return parts;
}

function _ensure_root_dict ( current ) {
	if ( current ≡ null ) {
		return {};
	}
	if ( current instanceof Dict ) {
		return current;
	}
	die "std/config expected Dict root for simple path mutation";
}

class Config extends Node {
	let _source := null;
	let _format := null;
	let _layers := [];

	method __build__ () {
		self.set_raw( self.raw ≡ null ? {}: self.raw );
		_layers := _layers ≡ null ? []: _layers;
		self._build_id();
	}

	static method detect_format ( source, fallback := null ) {
		return _detect_format_from_name( source, fallback );
	}

	static method from_data ( data, options? ) {
		return new Config(
			raw: _unwrap_config_value(data),
			_source: _opt( options, "source", null ),
			_format: _normalize_format( _opt( options, "format", null ) ),
			_layers: _opt( options, "layers", [] ),
		);
	}

	static method parse ( text, format, options? ) {
		let codec := _codec_for_format( format, options );
		let layer_source := _opt( options, "source", null );
		let decoded := codec.decode(text);
		return new Config(
			raw: decoded,
			_source: layer_source,
			_format: _normalize_format(format),
			_layers: [
				{
					source: layer_source,
					format: _normalize_format(format),
				},
			],
		);
	}

	static method load ( sources, options? ) {
		let cfg := new Config( raw: {}, _layers: [] );
		for ( let source in ( sources instanceof Array ? sources : [ sources ] ) ) {
			cfg.load_file( source, options );
		}
		return cfg;
	}

	method source () {
		return _source;
	}

	method format () {
		return _format;
	}

	method layers () {
		return _layers;
	}

	method to_data () {
		return self.raw;
	}

	method clone () {
		let cloned := new Config( raw: _merge_values( {}, self.raw, {} ) );
		cloned._layers := _layers.to_Array();
		cloned._source := _source;
		cloned._format := _format;
		return cloned;
	}

	method _delegate_node () {
		return Node.from_root( self.raw );
	}

	method type () {
		return self._delegate_node().type();
	}

	method can_have_named_children () {
		return self._delegate_node().can_have_named_children();
	}

	method can_have_indexed_children () {
		return self._delegate_node().can_have_indexed_children();
	}

	method can_have_named_indexed_children () {
		return self._delegate_node().can_have_named_indexed_children();
	}

	method children () {
		let out := [];
		for ( let child in self._delegate_node().children() ) {
			out.push(
				Node.wrap(
					child.raw(),
					self,
					child.key(),
					child.ix(),
				),
			);
		}
		return out;
	}

	method attributes () {
		let out := [];
		for ( let child in self._delegate_node().attributes() ) {
			out.push(
				Node.wrap(
					child.raw(),
					self,
					child.key(),
					child.ix(),
				),
			);
		}
		return out;
	}

	method do_action_on_child ( child, action ) {
		return super( child, action ) if action{op} ne ":=";

		let container := self.raw;
		if ( container instanceof Dict ) {
			let key := child.key();
			die "Path assignment expects string dict key" if key ≡ null;
			container{(key)} := action{value};
			return action{value};
		}
		if ( container instanceof Array ) {
			let ix := child.ix();
			die "Path assignment expects numeric array index" if ix ≡ null;
			container[ix] := action{value};
			return action{value};
		}
		if ( container instanceof PairList ) {
			let key := child.key();
			die "Path assignment expects string pairlist key" if key ≡ null;
			container.set( key, action{value} );
			return action{value};
		}
		return super( child, action );
	}

	method ref_on_child ( child ) {
		let container := self.raw;
		if ( container instanceof Dict ) {
			let key := child.key();
			die "Path assignment expects string dict key" if key ≡ null;
			return \ container{(key)};
		}
		if ( container instanceof Array ) {
			let ix := child.ix();
			die "Path assignment expects numeric array index" if ix ≡ null;
			return \ container[ix];
		}
		if ( container instanceof PairList ) {
			let key := child.key();
			die "Path assignment expects string pairlist key" if key ≡ null;
			return \ container{(key)};
		}
		return super(child);
	}

	method query ( pathish ) {
		return _compile_path(pathish).query(self);
	}

	method select ( pathish ) {
		return self.query(pathish);
	}

	method get_all ( pathish ) {
		return self.query(pathish);
	}

	method first ( pathish, fallback? ) {
		return _compile_path(pathish).first( self, fallback );
	}

	method get ( pathish, fallback? ) {
		return self.first( pathish, fallback );
	}

	method exists ( pathish ) {
		return _compile_path(pathish).exists(self);
	}

	method require ( pathish, message? ) {
		if ( self.exists(pathish) ) {
			return self.get(pathish);
		}
		die(
			message ?:
			`std/config required setting not found at '${pathish}'`
		);
	}

	method assign_first ( pathish, value, op := ":=", weak := false ) {
		return _compile_path(pathish).assign_first( self, value, op, weak );
	}

	method assign_all ( pathish, value, op := ":=", weak := false ) {
		return _compile_path(pathish).assign_all( self, value, op, weak );
	}

	method assign_maybe ( pathish, value, op := ":=", weak := false ) {
		return _compile_path(pathish).assign_maybe( self, value, op, weak );
	}

	method ref_first ( pathish ) {
		return _compile_path(pathish).ref_first(self);
	}

	method ref_all ( pathish ) {
		return _compile_path(pathish).ref_all(self);
	}

	method ref_maybe ( pathish ) {
		return _compile_path(pathish).ref_maybe(self);
	}

	method merge ( other, options? ) {
		let incoming := _unwrap_config_value(other);
		self.set_raw( _merge_values( self.raw, incoming, options ) );
		return self;
	}

	method overlay ( other, options? ) {
		return self.merge( other, options );
	}

	method merge_flat ( values, options? ) {
		return self if not( values instanceof Dict );

		let prefix := "" _ _opt( options, "prefix", "" );
		let separator := "" _ _opt( options, "separator", "__" );
		let downcase := _opt( options, "lowercase", false );

		for ( let key in values.keys() ) {
			let name := "" _ key;
			if ( prefix ≢ "" ) {
				next if substr( name, 0, length prefix ) ne prefix;
				name := substr( name, length prefix );
			}
			next if name ≡ "";

			let parts := [];
			for ( let part in split( name, separator ) ) {
				next if part ≡ "";
				parts.push( downcase ? lc(part) : part );
			}
			next if parts.length() = 0;

			self.set(
				"/" _ join( "/", parts ),
				_coerce_scalar_text( values.get(key), options ),
			);
		}

		return self;
	}

	method merge_env ( values, options? ) {
		return self.merge_flat( values, options );
	}

	method set ( pathish, value ) {
		let parts := _simple_path_parts(pathish);
		if ( parts.length() = 0 ) {
			self.set_raw(value);
			return value;
		}

		self.set_raw( _ensure_root_dict( self.raw ) );
		let cursor := self.raw;
		let i := 0;
		while ( i < parts.length() - 1 ) {
			let key := parts[i];
			if ( not cursor.exists(key) or cursor.get(key) ≡ null ) {
				cursor{(key)} := {};
			}
			else if ( not( cursor.get(key) instanceof Dict ) ) {
				die `std/config cannot create child path below non-Dict setting '${key}'`;
			}
			cursor := cursor.get(key);
			i++;
		}

		cursor{(parts[parts.length() - 1])} := value;
		return value;
	}

	method set_default ( pathish, value ) {
		if ( not self.exists(pathish) or self.get(pathish) ≡ null ) {
			return self.set( pathish, value );
		}
		return self.get(pathish);
	}

	method encode ( format?, options? ) {
		let chosen := _normalize_format(
			format ?: _format ?: "json"
		);
		return _codec_for_format( chosen, options ).encode( self.raw );
	}

	method save ( destination, options? ) {
		let path := _ensure_path_object(destination);
		let chosen := _normalize_format(
			_opt( options, "format", null ) ?:
			Config.detect_format( path, _format ?: "json" )
		);
		_codec_for_format( chosen, options ).dump( path, self.raw );
		return path;
	}

	method load_file ( source, options? ) {
		let path := _ensure_path_object(source);
		if ( _opt( options, "optional", false ) and not path.exists() ) {
			return self;
		}

		let chosen := _normalize_format(
			_opt( options, "format", null ) ?:
			Config.detect_format(path)
		);
		die `std/config could not determine format for '${path}'`
			if chosen ≡ null;

		let decoded := _codec_for_format( chosen, options ).load(path);
		self.merge( decoded, options );

		_source := path.to_String();
		_format := chosen;
		_layers.push(
			{
				source: _source,
				format: chosen,
			},
		);
		return self;
	}
}
