I think that your example is rejected not because of the semantics of #use,
but because toplevel directives in general are parsed at the level of
toplevel *phrases*, and not possibly-in-depth structure items. In other
words, a toplevel script is a sequence of structure items or toplevel
directives, but directives are not (nestable) structure items. The
documentation seems correct -- consistent with this behavior.

I see a way to do what you want using #mod_use, but it is a bit indirect
because #mod_use does not directly support signature checking:

    module type Foo_sig = sig ... end
    #mod_use "implementation.ml";;
    module Foo = (Implementation : Foo_sig);;

This approach defines a suitably restricted Foo, but it also exposes the
Implementation module in the rest of the scope. You can avoid this if you
use the same .ml name as the module name you want, so that shadowing hides
the implementation module

    module type Foo_sig = sig ... end
    #mod_use "foo.ml <http://implementation.ml>";;
    module Foo = (Foo : Foo_sig);;


On Sat, Feb 29, 2020 at 9:54 AM Richard W.M. Jones <rich@annexia.org> wrote:

> I was trying to break up a large ocaml interpreted script:
>
>   https://github.com/libguestfs/libnbd/blob/master/generator/generator
>
> The script contains sections like:
>
>   module Foo : sig
>   (* type signature *)
>   end = struct
>   (* very long implementation *)
>   end
>
> and it would be convenient for me to move the implementations into
> separate files.  However this doesn't work:
>
>   module Foo : sig
>   (* type signature *)
>   end = struct
>   #use "implementation.ml"  (* with or without ;; here *)
>   end
>
> So I guess #use only works for top level statements, which surprised
> me and contradicts the documentation here too:
>
>
> https://caml.inria.fr/pub/docs/manual-ocaml/toplevel.html#s%3Atoplevel-directives
>
> I could move the whole module definition to the file, but then I would
> lose the advantage of hiding the implementation while keeping the
> signature visible in the main file.
>
> Given the constraint that we can't use ocamlc or cppo (because of
> minimal build dependencies), are there any alternatives?  My first
> thought was C's cpp, but it seems impossible to get that working with
> #!/usr/bin/env and preserve the "scriptiness" of being able to just do
> ./generator/generator to run it.
>
> Rich.
>