dlangspec.pdf?

[H. S. Teoh]

On Wed, Jan 09, 2013 at 11:01:32AM -0800, Walter Bright wrote:
> On 1/9/2013 2:40 AM, Philippe Sigaud wrote:
> >On Wed, Jan 9, 2013 at 2:05 AM, Walter Bright
> ><newshound2 at digitalmars.com> wrote:
> >
> >>I'd still like to see it done as a phobos module. Maybe an
> >>enhancement request?
> >
> >So, this should:
> >
> >- take a .ddoc file for macro definition, or a [name, code] range of
> >  pairs.
> >- read an input range
> >     - this range can be a standard D file, a .dd or whatever. That
> >       means parsing D comments...
> >- find any macro definition
> >- find any $(NAME Args,) call, expand it recursively. Repeat until
> >  nothing changes anymore. This should be done lazily (through the
> >  input range interface), in case the user want to stop before the
> >  end.
> >- output the result as a range.
> >
> >What I'm not clear about, is: if the input is a D source file, should
> >the expander strip any D code from it? Should this return a
> >full-fledged documentation (ie, find the documented symbols...) or
> >just blindly expand DDoc macros.
> >
> 
> No no no. The module gets its input from an InputRange. Not a file.
> It gets its macro definitions, which are NAME=VALUE pairs, from an
> associative array of them.

I agree, the interface should be as generic as possible. I think it
would be nice to have a separate function for parsing macro definitions.
So the API should look something like this:

	Result expandDdocMacros(I,Result)(I inputRange,
			string[string] macroDefs)
		if (isInputRange!I && isSomeChar!(ElementType!I))
	{ ... }

	string[string] parseMacroDefs(I)(I inputRange)
		if (isInputRange!I && isSomeChar!(ElementType!I))
	{ ... }

Then you can use it something like this:

	void main() {
		auto macrodefs = File(macroFile);
		auto inputfile = File(ddocFile);

		auto expanded = expandDdocMacros(inputfile.byChar(),
						macrodefs.byChar());
		static assert(isInputRange!(typeof(expanded)));

		stdout.write(expanded);
	}

You can also feed it all sorts of stuff, like network input:

	string[string] builtinMacros = ...;

	// Online Ddoc expander!
	void myCgiApp(HttpRequest req, ref HttpResponse resp) {
		static assert(isInputRange!(typeof(req.data)) &&
			isSomeChar!(ElementType!(typeof(req.data))));

		auto result = expandDdocMacros(req.data, builtinMacros);
		resp.put(result);
	}

Etc., etc.. D ranges are an extremely powerful concept.


T

-- 
Без труда не выловишь и рыбку из пруда.