ul4on_pkg.sql

create or replace package UL4ON_PKG
as
	/******************************************************************************\
	UL4ON is a lightweight text-based crossplatform data interchange format.

	As the name suggests its purpose is to transport the object types supported by
	UL4. For more info about UL4 see `http://python.livinglogic.de/UL4.html` and for
	more info about UL4ON see `http://python.livinglogic.de/UL4ON.html`.

	`ul4on_pkg` can be used for creating UL4ON dumps iteratively. For example
	creating an UL4ON dump of a list with two strings can be done like this::

		declare
			c_out clob;
		begin
			ul4on_pkg.beginlist(c_out);
				ul4on_pkg.str(c_out, 'foo');
				ul4on_pkg.str(c_out, 'bar');
			ul4on_pkg.endlist(c_out);
		end;

	The CLOB generated by this will contain `l s"foo" s"bar" ]`. Any
	implementation of UL4ON will be able to deserialize this dump back into the
	original string list.
	\******************************************************************************/
	type backrefregistry is table of integer index by varchar2(300);

	-- Methods for outputting various objects into the UL4ON dump
	procedure none(c_out in out nocopy clob);
	procedure bool(c_out in out nocopy clob, p_value in integer);
	procedure int(c_out in out nocopy clob, p_value in integer);
	procedure float(c_out in out nocopy clob, p_value in number);
	procedure color(c_out in out nocopy clob, p_red in integer, p_green in integer, p_blue in integer, p_alpha in integer);
	procedure date_(c_out in out nocopy clob, p_value date);
	procedure date_(c_out in out nocopy clob, p_value timestamp);
	procedure datetime(c_out in out nocopy clob, p_value date);
	procedure datetime(c_out in out nocopy clob, p_value timestamp);
	procedure timedelta(c_out in out nocopy clob, p_days integer := 0, p_seconds integer := 0, p_microseconds integer := 0);
	procedure monthdelta(c_out in out nocopy clob, p_months integer := 0);
	procedure slice(c_out in out nocopy clob, p_start integer := null, p_stop integer := null);
	procedure str(c_out in out nocopy clob, p_value in varchar2);
	procedure str(c_out in out nocopy clob, p_registry in out nocopy backrefregistry, p_value in varchar2);
	procedure str(c_out in out nocopy clob, p_value in clob);
	procedure template(
		c_out in out nocopy clob,
		p_name varchar2,
		p_source in clob,
		p_signature varchar2 := null,
		p_whitespace varchar2 := 'keep',
		p_startdelim varchar2 := '<?',
		p_enddelim varchar2 := '?>'
	);

	-- Method for outputting a string key (simply calls str())
	procedure key(c_out in out nocopy clob, p_key in varchar2);
	procedure key(c_out in out nocopy clob, p_registry in out nocopy backrefregistry, p_key in varchar2);

	-- Methods for outputting key/value pairs inside a dictionary
	procedure keynone(c_out in out nocopy clob, p_key in varchar2);
	procedure keybool(c_out in out nocopy clob, p_key in varchar2, p_value in integer);
	procedure keyint(c_out in out nocopy clob, p_key in varchar2, p_value in integer);
	procedure keyfloat(c_out in out nocopy clob, p_key in varchar2, p_value in number);
	procedure keycolor(c_out in out nocopy clob, p_key in varchar2, p_red in integer, p_green in integer, p_blue in integer, p_alpha in integer);
	procedure keydate(c_out in out nocopy clob, p_key in varchar2, p_value date);
	procedure keydate(c_out in out nocopy clob, p_key in varchar2, p_value timestamp);
	procedure keydatetime(c_out in out nocopy clob, p_key in varchar2, p_value date);
	procedure keydatetime(c_out in out nocopy clob, p_key in varchar2, p_value timestamp);
	procedure keytimedelta(c_out in out nocopy clob, p_key in varchar2, p_days integer := 0, p_seconds integer := 0, p_microseconds integer := 0);
	procedure keymonthdelta(c_out in out nocopy clob, p_key in varchar2, p_months integer := 0);
	procedure keyslice(c_out in out nocopy clob, p_key in varchar2, p_start integer := null, p_stop integer := null);
	procedure keystr(c_out in out nocopy clob, p_key in varchar2, p_value in varchar2);
	procedure keystr(c_out in out nocopy clob, p_key in varchar2, p_value in clob);

	-- Begin and end a list object
	procedure beginlist(c_out in out nocopy clob);
	procedure endlist(c_out in out nocopy clob);

	-- Begin and end a set object
	procedure beginset(c_out in out nocopy clob);
	procedure endset(c_out in out nocopy clob);

	-- Begin and end a dict object
	procedure begindict(c_out in out nocopy clob, p_ordered integer := 0);
	procedure enddict(c_out in out nocopy clob);

	-- Begin and end a custom object
	procedure beginobject(c_out in out nocopy clob, p_type varchar2);
	function beginobject(c_out in out nocopy clob, p_type in varchar2, p_registry in out nocopy backrefregistry, p_id in varchar2) return boolean;
	procedure endobject(c_out in out nocopy clob);

	-- Append another UL4ON dump (this dump is independent of the first one and has its own backref counter)
	procedure append(c_out in out nocopy clob, p_value in clob);
end;

/

create or replace package body UL4ON_PKG
as
	procedure none(c_out in out nocopy clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 'n');
	end;

	procedure bool(c_out in out nocopy clob, p_value in integer)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		elsif p_value != 0 then
			dbms_lob.writeappend(c_out, 2, 'bT');
		else
			dbms_lob.writeappend(c_out, 2, 'bF');
		end if;
	end;

	procedure int(c_out in out nocopy clob, p_value in integer)
	as
		v_strvalue varchar2(50);
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			v_strvalue := to_char(p_value);
			dbms_lob.writeappend(c_out, 1, 'i');
			dbms_lob.writeappend(c_out, length(v_strvalue), v_strvalue);
		end if;
	end;

	procedure float(c_out in out nocopy clob, p_value in number)
	as
		v_strvalue varchar2(50);
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			v_strvalue := trim(to_char(p_value, '999999999999999999999999999999.9999999999'));
			dbms_lob.writeappend(c_out, 1, 'f');
			dbms_lob.writeappend(c_out, length(v_strvalue), v_strvalue);
		end if;
	end;

	procedure color(c_out in out nocopy clob, p_red in integer, p_green in integer, p_blue in integer, p_alpha in integer)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 'c');
		int(c_out, p_red);
		int(c_out, p_green);
		int(c_out, p_blue);
		int(c_out, p_alpha);
	end;

	procedure timedelta(c_out in out nocopy clob, p_days integer := 0, p_seconds integer := 0, p_microseconds integer := 0)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 't');
		int(c_out, p_days);
		int(c_out, p_seconds);
		int(c_out, p_microseconds);
	end;

	procedure monthdelta(c_out in out nocopy clob, p_months integer := 0)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 'm');
		int(c_out, p_months);
	end;

	procedure date_(c_out in out nocopy clob, p_value date)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			dbms_lob.writeappend(c_out, 1, 'x');
			int(c_out, extract(year from p_value));
			int(c_out, extract(month from p_value));
			int(c_out, extract(day from p_value));
		end if;
	end;

	procedure date_(c_out in out nocopy clob, p_value timestamp)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			dbms_lob.writeappend(c_out, 1, 'x');
			int(c_out, extract(year from p_value));
			int(c_out, extract(month from p_value));
			int(c_out, extract(day from p_value));
		end if;
	end;

	procedure datetime(c_out in out nocopy clob, p_value date)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			dbms_lob.writeappend(c_out, 1, 'z');
			int(c_out, extract(year from p_value));
			int(c_out, extract(month from p_value));
			int(c_out, extract(day from p_value));
			int(c_out, to_number(to_char(p_value, 'HH24')));
			int(c_out, to_number(to_char(p_value, 'MI')));
			int(c_out, to_number(to_char(p_value, 'SS')));
			int(c_out, 0);
		end if;
	end;

	procedure datetime(c_out in out nocopy clob, p_value timestamp)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			dbms_lob.writeappend(c_out, 1, 'z');
			int(c_out, extract(year from p_value));
			int(c_out, extract(month from p_value));
			int(c_out, extract(day from p_value));
			int(c_out, extract(hour from p_value));
			int(c_out, extract(minute from p_value));
			int(c_out, trunc(extract(second from p_value)));
			int(c_out, to_number(to_char(p_value, 'FF6')));
		end if;
	end;

	procedure slice(c_out in out nocopy clob, p_start integer := null, p_stop integer := null)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 'r');
		int(c_out, p_start);
		int(c_out, p_stop);
	end;

	procedure writeul4onstr(c_out in out nocopy clob, p_value in varchar2)
	as
		v_buffer varchar2(32000 char);
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		end if;

		if length(p_value) <= 16000 then
			v_buffer := replace(replace(p_value, '\', '\\'), '"', '\"');
			dbms_lob.writeappend(c_out, length(v_buffer), v_buffer);
		else
			for i in 0 .. trunc((length(p_value) - 1)/16000) loop
				v_buffer := substr(p_value, i * 16000 + 1, 16000);
				v_buffer := replace(replace(v_buffer, '\', '\\'), '"', '\"');
				dbms_lob.writeappend(c_out, length(v_buffer), v_buffer);
			end loop;
		end if;
	end;

	procedure str(c_out in out nocopy clob, p_value in varchar2)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			dbms_lob.writeappend(c_out, 2, 's"');
			writeul4onstr(c_out, p_value);
			dbms_lob.writeappend(c_out, 1, '"');
		end if;
	end;

	procedure str(c_out in out nocopy clob, p_registry in out nocopy backrefregistry, p_value in varchar2)
	as
		v_strindex varchar2(10);
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		elsif length(p_value) < 300-4 then -- the key must fit in the backrefregistry, so we refuse to store long strings in the registry
			if p_registry.exists('str:' || p_value) then
				v_strindex := to_char(p_registry('str:' || p_value));
				dbms_lob.writeappend(c_out, 1, '^');
				dbms_lob.writeappend(c_out, length(v_strindex), v_strindex);
			else
				dbms_lob.writeappend(c_out, 2, 'S"');
				writeul4onstr(c_out, p_value);
				dbms_lob.writeappend(c_out, 1, '"');
				p_registry('str:' || p_value) := p_registry.count;
			end if;
		else
			dbms_lob.writeappend(c_out, 2, 's"');
			writeul4onstr(c_out, p_value);
			dbms_lob.writeappend(c_out, 1, '"');
		end if;
	end;

	procedure str(c_out in out nocopy clob, p_value in clob)
	as
		v_buffer varchar2(32000);
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is null then
			dbms_lob.writeappend(c_out, 1, 'n');
		else
			dbms_lob.writeappend(c_out, 2, 's"');

			for i in 0 .. trunc((dbms_lob.getlength(p_value) - 1 )/10000) loop
				v_buffer := dbms_lob.substr(p_value, 10000, i * 10000 + 1);
				writeul4onstr(c_out, v_buffer);
			end loop;

			dbms_lob.writeappend(c_out, 1, '"');
		end if;
	end;

	procedure template(
		c_out in out nocopy clob,
		p_name varchar2,
		p_source in clob,
		p_signature varchar2 := null,
		p_whitespace varchar2 := 'keep',
		p_startdelim varchar2 := '<?',
		p_enddelim varchar2 := '?>'
	)
	as
	begin
		beginobject(c_out, 'de.livinglogic.ul4.template');
			none(c_out); -- The version `None` means that the template must be compiled from source
			str(c_out, p_name);
			str(c_out, p_source);
			str(c_out, p_signature);
			str(c_out, p_whitespace);
			str(c_out, p_startdelim);
			str(c_out, p_enddelim);
		endobject(c_out);
	end;

	procedure key(c_out in out nocopy clob, p_key in varchar2)
	as
	begin
		str(c_out, p_key);
	end;

	procedure key(c_out in out nocopy clob, p_registry in out nocopy backrefregistry, p_key in varchar2)
	as
	begin
		str(c_out, p_registry, p_key);
	end;

	procedure keynone(c_out in out nocopy clob, p_key in varchar2)
	as
	begin
		key(c_out, p_key);
		none(c_out);
	end;

	procedure keybool(c_out in out nocopy clob, p_key in varchar2, p_value in integer)
	as
	begin
		key(c_out, p_key);
		bool(c_out, p_value);
	end;

	procedure keyint(c_out in out nocopy clob, p_key in varchar2, p_value in integer)
	as
	begin
		key(c_out, p_key);
		int(c_out, p_value);
	end;

	procedure keyfloat(c_out in out nocopy clob, p_key in varchar2, p_value in number)
	as
	begin
		key(c_out, p_key);
		float(c_out, p_value);
	end;

	procedure keydate(c_out in out nocopy clob, p_key in varchar2, p_value date)
	as
	begin
		key(c_out, p_key);
		date_(c_out, p_value);
	end;

	procedure keydate(c_out in out nocopy clob, p_key in varchar2, p_value timestamp)
	as
	begin
		key(c_out, p_key);
		date_(c_out, p_value);
	end;

	procedure keydatetime(c_out in out nocopy clob, p_key in varchar2, p_value date)
	as
	begin
		key(c_out, p_key);
		datetime(c_out, p_value);
	end;

	procedure keydatetime(c_out in out nocopy clob, p_key in varchar2, p_value timestamp)
	as
	begin
		key(c_out, p_key);
		datetime(c_out, p_value);
	end;

	procedure keytimedelta(c_out in out nocopy clob, p_key in varchar2, p_days integer := 0, p_seconds integer := 0, p_microseconds integer := 0)
	as
	begin
		key(c_out, p_key);
		timedelta(c_out, p_days, p_seconds, p_microseconds);
	end;

	procedure keymonthdelta(c_out in out nocopy clob, p_key in varchar2, p_months integer := 0)
	as
	begin
		key(c_out, p_key);
		monthdelta(c_out, p_months);
	end;

	procedure keyslice(c_out in out nocopy clob, p_key in varchar2, p_start integer := null, p_stop integer := null)
	as
	begin
		key(c_out, p_key);
		slice(c_out, p_start, p_stop);
	end;

	procedure keycolor(c_out in out nocopy clob, p_key in varchar2, p_red in integer, p_green in integer, p_blue in integer, p_alpha in integer)
	as
	begin
		key(c_out, p_key);
		color(c_out, p_red, p_green, p_blue, p_alpha);
	end;

	procedure keystr(c_out in out nocopy clob, p_key in varchar2, p_value in varchar2)
	as
	begin
		key(c_out, p_key);
		str(c_out, p_value);
	end;

	procedure keystr(c_out in out nocopy clob, p_key in varchar2, p_value in clob)
	as
	begin
		key(c_out, p_key);
		str(c_out, p_value);
	end;

	procedure beginlist(c_out in out nocopy clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 'l');
	end;

	procedure endlist(c_out in out nocopy clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, ']');
	end;

	procedure beginset(c_out in out nocopy clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 'y');
	end;

	procedure endset(c_out in out nocopy clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, '}');
	end;

	procedure begindict(c_out in out nocopy clob, p_ordered integer := 0)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, case when p_ordered = 0 then 'd' else 'e' end);
	end;

	procedure enddict(c_out in out nocopy clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, '}');
	end;

	procedure beginobject(c_out in out nocopy clob, p_type varchar2)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, 'o');
		str(c_out, p_type);
	end;

	function beginobject(c_out in out nocopy clob, p_type in varchar2, p_registry in out nocopy backrefregistry, p_id in varchar2)
	return boolean
	as
		v_strindex varchar2(12);
	begin
		if p_id is null then
			none(c_out);
			return false;
		else
			if c_out is null then
				dbms_lob.createtemporary(c_out, true);
			else
				dbms_lob.writeappend(c_out, 1, ' ');
			end if;
			if p_registry.exists(p_type || ':' || p_id) then
				v_strindex := to_char(p_registry(p_type || ':' || p_id));
				dbms_lob.writeappend(c_out, 1, '^');
				dbms_lob.writeappend(c_out, length(v_strindex), v_strindex);
				return false;
			else
				dbms_lob.writeappend(c_out, 1, 'O');
				p_registry(p_type || ':' || p_id) := p_registry.count;
				str(c_out, p_registry, p_type);
				return true;
			end if;
		end if;
	end;

	procedure endobject(c_out in out nocopy clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		dbms_lob.writeappend(c_out, 1, ')');
	end;

	procedure append(c_out in out nocopy clob, p_value in clob)
	as
	begin
		if c_out is null then
			dbms_lob.createtemporary(c_out, true);
		else
			dbms_lob.writeappend(c_out, 1, ' ');
		end if;
		if p_value is not null and dbms_lob.getlength(p_value) != 0 then
			dbms_lob.append(c_out, p_value);
		end if;
	end;
end;

/