On 08/01/2014, at 11:34 PM, GitHub wrote:
> Log Message:
> -----------
> Add LP tool and webserver display.
Specs below. Here's the rationale.
At present "flx_tangle" can extract at most two files from an fdoc:
1. A Felix file
basename.flx
from all the @felix lines in the document, concatenated, and
2. An expect file
basename.expect
from all the @expect lines in the document, concatenated.
Whilst "flx" can execute the felix part of any fdoc directly,
it cannot also check the expected output, so if there is any,
you have to run flx_tangle, and process the extracted *.flx
file instead, with the corresponding expect file.
This is great for simple tutorial pages, but it starts to fall down
for more complex tutorials which might involve multiple
examples, multiple files being separately compiled,
files including C++ files, or cases involving build scripts.
With the new tool flx_iscr ... named in honour of my old LP
tool interscript, which is written in Python and STILL hanging
around in the bootstrapping part of the build system because it's
still the only way to set up the configuration data ...
it is possible to extract arbitrary files.
There are only two commands:
@tangler nick = filename
defines a tangler object (text buffer) with a given nickname,
and then
@tangle nick
stuff
@next-command-or-eof ...
appends stuff to the buffer for that nick. At the end, the buffers
are written to the files specified (unless the content hasn't changed).
By inventing some convention, we can do something like:
@tangler example = ex1.flx
@tangler expected = ex1.expect
@tangler make = make.sh
A tutorial example hello world:
@tangle example
println$ "Hello World";
@
and of course we expect:
@tangle expected
Hello World
@
and here's the script to check it works:
@tangle make
flx --expect ex1
and then say:
flx_iscr tut1.fdoc tut1
sh make.sh
(for example .. )
It's clear this "can do anything". For example we can pack docs, library code,
regression tests, tutorial examples, and build and installation code into
a single file and distribute it as a "package".
With suitable fiddling Mike Maul's scoop can be adapted to use
this convention. It will handle the downloading, testing, and installation
of packages, but now a package is a single file of source, and
"what to do with it" is dictated by the contents of the file itself.
[Scoop pretty much already does this]
With this format we also need a packing tool. This basically
takes the sources in a directory and packs them into the
above format. So you can develop with a set of files
but distribute a single file.
There's a core difference between this kind of literate source
file package and, say, a tarball: the webserver can display
the package directly. And of course the programmer can
write one directly. For "tutorial examples" this avoids the
problem of "linking" the documentation to the sources.
With some fiddling there are some advances to be made.
One is to get rid of flx_tangle. We just need a tangler spec like:
tangler default = basename.flx
where "basename" means "the basename of the current file"
and "default" means that @felix invokes this tangler.
Ditto for expect. In other words flx_iscr can be extended to handle
@felix and @expect as special cases and we can chuck flx_tangle.
A more advanced scenario would be to get rid of flx_iscr as well.
We can certainly "add" flx_iscr logic to "flx" somehow.
We can also look at getting "flxg" compiler to understand a bit of it.
Originally my thought was that
@tangler fred = somefile
maps to
var fred = fopen_output "somefile";
and @tangle fred (lines) @... maps to
write (fred, """
(lines)
""";
so actually we could *execute* the file using flx.
In other words getting rid of flx_iscr by using the parser.
After all the parser invokes Scheme commands so it
can do anything .. :)
But I thought .. one step at a time. I need the basic version
right now, because I'm not willing to hand synchronise
documentation and code.
So I invoke the great god of Agile.
>
> Add flx_iscr.flx tool and make webserver display
> something approximately right for the new commands.
>
> flx_iscr filename optional-directory
>
> processes filename and writes files into optional-directory.
> If the latter isn't specified the current directory is used.
>
> Commands have the form:
>
> @tangler nick = filename
> @tangle nick
> ...
>
> The first command defines a tangler with nickname nick,
> associated with optional-directory/filename.
>
> The second command populates a buffer associated with the given
> nickname with lines following the @tangle command up to the next
> @command or the end of file.
>
> Any number of tangle commands to the
> same nick are allowed. The nick must be defined by a tangler command
> and tangler commands must only define a nick once, otherwise
> the program aborts.
>
> After the input file is processed the aggregated contents of each
> tangle buffer are compared to the associated file. If the contents
> differ from the file, the buffer is written to the file.
>
> The comparison is done to avoid changing the latest modification
> date for the file which may be used in dependency checking.
>
> Any directories are autocreated.
>
> The tool currently cannot distinguish a non-existant file from
> a file with empty contents, so if a file doesn't exist and no
> data is tangled to it, it will not be created.
>
> The webserver currently recognises only files with ".flx"
> or ".cxx" extensions as Felix and C++ files. Any other filename
> extension is typeset as preformt data. To be extended later!
--
john skaller
skal...@users.sourceforge.net
http://felix-lang.org
------------------------------------------------------------------------------
Rapidly troubleshoot problems before they affect your business. Most IT
organizations don't have a clear picture of how application performance
affects their revenue. With AppDynamics, you get 100% visibility into your
Java,.NET, & PHP application. Start your 15-day FREE TRIAL of AppDynamics Pro!
http://pubads.g.doubleclick.net/gampad/clk?id=84349831&iu=/4140/ostg.clktrk
_______________________________________________
Felix-language mailing list
Felix-language@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/felix-language
