PLANNED.txt

/*
MetaC Preprocessor - A macro processor for preprocessing usage.
Copyright (C) 2022 Jared A. Maddox

This program is free software; you can redistribute it and/or modify it
under the terms of version 2 of the GNU General Public License as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the:
	Free Software Foundation, Inc.,
	59 Temple Place, Suite 330,
	Boston, MA 02111-1307 USA
*/

Needed directives:
	_enddef, _endif, _endset, _endcount /* These should all be INLINE directives, not */
		/*  freshline, to allow better whitespace control! */
	
	_emit_string(^ string ^) /* Converts the string to tokens and immediately outputs them. */
	
		/* Inline, the string will be used as if it was a source file. Note that the things */
		/*  contained inside square brackets are optional. */
	_include_text(^ string [, dir_ref, file [, line, column ] ] ^)
		/* dir_ref is a name token as a string, matching one provided on the command line */
		/*  and/or in preprocessor configuration files along with a directory path- this */
		/*  is used to provide a better version of the C preprocessor differentiation */
		/*  between #include<> and #include""- in MetaCPP, you not only get to use the */
		/*  "standard library" ( "_stdlib" ) and "current working directory" ( "_curdir" ) */
		/*  source directories, but you can define custom ones for e.g. libraries provided */
		/*  by other projects; file is a path (once again, as a string) from the directory */
		/*  specified by dir_ref to the individual file that is to be included, with all */
		/*  special names such as ".", "..", and "~" resolved + eliminated BEFORE adding to */
		/*  dir_ref for the sake of confining the possible search directories. */
	_include_file(^ dir_ref, file ^)
	_require_file(^ dir_ref, file ^) /* See _include_file. */
		/* Packages file contents into a macro. See also _include_file and _define. */
	_macroize_file(^ dir_ref, file, name ^)
	
		/* Line scoped. The contents of plain square brackets are either optional */
		/*  (body_tokens), or semi-optional (the arg_names stuff literally markes a */
		/*  particular define as being a function macro). Note that the body_tokens can */
		/*  include newlines without requiring them to be escaped: the define is marked by */
		/*  the use of _enddef, NOT by a newline. Defines CANNOT (at least currently) be */
		/*  nested, but are allowed to contain _if(^ ^), as well as to be contained BY */
		/*  _if(^  ^) bodies (but not conditions). */
	_define(^ name ^) [ [^ arg_names, ... ^] ]
			[ body_tokens ]
		_enddef(^ ^)
		/* Line scoped. See _define, excepting that all forset defines are function style, */
		/*  and arbitrary numbers of _forsubset/_endsubfor pairs can be used inside of it */
		/*  to specify individual "bite" sizes for the args under the requirement that no */
		/*  two are allowed to have the SAME size of bite. A subset with zero named */
		/*  arguments is illegal. */
	_forset(^ name ^)
		_forsubset[^ arg_names, ... ^]
			[ body_tokens ]
		_endsubfor
		_endfor
		/* As with forset, but without subsets, and running the same number of times as */
		/*  provided a invocation. */
	_forcount(^ name ^)
		[ body_tokens ]
		_endfor
	_if(^ condition ^) /* Works like in C. */
		_else
		_elif(^ condition ^)
		_endif
	
	_concatenate(^ a, b ^)
	_stringify(^ argument ^)
	
	_char_findfirst(^ str, chr ^)
	_strmatch(^ str_a, str_b ^)
	_strcopy(^ str, start_offset, length ^)
	_strlen(^ str ^)
	_utctime(^ ^)
	_localtime(^ ^)
	_elapsedtime(^ ^)
	
	_randint(^ ^)
	_randstr(^ ^)
	_RAND_MAX(^ ^)
	
	_str2int(^ str ^)
	_str2float(^ str ^)
	
	_num2sign(^ num ^)
	_float2arr(^ flt ^)
	_ceil(^ num ^)
	_floor(^ num ^)
	_trunc(^ num ^)
	_round(^ num ^)
	_isunordered(^ flt_a, flt_b ^)
	
	_alert(^ msg... ^)
	_error(^ msg... ^)
	_preproc_assert(^ num, err_message... ^)
	
		/* immediately and recursively runs "code" through the entire macro */
		/*  handling system, essentially until there aren't any macros or */
		/*  directives left uncalled from "code", even if embedded into e.g. */
		/*  a _define(^^). This is mostly useful inside defines. */
	_immediate(^ code ^)
		/* encodes an invocation of _immediate(^^) for executation at */
		/*  whatever the normal time is- this is mostly useful inside */
		/*  defines. */
	_embed_immediate(^ code ^)