├── manual ├── refman │ ├── .gitignore │ ├── Makefile │ ├── const.etex │ ├── refman.etex │ ├── compunit.etex │ ├── values.etex │ ├── names.etex │ ├── patterns.etex │ ├── modules.etex │ └── types.etex ├── tutorials │ ├── .gitignore │ └── Makefile ├── cmds │ ├── .gitignore │ ├── ocamlbuild.etex │ ├── browser.etex │ ├── Makefile │ ├── afl-fuzz.etex │ ├── plugins.etex │ ├── spacetime.etex │ ├── profil.etex │ └── depend.etex ├── textman │ └── .gitignore ├── infoman │ └── .gitignore ├── htmlman │ ├── libgraph.gif │ ├── next_motif.gif │ ├── contents_motif.gif │ ├── previous_motif.gif │ ├── fonts │ │ ├── fira-sans-v8-latin-regular.eot │ │ ├── fira-sans-v8-latin-regular.ttf │ │ ├── fira-sans-v8-latin-regular.woff │ │ └── fira-sans-v8-latin-regular.woff2 │ └── .gitignore ├── library │ ├── libgraph.png │ ├── .gitignore │ ├── compiler_libs.mld │ ├── libnum.etex │ ├── libgraph.fig │ ├── libstr.etex │ ├── libdynlink.etex │ ├── libbigarray.etex │ ├── core.etex │ ├── Makefile │ ├── libthreads.etex │ ├── libgraph.etex │ ├── compilerlibs.etex │ ├── libunix.etex │ └── builtin.etex ├── .gitignore ├── manual.info.header ├── texstuff │ └── .gitignore ├── index.tex ├── manual.tex ├── foreword.etex ├── manual.hva ├── style.css ├── allfiles.etex ├── manual.inf ├── Makefile ├── macros.hva ├── macros.tex └── biblio.etex ├── tests ├── .gitignore ├── README.md ├── check-stdlib-modules ├── Makefile └── cross_reference_checker.ml ├── styles ├── doc.tfm ├── docbf.tfm ├── docit.tfm ├── docmi.tfm ├── docrm.tfm ├── doctt.tfm ├── isolatin.sty ├── fullpage.sty ├── scroll.sty ├── caml.sty ├── ocamldoc.hva ├── syntaxdef.sty ├── syntaxdeftxt.sty ├── altindex.sty ├── caml-sl.sty ├── ocamldoc.sty ├── multind.sty ├── syntaxdef.hva ├── multicols.sty └── html.sty ├── .gitmodules ├── tools ├── .gitignore ├── transfmain.ml ├── Makefile ├── fix_index.sh ├── transf.mll ├── htmltransf.mll └── texquote2.ml ├── .travis-ci.sh ├── .travis.yml ├── LICENSE └── Makefile /manual/refman/.gitignore: -------------------------------------------------------------------------------- 1 | *.tex 2 | *.htex 3 | -------------------------------------------------------------------------------- /manual/tutorials/.gitignore: -------------------------------------------------------------------------------- 1 | *.tex 2 | *.htex 3 | -------------------------------------------------------------------------------- /tests/.gitignore: -------------------------------------------------------------------------------- 1 | /cross-reference-checker 2 | -------------------------------------------------------------------------------- /manual/cmds/.gitignore: -------------------------------------------------------------------------------- 1 | *.tex 2 | *.htex 3 | warnings.etex 4 | -------------------------------------------------------------------------------- /styles/doc.tfm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/styles/doc.tfm -------------------------------------------------------------------------------- /styles/docbf.tfm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/styles/docbf.tfm -------------------------------------------------------------------------------- /styles/docit.tfm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/styles/docit.tfm -------------------------------------------------------------------------------- /styles/docmi.tfm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/styles/docmi.tfm -------------------------------------------------------------------------------- /styles/docrm.tfm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/styles/docrm.tfm -------------------------------------------------------------------------------- /styles/doctt.tfm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/styles/doctt.tfm -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "ocaml"] 2 | path = ocaml 3 | url = https://github.com/ocaml/ocaml 4 | -------------------------------------------------------------------------------- /manual/textman/.gitignore: -------------------------------------------------------------------------------- 1 | manual.txt 2 | manual.hmanual.kwd 3 | *.haux 4 | *.hind 5 | *.htoc 6 | -------------------------------------------------------------------------------- /styles/isolatin.sty: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/styles/isolatin.sty -------------------------------------------------------------------------------- /manual/infoman/.gitignore: -------------------------------------------------------------------------------- 1 | *.haux 2 | *.hind 3 | *.info*.gz 4 | *.info.body* 5 | ocaml.hocaml.kwd 6 | -------------------------------------------------------------------------------- /manual/htmlman/libgraph.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/libgraph.gif -------------------------------------------------------------------------------- /manual/library/libgraph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/library/libgraph.png -------------------------------------------------------------------------------- /manual/htmlman/next_motif.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/next_motif.gif -------------------------------------------------------------------------------- /manual/htmlman/contents_motif.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/contents_motif.gif -------------------------------------------------------------------------------- /manual/htmlman/previous_motif.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/previous_motif.gif -------------------------------------------------------------------------------- /manual/library/.gitignore: -------------------------------------------------------------------------------- 1 | *.tex 2 | *.htex 3 | arithstatus.mli 4 | ocamldoc.out 5 | ocamldoc.sty 6 | compiler_libs.txt 7 | 8 | -------------------------------------------------------------------------------- /manual/.gitignore: -------------------------------------------------------------------------------- 1 | allfiles.tex 2 | biblio.tex 3 | foreword.tex 4 | version.tex 5 | warnings.etex 6 | warnings.tex 7 | foreword.htex 8 | manual.html 9 | -------------------------------------------------------------------------------- /styles/fullpage.sty: -------------------------------------------------------------------------------- 1 | \marginparwidth 0pt \oddsidemargin 0pt \evensidemargin 0pt \marginparsep 0pt 2 | \topmargin 0pt \textwidth 6.5in \textheight 8.5 in 3 | -------------------------------------------------------------------------------- /manual/htmlman/fonts/fira-sans-v8-latin-regular.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/fonts/fira-sans-v8-latin-regular.eot -------------------------------------------------------------------------------- /manual/htmlman/fonts/fira-sans-v8-latin-regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/fonts/fira-sans-v8-latin-regular.ttf -------------------------------------------------------------------------------- /manual/htmlman/fonts/fira-sans-v8-latin-regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/fonts/fira-sans-v8-latin-regular.woff -------------------------------------------------------------------------------- /manual/htmlman/fonts/fira-sans-v8-latin-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lkwq007/ocaml-manual-cn/HEAD/manual/htmlman/fonts/fira-sans-v8-latin-regular.woff2 -------------------------------------------------------------------------------- /manual/manual.info.header: -------------------------------------------------------------------------------- 1 | INFO-DIR-SECTION OCaml Programming Language 2 | START-INFO-DIR-ENTRY 3 | * ocaml: (ocaml). OCaml Reference Manual 4 | END-INFO-DIR-ENTRY 5 | -------------------------------------------------------------------------------- /tools/.gitignore: -------------------------------------------------------------------------------- 1 | transf.ml 2 | texquote2 3 | htmltransf.ml 4 | transf 5 | htmlgen 6 | htmlquote 7 | latexscan.ml 8 | dvi2txt 9 | *.dSYM 10 | *.cm[io] 11 | *.o 12 | -------------------------------------------------------------------------------- /manual/htmlman/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | *.haux 3 | *.hind 4 | compilerlibref 5 | libref 6 | manual.hmanual 7 | manual.hmanual.kwd 8 | manual.css 9 | *.htoc 10 | *.svg 11 | -------------------------------------------------------------------------------- /manual/texstuff/.gitignore: -------------------------------------------------------------------------------- 1 | *.aux 2 | *.dvi 3 | *.idx 4 | *.ilg 5 | *.ind 6 | *.log 7 | *.toc 8 | *.ipr 9 | *.txt 10 | *.pdf 11 | *.ps 12 | manual.out 13 | manual.out 14 | -------------------------------------------------------------------------------- /styles/scroll.sty: -------------------------------------------------------------------------------- 1 | % Modification to plaintext.sty to suppress page headings 2 | % and make pages contiguous when processed with dvi2txt 3 | 4 | \pagestyle{empty} 5 | \advance\voffset by -2\baselineskip 6 | -------------------------------------------------------------------------------- /tools/transfmain.ml: -------------------------------------------------------------------------------- 1 | let main() = 2 | let lexbuf = Lexing.from_channel stdin in 3 | if Array.length Sys.argv >= 2 && Sys.argv.(1) = "-html" 4 | then Htmltransf.main lexbuf 5 | else Transf.main lexbuf; 6 | exit 0;; 7 | 8 | Printexc.print main ();; 9 | -------------------------------------------------------------------------------- /manual/cmds/ocamlbuild.etex: -------------------------------------------------------------------------------- 1 | \chapter{The ocamlbuild compilation manager} \label{c:ocamlbuild} 2 | 3 | Since OCaml version 4.03, the ocamlbuild compilation manager is 4 | distributed separately from the OCaml compiler. The project is now 5 | hosted at \url{https://github.com/ocaml/ocamlbuild/}. 6 | -------------------------------------------------------------------------------- /manual/cmds/browser.etex: -------------------------------------------------------------------------------- 1 | \chapter{The browser/editor (ocamlbrowser)} \label{c:browser} 2 | %HEVEA\cutname{browser.html} 3 | 4 | Since OCaml version 4.02, the OCamlBrowser tool and the Labltk library 5 | are distributed separately from the OCaml compiler. The project is now 6 | hosted at \url{https://forge.ocamlcore.org/projects/labltk/}. 7 | -------------------------------------------------------------------------------- /manual/library/compiler_libs.mld: -------------------------------------------------------------------------------- 1 | {!indexlist} 2 | 3 | {1 Warning} 4 | This library is part of the internal OCaml compiler API, and is 5 | not the language standard library. 6 | There are no compatibility guarantees between releases, so code written 7 | against these modules must be willing to depend on specific OCaml compiler 8 | versions. 9 | 10 | -------------------------------------------------------------------------------- /tests/README.md: -------------------------------------------------------------------------------- 1 | These tests have for objective to test the consistency between the manual and 2 | the rest of the compiler sources: 3 | 4 | - `cross_reference_checker.ml` checks that reference to the manual from the 5 | compiler sources are still accurate. 6 | 7 | - `check-stdlib-modules` checks that all stdlib modules are linked from the 8 | main entry of the stdlib in the manual: `manual/manual/library/stdlib.etex` 9 | -------------------------------------------------------------------------------- /manual/index.tex: -------------------------------------------------------------------------------- 1 | \ifouthtml 2 | \begin{rawhtml} 3 | 10 | \end{rawhtml} 11 | \else 12 | \chapter*{库索引} 13 | \markright{库索引} 14 | \addcontentsline{toc}{chapter}{库索引} 15 | \myprintindex{\jobname.ind} 16 | \fi 17 | \chapter*{关键字索引} 18 | \markright{关键字索引} 19 | \addcontentsline{toc}{chapter}{关键字索引} 20 | \myprintindex{\jobname.kwd.ind} 21 | -------------------------------------------------------------------------------- /tools/Makefile: -------------------------------------------------------------------------------- 1 | TOPDIR=../ocaml 2 | COMPFLAGS=-I $(OTOPDIR)/otherlibs/str -I $(OTOPDIR)/otherlibs/unix 3 | include $(TOPDIR)/Makefile.tools 4 | 5 | all: texquote2 transf 6 | 7 | 8 | transf: transf.cmo htmltransf.cmo transfmain.cmo 9 | $(OCAMLC) -o $@ -g $^ 10 | 11 | transfmain.cmo: transf.cmo htmltransf.cmo 12 | 13 | texquote2: texquote2.ml 14 | $(OCAMLC) -o $@ $< 15 | 16 | %.cmo: %.ml 17 | $(OCAMLC) -c $< 18 | 19 | %.cmi: %.mli 20 | $(OCAMLC) -c $< 21 | 22 | %.ml: %.mll 23 | $(OCAMLLEX) $< 24 | 25 | 26 | .PHONY: clean 27 | clean: 28 | rm -f *.o *.cm? *.cmx? 29 | rm -f transf.ml htmltransf.ml 30 | rm -f texquote2 transf 31 | -------------------------------------------------------------------------------- /manual/library/libnum.etex: -------------------------------------------------------------------------------- 1 | \chapter{The num library: arbitrary-precision rational arithmetic} 2 | %HEVEA\cutname{libnum.html} 3 | 4 | The "num" library implements integer arithmetic and rational 5 | arithmetic in arbitrary precision. It was split off the core 6 | OCaml distribution starting with the 4.06.0 release, and can now be found 7 | at \url{https://github.com/ocaml/num}. 8 | 9 | New applications that need arbitrary-precision arithmetic should use the 10 | "Zarith" library (\url{https://github.com/ocaml/Zarith}) instead of the "Num" 11 | library, and older applications that already use "Num" are encouraged to 12 | switch to "Zarith". "Zarith" delivers much better performance than "Num" 13 | and has a nicer API. 14 | -------------------------------------------------------------------------------- /.travis-ci.sh: -------------------------------------------------------------------------------- 1 | # inspired by https://gist.github.com/avsm/6757425 2 | 3 | # hevea 4 | OPAM_DEPENDS="hevea" 5 | 6 | # info 7 | export OPAMYES=1 8 | export OPAMVERBOSE=1 9 | echo OCaml version 10 | ocaml -version 11 | echo OPAM versions 12 | opam --version 13 | opam --git-version 14 | 15 | # init opam 16 | opam init 17 | opam install ${OPAM_DEPENDS} 18 | eval `opam config env` 19 | 20 | # rm .gitignore of htmlman 21 | cd manual/htmlman 22 | rm .gitignore 23 | cd ../.. 24 | make 25 | # this part should not be put in the before_deploy part 26 | mkdir release 27 | { 28 | REFMAN_VERSION=`git describe --abbrev=0 --tags` && 29 | export RELEASENAME="ocaml-${REFMAN_VERSION}-" 30 | } || { 31 | export RELEASENAME="" 32 | } 33 | make release -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | dist: xenial 2 | language: c 3 | script: bash -ex .travis-ci.sh 4 | before_install: 5 | - sudo add-apt-repository ppa:jonathonf/texlive -y 6 | - sudo add-apt-repository ppa:apt-fast/stable -y 7 | - sudo apt-get update -q 8 | - sudo apt-get install apt-fast -y 9 | - sudo apt-fast install ocaml ocaml-native-compilers opam texlive-full -y 10 | deploy: 11 | - provider: pages 12 | local_dir: manual/htmlman 13 | skip-cleanup: true 14 | github-token: $GITHUB_TOKEN 15 | keep-history: true 16 | on: 17 | branch: master 18 | - provider: releases 19 | api_key: $GITHUB_TOKEN 20 | file_glob: true 21 | file: release/* 22 | skip_cleanup: true 23 | draft: true 24 | on: 25 | tags: true 26 | 27 | -------------------------------------------------------------------------------- /styles/caml.sty: -------------------------------------------------------------------------------- 1 | % CAML style option, for use with the caml-latex filter. 2 | 3 | \typeout{Document Style option `caml' <7 Apr 92>.} 4 | 5 | {\catcode`\^^M=\active % 6 | \gdef\@camlinputline#1^^M{\tt\##1\par} % 7 | \gdef\@camloutputline#1^^M{\tt#1\par} } % 8 | \def\@camlblankline{\medskip} 9 | \chardef\@camlbackslash="5C 10 | 11 | \def\caml{ 12 | \bgroup 13 | \flushleft 14 | \parindent 0pt 15 | \parskip 0pt 16 | \let\do\@makeother\dospecials 17 | \catcode`\^^M=\active 18 | \catcode`\\=0 19 | \catcode`\ \active 20 | \frenchspacing 21 | \@vobeyspaces 22 | \let\?\@camlinputline 23 | \let\:\@camloutputline 24 | \let\;\@camlblankline 25 | \let\\\@camlbackslash 26 | } 27 | 28 | \def\endcaml{ 29 | \endflushleft 30 | \egroup\noindent 31 | } 32 | -------------------------------------------------------------------------------- /tests/check-stdlib-modules: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | TMPDIR="${TMPDIR:-/tmp}" 4 | 5 | (cd $1/stdlib; ls -1 *.mli) | sed -e 's/\.mli//' >$TMPDIR/stdlib-$$-files 6 | cut -c 1 $TMPDIR/stdlib-$$-files | tr a-z A-Z >$TMPDIR/stdlib-$$-initials 7 | cut -c 2- $TMPDIR/stdlib-$$-files \ 8 | | paste -d '\0' $TMPDIR/stdlib-$$-initials - >$TMPDIR/stdlib-$$-modules 9 | 10 | exitcode=0 11 | for i in `cat $TMPDIR/stdlib-$$-modules`; do 12 | case $i in 13 | Stdlib | Camlinternal* | *Labels | Obj | Pervasives) continue;; 14 | esac 15 | grep -q -e '"'$i'" & p\.~\\pageref{'$i'} &' $1/manual/manual/library/stdlib.etex || { 16 | echo "Module $i is missing from stdlib.etex." >&2 17 | exitcode=2 18 | } 19 | done 20 | 21 | rm -f $TMPDIR/stdlib-$$-* 22 | 23 | exit $exitcode 24 | -------------------------------------------------------------------------------- /manual/tutorials/Makefile: -------------------------------------------------------------------------------- 1 | TOPDIR = ../../ocaml 2 | include $(TOPDIR)/Makefile.tools 3 | 4 | LD_PATH = "$(TOPDIR)/otherlibs/str:$(TOPDIR)/otherlibs/unix" 5 | 6 | TOOLS = ../../tools 7 | CAMLLATEX = $(SET_LD_PATH) \ 8 | $(OCAMLRUN) $(TOPDIR)/tools/caml-tex \ 9 | -repo-root $(TOPDIR) -n 80 -v false 10 | TEXQUOTE = $(OCAMLRUN) $(TOOLS)/texquote2 11 | TRANSF = $(SET_LD_PATH) $(OCAMLRUN) $(TOOLS)/transf 12 | 13 | 14 | FILES = coreexamples.tex lablexamples.tex objectexamples.tex \ 15 | moduleexamples.tex advexamples.tex polymorphism.tex 16 | 17 | 18 | etex-files: $(FILES) 19 | all: $(FILES) 20 | 21 | 22 | %.gen.tex: %.etex 23 | $(CAMLLATEX) $< -o $@ 24 | 25 | %.tex: %.gen.tex 26 | $(TEXQUOTE) < $< > $*.texquote_error.tex 27 | mv $*.texquote_error.tex $@ 28 | 29 | 30 | .PHONY: clean 31 | clean: 32 | rm -f *.tex 33 | -------------------------------------------------------------------------------- /styles/ocamldoc.hva: -------------------------------------------------------------------------------- 1 | \usepackage{alltt} 2 | \newenvironment{ocamldoccode}{\begin{alltt}}{\end{alltt}} 3 | \newenvironment{ocamldocdescription}{\begin{quote}}{\end{quote}} 4 | \newenvironment{ocamldoccomment}{\begin{quote}}{\end{quote}} 5 | 6 | 7 | \newenvironment{ocamldocindent}{\list{}{}\item\relax}{\endlist} 8 | \newenvironment{ocamldocsigend} 9 | {\noindent\quad\texttt{sig}\ocamldocindent} 10 | {\endocamldocindent 11 | \noindent\quad\texttt{end}\medskip} 12 | \newenvironment{ocamldocobjectend} 13 | {\noindent\quad\texttt{object}\ocamldocindent} 14 | {\endocamldocindent 15 | \noindent\quad\texttt{end}\medskip} 16 | 17 | \newcommand{\moduleref}[1]{\ifhtml\ahref{libref/#1.html}{\texttt{#1}}\fi} 18 | 19 | # For processing .tex generated by ocamldoc (for text manual) 20 | \newcommand{\ocamldocvspace}[1]{\vspace{#1}} -------------------------------------------------------------------------------- /styles/syntaxdef.sty: -------------------------------------------------------------------------------- 1 | \newif\ifspace 2 | \def\addspace{\ifspace \; \spacefalse \fi} 3 | \def\token#1{\addspace\hbox{\tt #1} \spacetrue} 4 | \def\nonterm#1{\addspace\nt{#1} \spacetrue} 5 | \def\nt#1{\hbox{\sl #1\/}} 6 | \def\brepet{\addspace\{} 7 | \def\erepet{\}} 8 | \def\boption{\addspace[} 9 | \def\eoption{]} 10 | \def\brepets{\addspace\{} 11 | \def\erepets{\}^+} 12 | \def\bparen{\addspace(} 13 | \def\eparen{)} 14 | \def\orelse{\mid \spacefalse} 15 | \def\is{ & ::= & \spacefalse } 16 | \def\alt{ \\ & \mid & \spacefalse } 17 | \def\cutline{ \\ & & \spacefalse } 18 | \def\sep{ \\[2mm] \spacefalse } 19 | \def\emptystring{\epsilon} 20 | \def\syntax{$$\begin{array}{rrl}\spacefalse} 21 | \def\endsyntax{\end{array}$$} 22 | \def\syntaxleft{$\begin{array}{rrl}\spacefalse} 23 | \def\endsyntaxleft{\end{array}$} 24 | \let\oldldots=\ldots 25 | \def\ldots{\spacefalse\oldldots} 26 | \def\synt#1{$\spacefalse#1$} 27 | -------------------------------------------------------------------------------- /tests/Makefile: -------------------------------------------------------------------------------- 1 | TOPDIR=$(abspath ../ocaml) 2 | include $(TOPDIR)/Makefile.tools 3 | MANUAL=$(TOPDIR)/../manual 4 | 5 | .PHONY: all 6 | all: check-cross-references check-stdlib 7 | 8 | .PHONY: tools 9 | tools: cross-reference-checker 10 | 11 | cross-reference-checker: cross_reference_checker.ml 12 | $(OCAMLC) $(TOPDIR)/compilerlibs/ocamlcommon.cma \ 13 | -I $(TOPDIR)/parsing -I $(TOPDIR)/driver \ 14 | $< -o $@ 15 | 16 | .PHONY: check-cross-references 17 | check-cross-references: cross-reference-checker 18 | $(SET_LD_PATH) \ 19 | $(OCAMLRUN) ./cross-reference-checker \ 20 | -auxfile $(MANUAL)/texstuff/manual.aux \ 21 | $(TOPDIR)/utils/warnings.ml \ 22 | $(TOPDIR)/driver/main_args.ml \ 23 | $(TOPDIR)/bytecomp/translmod.ml 24 | 25 | .PHONY: check-stdlib 26 | check-stdlib: 27 | ./check-stdlib-modules $(TOPDIR) 28 | 29 | 30 | .PHONY: clean 31 | clean: 32 | rm -f *.cm? *.cmx? cross-reference-checker 33 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The present documentation is copyright Institut National de Recherche 2 | en Informatique et en Automatique (INRIA). 3 | 4 | The OCaml documentation and user's manual may be reproduced and 5 | distributed in whole or in part, subject to the following conditions: 6 | 7 | - The copyright notice above and this permission notice must be 8 | preserved complete on all complete or partial copies. 9 | 10 | - Any translation or derivative work of the OCaml documentation and 11 | user's manual must be approved by the authors in writing before 12 | distribution. 13 | 14 | - If you distribute the OCaml documentation and user's manual in part, 15 | instructions for obtaining the complete version of this manual must 16 | be included, and a means for obtaining a complete version provided. 17 | 18 | - Small portions may be reproduced as illustrations for reviews or 19 | quotes in other works without this permission notice if proper 20 | citation is given. 21 | -------------------------------------------------------------------------------- /manual/refman/Makefile: -------------------------------------------------------------------------------- 1 | TOPDIR = ../../ocaml 2 | include $(TOPDIR)/Makefile.tools 3 | 4 | LD_PATH = "$(TOPDIR)/otherlibs/str:$(TOPDIR)/otherlibs/unix" 5 | 6 | TOOLS = ../../tools 7 | CAMLLATEX = $(SET_LD_PATH) \ 8 | $(OCAMLRUN) $(TOPDIR)/tools/caml-tex \ 9 | -repo-root $(TOPDIR) -n 80 -v false 10 | TEXQUOTE = $(OCAMLRUN) $(TOOLS)/texquote2 11 | TRANSF = $(SET_LD_PATH) $(OCAMLRUN) $(TOOLS)/transf 12 | 13 | 14 | FILES = refman.tex lex.tex names.tex values.tex const.tex types.tex \ 15 | patterns.tex expr.tex typedecl.tex modtypes.tex modules.tex compunit.tex \ 16 | exten.tex classes.tex 17 | 18 | 19 | etex-files: $(FILES) 20 | all: $(FILES) 21 | 22 | 23 | %.gen.tex: %.etex 24 | $(CAMLLATEX) $< -o $*_camltex.tex 25 | $(TRANSF) < $*_camltex.tex > $*.transf_error.tex 26 | mv $*.transf_error.tex $@ 27 | 28 | %.tex: %.gen.tex 29 | $(TEXQUOTE) < $< > $*.texquote_error.tex 30 | mv $*.texquote_error.tex $@ 31 | 32 | 33 | .PHONY: clean 34 | clean: 35 | rm -f *.tex 36 | -------------------------------------------------------------------------------- /manual/library/libgraph.fig: -------------------------------------------------------------------------------- 1 | #FIG 3.2 2 | Landscape 3 | Center 4 | Inches 5 | Letter 6 | 100.00 7 | Single 8 | -2 9 | 1200 2 10 | 2 1 0 1 0 7 0 0 -1 0.000 0 0 7 1 0 2 11 | 1 1 1.00 60.00 120.00 12 | 1050 3375 4575 3375 13 | 2 1 0 1 0 7 0 0 -1 0.000 0 0 -1 1 0 2 14 | 1 1 1.00 60.00 120.00 15 | 1200 3525 1200 825 16 | 2 1 0 1 0 7 0 0 -1 0.000 0 0 7 0 0 3 17 | 1125 1200 3750 1200 3750 3450 18 | 2 1 0 1 0 7 0 0 -1 0.000 0 0 -1 0 0 3 19 | 1125 2400 2475 2400 2475 3450 20 | 2 2 0 1 0 0 0 0 20 0.000 0 0 7 0 0 5 21 | 2475 2400 2550 2400 2550 2325 2475 2325 2475 2400 22 | 4 0 0 0 0 0 12 0.0000 4 135 525 2325 1500 Screen\001 23 | 4 0 0 0 0 0 12 0.0000 4 180 990 2175 2250 point at (x,y)\001 24 | 4 0 0 0 0 0 12 0.0000 4 90 90 2400 3600 x\001 25 | 4 0 0 0 0 0 12 0.0000 4 135 90 975 2475 y\001 26 | 4 0 0 0 0 0 12 0.0000 4 180 450 1050 750 y axis\001 27 | 4 0 0 0 0 14 12 0.0000 4 180 840 225 1200 size_y()\001 28 | 4 0 0 0 0 14 12 0.0000 4 165 840 3375 3600 size_x()\001 29 | 4 0 0 0 0 0 12 0.0000 4 135 450 4650 3375 x axis\001 30 | -------------------------------------------------------------------------------- /styles/syntaxdeftxt.sty: -------------------------------------------------------------------------------- 1 | \newif\ifspace 2 | \def\addspace{\ifspace\ \spacefalse\fi} 3 | \def\token#1{\addspace\hbox{\tt #1}\spacetrue\ignorespaces} 4 | %%% \def\nonterm#1{\addspace\hbox{\tt <#1>}\spacetrue\ignorespaces} 5 | \def\nonterm#1{\addspace\hbox{\it #1}\spacetrue\ignorespaces} 6 | \def\brepet{\addspace\hbox to1em{$\{$\hfil}\ignorespaces} 7 | \def\erepet{\hbox to1em{$\}$\hfil}\ignorespaces} 8 | \def\boption{\addspace[\ignorespaces} 9 | \def\eoption{]\ignorespaces} 10 | \def\brepets{\brepet\ignorespaces} 11 | \def\erepets{\erepet+\ignorespaces} 12 | \def\bparen{\addspace(\ignorespaces} 13 | \def\eparen{)\ignorespaces} 14 | \def\orelse{~\hbox to1em{$|$\hfil}~\spacefalse\ignorespaces} 15 | \def\is{& ::= & \spacefalse\ignorespaces} 16 | \def\alt{\\ & \hbox to1em{$|$\hfil} & \spacefalse } 17 | \def\sep{\\[\baselineskip] \spacefalse} 18 | \def\emptystring{nothing} 19 | \def\syntax{\begin{center}\begin{tabular}{rrl}\spacefalse\ignorespaces} 20 | \def\endsyntax{\end{tabular}\end{center}} 21 | \def\ldots{\spacefalse...\ignorespaces} 22 | \def\synt#1{$\spacefalse#1$} 23 | -------------------------------------------------------------------------------- /manual/library/libstr.etex: -------------------------------------------------------------------------------- 1 | \chapter{The str library: regular expressions and string processing} 2 | %HEVEA\cutname{libstr.html} 3 | 4 | The "str" library provides high-level string processing functions, 5 | some based on regular expressions. It is intended to support the kind 6 | of file processing that is usually performed with scripting languages 7 | such as "awk", "perl" or "sed". 8 | 9 | Programs that use the "str" library must be linked as follows: 10 | \begin{alltt} 11 | ocamlc \var{other options} str.cma \var{other files} 12 | ocamlopt \var{other options} str.cmxa \var{other files} 13 | \end{alltt} 14 | For interactive use of the "str" library, do: 15 | \begin{alltt} 16 | ocamlmktop -o mytop str.cma 17 | ./mytop 18 | \end{alltt} 19 | or (if dynamic linking of C libraries is supported on your platform), 20 | start "ocaml" and type "#load \"str.cma\";;". 21 | 22 | \ifouthtml 23 | \begin{links} 24 | \item \ahref{libref/Str.html}{Module \texttt{Str}: regular expressions and string processing} 25 | \end{links} 26 | 27 | \else 28 | \input{Str.tex} 29 | \fi 30 | 31 | 32 | -------------------------------------------------------------------------------- /manual/refman/const.etex: -------------------------------------------------------------------------------- 1 | \section{Constants} 2 | %HEVEA\cutname{const.html} 3 | 4 | \ikwd{false\@\texttt{false}} 5 | \ikwd{true\@\texttt{true}} 6 | \ikwd{begin\@\texttt{begin}} 7 | \ikwd{end\@\texttt{end}} 8 | 9 | \begin{syntax} 10 | constant: 11 | integer-literal 12 | | int32-literal 13 | | int64-literal 14 | | nativeint-literal 15 | | float-literal 16 | | char-literal 17 | | string-literal 18 | | constr 19 | | "false" 20 | | "true" 21 | | "("")" 22 | | "begin" "end" 23 | | "[""]" 24 | | "[|""|]" 25 | | "`"tag-name 26 | \end{syntax} 27 | See also the following language extension: 28 | \hyperref[s:extension-literals]{extension literals}. 29 | 30 | The syntactic class of constants comprises literals from the four 31 | base types (integers, floating-point numbers, characters, character 32 | strings), the integer variants, and constant constructors 33 | from both normal and polymorphic variants, as well as the special 34 | constants @"false"@, @"true"@, @"("")"@, 35 | @"[""]"@, and @"[|""|]"@, which behave like constant constructors, and 36 | @"begin" "end"@, which is equivalent to @'('')'@. 37 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | all: ocaml tools manual tests 2 | 3 | ocaml: 4 | cd ocaml && test -s ocamlc || ( ./configure && $(MAKE) world.opt ) 5 | 6 | # The tools and the tests are rebuilt each time in order to avoid issues with 7 | # different compiler versions 8 | tests: manual 9 | $(MAKE) -C tests clean 10 | $(MAKE) -C tests all 11 | 12 | tools: 13 | $(MAKE) -C tools clean 14 | $(MAKE) -C tools all 15 | $(MAKE) -C tests tools 16 | 17 | manual: tools 18 | $(MAKE) -C manual all 19 | 20 | html: tools 21 | $(MAKE) -C manual html 22 | 23 | .PHONY: release 24 | release: 25 | $(MAKE) -C manual release 26 | 27 | # The pregen-etex target generates the latex files from the .etex 28 | # files to ensure that this phase of the manual build process, which 29 | # may execute OCaml fragments and expect certain outputs, is correct 30 | pregen-etex: tools 31 | $(MAKE) -C manual etex-files 32 | 33 | # pregen builds both .etex files and the documentation of the standard library 34 | pregen: tools 35 | $(MAKE) -C manual files 36 | 37 | 38 | .PHONY: ocaml tests manual tools 39 | 40 | 41 | .PHONY: clean 42 | clean: 43 | $(MAKE) -C manual clean 44 | $(MAKE) -C tools clean 45 | $(MAKE) -C tests clean 46 | -------------------------------------------------------------------------------- /manual/manual.tex: -------------------------------------------------------------------------------- 1 | \documentclass[11pt]{book} 2 | % use ctex 3 | \usepackage[UTF8,heading=true]{ctex} 4 | % change section title formating 5 | \ctexset{ 6 | section/format = \Large\bfseries\raggedright 7 | } 8 | \usepackage{ae} 9 | \usepackage[utf8]{inputenc} 10 | \usepackage[T1]{fontenc} 11 | % HEVEA\@def@charset{UTF-8}% 12 | \usepackage{alltt} 13 | \usepackage{fullpage} 14 | \usepackage{syntaxdef} 15 | \usepackage{multind} 16 | \usepackage{html} 17 | \usepackage{textcomp} 18 | \usepackage{caml-sl} 19 | \usepackage{ocamldoc} 20 | \usepackage{xspace} 21 | 22 | \input{macros.tex} 23 | 24 | % Add meta tag to the generated head tag 25 | \ifouthtml 26 | \let\oldmeta=\@meta 27 | \renewcommand{\@meta}{ 28 | \oldmeta 29 | \begin{rawhtml} 30 | 31 | \end{rawhtml} 32 | } 33 | \fi 34 | 35 | \usepackage[colorlinks,linkcolor=blue]{hyperref} 36 | %\makeatletter \def\@wrindex#1#2{\xdef \@indexfile{\csname #1@idxfile\endcsname}\@@wrindex#2||\\}\makeatother 37 | \def\th{^{\hbox{\scriptsize th}}} 38 | 39 | \raggedbottom 40 | \input{version.tex} 41 | %HEVEA\tocnumber 42 | %HEVEA\setcounter{cuttingdepth}{1} 43 | %HEVEA\title{OCaml 系统，版本 \ocamlversion} 44 | \input{allfiles.tex} 45 | 46 | 47 | -------------------------------------------------------------------------------- /manual/library/libdynlink.etex: -------------------------------------------------------------------------------- 1 | \chapter{The dynlink library: dynamic loading and linking of object files} 2 | %HEVEA\cutname{libdynlink.html} 3 | 4 | The "dynlink" library supports type-safe dynamic loading and linking 5 | of bytecode object files (".cmo" and ".cma" files) in a running 6 | bytecode program, or of native plugins (usually ".cmxs" files) in a 7 | running native program. Type safety is ensured by limiting the set of 8 | modules from the running program that the loaded object file can 9 | access, and checking that the running program and the loaded object 10 | file have been compiled against the same interfaces for these modules. 11 | In native code, there are also some compatibility checks on the 12 | implementations (to avoid errors with cross-module optimizations); it 13 | might be useful to hide ".cmx" files when building native plugins so 14 | that they remain independent of the implementation of modules in the 15 | main program. 16 | 17 | Programs that use the "dynlink" library simply need to link 18 | "dynlink.cma" or "dynlink.cmxa" with their object files and other libraries. 19 | 20 | \ifouthtml 21 | \begin{links} 22 | \item \ahref{libref/Dynlink.html}{Module \texttt{Dynlink}: dynamic loading of bytecode object files} 23 | \end{links} 24 | 25 | \else 26 | \input{Dynlink.tex} 27 | \fi 28 | 29 | -------------------------------------------------------------------------------- /manual/library/libbigarray.etex: -------------------------------------------------------------------------------- 1 | \chapter{The bigarray library} 2 | %HEVEA\cutname{libbigarray.html} 3 | 4 | The "bigarray" library has now been integrated into OCaml's standard 5 | library. 6 | 7 | The "bigarray" functionality may now be found in the standard library 8 | \ifouthtml 9 | \ahref{libref/Bigarray.html}{\texttt{Bigarray} module}, 10 | \else 11 | \texttt{Bigarray} module, 12 | \fi 13 | except for the "map_file" function which is now 14 | part of the \hyperref[c:unix]{Unix library}. The documentation has 15 | been integrated into the documentation for the standard library. 16 | 17 | The legacy "bigarray" library bundled with the compiler is a 18 | compatibility library with exactly the same interface as before, 19 | i.e. with "map_file" included. 20 | 21 | We strongly recommend that you port your code to use the standard 22 | library version instead, as the changes required are minimal. 23 | 24 | If you choose to use the compatibility library, you must link your 25 | programs as follows: 26 | \begin{alltt} 27 | ocamlc \var{other options} bigarray.cma \var{other files} 28 | ocamlopt \var{other options} bigarray.cmxa \var{other files} 29 | \end{alltt} 30 | For interactive use of the "bigarray" compatibility library, do: 31 | \begin{alltt} 32 | ocamlmktop -o mytop bigarray.cma 33 | ./mytop 34 | \end{alltt} 35 | or (if dynamic linking of C libraries is supported on your platform), 36 | start "ocaml" and type "#load \"bigarray.cma\";;". 37 | -------------------------------------------------------------------------------- /manual/library/core.etex: -------------------------------------------------------------------------------- 1 | \chapter{The core library} \label{c:corelib}\cutname{core.html} 2 | 3 | This chapter describes the OCaml core library, which is 4 | composed of declarations for built-in types and exceptions, plus 5 | the module "Pervasives" that provides basic operations on these 6 | built-in types. The "Pervasives" module is special in two 7 | ways: 8 | \begin{itemize} 9 | \item It is automatically linked with the user's object code files by 10 | the "ocamlc" command (chapter~\ref{c:camlc}). 11 | 12 | \item It is automatically ``opened'' when a compilation starts, or 13 | when the toplevel system is launched. Hence, it is possible to use 14 | unqualified identifiers to refer to the functions provided by the 15 | "Pervasives" module, without adding a "open Pervasives" directive. 16 | \end{itemize} 17 | 18 | \section*{Conventions} 19 | 20 | The declarations of the built-in types and the components of module 21 | "Pervasives" are printed one by one in typewriter font, followed by a 22 | short comment. All library modules and the components they provide are 23 | indexed at the end of this report. 24 | 25 | \input{builtin.tex} 26 | 27 | \ifouthtml 28 | \section{Module {\tt Stdlib}: the initially opened module} 29 | \begin{links} 30 | \item \ahref{libref/Stdlib.html}{Module \texttt{Stdlib}: the initially opened module} 31 | \item \ahref{libref/Pervasives.html}{Module \texttt{Pervasives}: deprecated alias for Stdlib} 32 | \end{links} 33 | \else 34 | \input{Stdlib.tex} 35 | \fi 36 | 37 | -------------------------------------------------------------------------------- /manual/cmds/Makefile: -------------------------------------------------------------------------------- 1 | TOPDIR = ../../ocaml 2 | include $(TOPDIR)/Makefile.tools 3 | 4 | LD_PATH = "$(TOPDIR)/otherlibs/str:$(TOPDIR)/otherlibs/unix" 5 | 6 | TOOLS = ../../tools 7 | CAMLLATEX = $(SET_LD_PATH) \ 8 | $(OCAMLRUN) $(TOPDIR)/tools/caml-tex \ 9 | -repo-root $(TOPDIR) -n 80 -v false 10 | TEXQUOTE = $(OCAMLRUN) $(TOOLS)/texquote2 11 | TRANSF = $(SET_LD_PATH) $(OCAMLRUN) $(TOOLS)/transf 12 | 13 | FILES = comp.tex top.tex runtime.tex native.tex lexyacc.tex intf-c.tex \ 14 | depend.tex profil.tex debugger.tex browser.tex ocamldoc.tex \ 15 | warnings-help.tex ocamlbuild.tex flambda.tex spacetime.tex \ 16 | afl-fuzz.tex plugins.tex unified-options.tex 17 | 18 | WITH_TRANSF = top.tex intf-c.tex flambda.tex spacetime.tex \ 19 | afl-fuzz.tex lexyacc.tex debugger.tex 20 | 21 | WITH_CAMLEXAMPLE = ocamldoc.tex 22 | 23 | 24 | etex-files: $(FILES) 25 | all: $(FILES) 26 | 27 | 28 | %.tex: %.etex 29 | $(TEXQUOTE) < $< > $*.texquote_error.tex 30 | mv $*.texquote_error.tex $@ 31 | 32 | $(WITH_TRANSF): %.tex: %.etex 33 | $(TRANSF) < $< > $*.transf_error.tex 34 | mv $*.transf_error.tex $*.transf_gen.tex 35 | $(TEXQUOTE) < $*.transf_gen.tex > $*.texquote_error.tex 36 | mv $*.texquote_error.tex $@ 37 | 38 | $(WITH_CAMLEXAMPLE): %.tex: %.etex 39 | $(CAMLLATEX) $< -o $*.gen.tex 40 | $(TRANSF) < $*.gen.tex > $*.transf_error.tex 41 | mv $*.transf_error.tex $*.transf_gen.tex 42 | $(TEXQUOTE) < $*.transf_gen.tex > $*.texquote_error.tex 43 | mv $*.texquote_error.tex $@ 44 | 45 | warnings-help.etex: ../warnings-help.etex 46 | cp $< $@ 47 | 48 | 49 | .PHONY: clean 50 | clean: 51 | rm -f *.tex 52 | rm -f warnings-help.etex 53 | -------------------------------------------------------------------------------- /styles/altindex.sty: -------------------------------------------------------------------------------- 1 | %% An attempt to have several index files 2 | %% 3 | %% Defines \altindex{filename}{word to index} 4 | %% and \makealtindex{filename} 5 | %% 6 | %% It is possible to define a macro for each index as follows: 7 | %% \newcommand{\myindex}{\altindex{myindexfile}} 8 | %% 9 | %% This code is not really clean, there are still a number of things 10 | %% that I don't understand... but it works. 11 | 12 | %% \makealtindex{filename} opens filename.idx for writing. 13 | 14 | \def\makealtindex#1{\if@filesw 15 | \expandafter\newwrite\csname @#1altindexfile\endcsname 16 | \immediate\openout\expandafter\csname @#1altindexfile\endcsname=#1.idx 17 | \typeout{Writing alternate index file #1.idx}\fi} 18 | 19 | %% \@wraltindex makes the assumes that a trailing `\fi' will get bound 20 | %% to #2. So, it `eats' it as second parameter and reinserts it. 21 | %% Quick and dirty, I know... 22 | %% Writes the index entry #3 into #1. 23 | 24 | \def\@wraltindex#1#2#3{\let\thepage\relax 25 | \xdef\@gtempa{\write#1{\string 26 | \indexentry{#3}{\thepage}}}\fi\endgroup\@gtempa 27 | \if@nobreak \ifvmode\nobreak\fi\fi\@esphack} 28 | 29 | %% \altindex{filename}{index entry} does nothing if 30 | %% \@altindexfile is \relax (i.e. filename.idx not open). 31 | %% Otherwise, writes the index entry, and closes the whole stuff (some 32 | %% groups, and some \if). 33 | 34 | \def\altindex#1{\@bsphack\begingroup 35 | \def\protect##1{\string##1\space}\@sanitize 36 | \@ifundefined{@#1altindexfile}% 37 | {\endgroup\@esphack}% 38 | {\@wraltindex{\expandafter\csname @#1altindexfile\endcsname}} 39 | } 40 | -------------------------------------------------------------------------------- /manual/refman/refman.etex: -------------------------------------------------------------------------------- 1 | \chapter{The OCaml language} \label{c:refman} 2 | %HEVEA\cutname{language.html} 3 | 4 | %better html output that way, sniff. 5 | %HEVEA\subsection*{Foreword} 6 | %BEGIN LATEX 7 | \section*{Foreword} 8 | %END LATEX 9 | 10 | This document is intended as a reference manual for the OCaml 11 | language. It lists the language constructs, and gives their precise 12 | syntax and informal semantics. It is by no means a tutorial 13 | introduction to the language: there is not a single example. A good 14 | working knowledge of OCaml is assumed. 15 | 16 | No attempt has been made at mathematical rigor: words are employed 17 | with their intuitive meaning, without further definition. As a 18 | consequence, the typing rules have been left out, by lack of the 19 | mathematical framework required to express them, while they are 20 | definitely part of a full formal definition of the language. 21 | 22 | 23 | \subsection*{Notations} 24 | 25 | The syntax of the language is given in BNF-like notation. Terminal 26 | symbols are set in typewriter font (@'like' 'this'@). 27 | Non-terminal symbols are set in italic font (@like that@). 28 | Square brackets @[\ldots]@ denote optional components. Curly brackets 29 | @{\ldots}@ denotes zero, one or several repetitions of the enclosed 30 | components. Curly brackets with a trailing plus sign @{{\ldots}}@ 31 | denote one or several repetitions of the enclosed components. 32 | Parentheses @(\ldots)@ denote grouping. 33 | 34 | %HEVEA\cutdef{section} 35 | \input{lex} 36 | \input{values} 37 | \input{names} 38 | \input{types} 39 | \input{const} 40 | \input{patterns} 41 | \input{expr} 42 | \input{typedecl} 43 | \input{classes} 44 | \input{modtypes} 45 | \input{modules} 46 | \input{compunit} 47 | %HEVEA\cutend 48 | -------------------------------------------------------------------------------- /tools/fix_index.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # usage: fix_index.sh .idx 4 | 5 | # This script works around a hyperref bug: hyperref does not handle 6 | # quotes in \index arguments properly. 7 | # 8 | # Symptom: 9 | # When \index{-pipe-pipe@\verb`("|"|)`} appears in your .tex, the hyperref 10 | # package mangles it and produces this line in your .idx: 11 | # \indexentry{(-pipe-pipe)@\verb`("|hyperindexformat{\"}}{292} 12 | # instead of the expected: 13 | # \indexentry{(-pipe-pipe)@\verb`("|"|)`|hyperpage}{292} 14 | # 15 | # This is because it fails to handle quoted characters correctly. 16 | # 17 | # The workaround: 18 | # Look for the buggy line in the given .idx file and change it. 19 | 20 | # Note: this bug will happen every time you have a | (pipe) character 21 | # in an index entry (properly quoted with a " (double-quote) before it). 22 | # We fix only the one case that appears in the OCaml documentation. 23 | # We do not attempt a general solution because hyperref erases part 24 | # of the argument, so we cannot recover the correct string from its 25 | # output. 26 | 27 | # Note 2013-06-19: 28 | # The above was for the || operator in the stdlib's Pervasives module. 29 | # Now we have the same problem with the |> operator that was added 30 | # to the same module in commit 13739, hence the second special case. 31 | 32 | usage(){ 33 | echo "usage: fix_index.sh .idx" >&2 34 | exit 2 35 | } 36 | 37 | case $# in 38 | 1) ;; 39 | *) usage;; 40 | esac 41 | 42 | sed < "$1" > "$1.new" \ 43 | -e 's/verb`("|hyperindexformat{\\"}/verb`("|"|)`|hyperpage/' \ 44 | -e 's/verb`("|hyperindexformat{\\>)`}/verb`("|>)`|hyperpage/' 45 | 46 | case $? in 47 | 0) echo "fix_index.sh: fixed $1 successfully.";; 48 | *) echo "fix_index.sh: some error occurred."; exit 1;; 49 | esac 50 | 51 | mv "$1.new" "$1" 52 | -------------------------------------------------------------------------------- /manual/foreword.etex: -------------------------------------------------------------------------------- 1 | \chapter*{前言} 2 | \markboth{前言}{} 3 | %HEVEA\cutname{foreword.html} 4 | 5 | 该手册记录了 OCaml \ocamlversion\ 版本的相关信息。其结构组织如下： 6 | 7 | \begin{itemize} 8 | \item 第\ref{p:tutorials}部分，“OCaml 简介”将提供该语言的简要介绍。 9 | \item 第\ref{p:refman}部分，“OCaml 语言”，给出该语言的使用参考说明。 10 | \item 第\ref{p:commands}部分，“OCaml 工具”，记录了编译器、顶层系统和编程工具的相关信息。 11 | \item 第\ref{p:library}部分，“OCaml 库”，描述了标准库所提供的模块。 12 | \begin{latexonly} 13 | \item 第\ref{p:appendix}部分，“附录”，包含了标准库中所有标示符的索引和关键词的索引。 14 | \end{latexonly} 15 | \end{itemize} 16 | 17 | \section*{约定} 18 | 19 | OCaml 可以在若干操作系统上运行。因此该手册上的部分内容将只针对如下的某一特定操作系统： 20 | 21 | \begin{unix} 这部分材料仅针对 Unix 族的操作系统，如 Linux 和~\hbox{MacOS~X}。 22 | \end{unix} 23 | 24 | \begin{windows} 这部分材料仅针对 Microsoft Windows 操作系统，如 XP、Vista、7、8、10。 25 | \end{windows} 26 | 27 | \section*{协议} 28 | 29 | OCaml 系统的版权归属为 copyright \copyright\ 1996--\number\year\ 30 | 法国国家信息与自动化研究所（Institut National de Recherche en Informatique et en Automatique，简称 INRIA）。INRIA 拥有 OCaml 系统的所有权。 31 | 32 | OCaml 系统是开源的，可以被自由的重新分发。请查看发行版中的“LICENSE”文件获取有关的许可协议信息。 33 | 34 | 本文档的版权归属于 copyright \copyright\ \number\year\ 35 | 法国国家信息与自动化研究所。OCaml 文档和用户手册在满足如下条件时可以被全部或部分复制与分发： 36 | \begin{itemize} 37 | \item 以上的版权声明与此许可声明必须被完整地保留在所有完整或部分副本中。 38 | \item 任何 OCaml 文档和用户手册的翻译或衍生作品在发行必须得到原作者的书面批准。 39 | \item 如果您部分分发 OCaml 文档和用户手册，则必须包括获取本手册完整版本的说明，并提供获取完整版本手册的方法。 40 | \item 若给出合适的引用，可以在不包含此声明许可的情况下，将手册的一小部分内容作为其他作品中的评论或引用示例使用。 41 | \end{itemize} 42 | 43 | \section*{可用性} 44 | 45 | \begin{latexonly} 46 | 完整的 OCaml 发行版可以在~\url{http://www.ocaml.org/} 和~\url{http://caml.inria.fr/} 获得。 47 | 第一个网站包括大量关于 OCaml 的额外信息。 48 | \end{latexonly} 49 | 50 | \begin{htmlonly} 51 | 完整的OCaml发行版可以在 52 | \href{http://www.ocaml.org/}{Caml 社区网站}和 53 | \href{http://caml.inria.fr/}{旧版的 Caml 网站}上获得。\href{http://www.ocaml.org/}{Caml 社区网站}上包括大量关于 OCaml 的额外信息。 54 | \end{htmlonly} 55 | -------------------------------------------------------------------------------- /styles/caml-sl.sty: -------------------------------------------------------------------------------- 1 | % CAML style option, for use with the caml-latex filter. 2 | 3 | \typeout{Document Style option `caml-sl' <7 Apr 92>.} 4 | \newcommand{\hash}{\#} 5 | {\catcode`\^^M=\active % 6 | \gdef\@camlinputline#1^^M{\normalsize\tt\hash{} #1\par} % 7 | \gdef\@camloutputline#1^^M{\small\ttfamily\slshape#1\par} } % 8 | \def\@camlblankline{\medskip} 9 | \chardef\@camlbackslash="5C 10 | \def\@bunderline{\setbox0\hbox\bgroup\let\par\@parinunderline} 11 | 12 | \def \@parinunderline {\futurelet \@next \@@parinunderline} 13 | \def \@@parinunderline {\ifx \@next \? \let \@do \@@par@inunderline \else \let \@do \@@@parinunderline \fi \@do} 14 | \def \@@par@inunderline #1{\@eunderline\@oldpar\?\@bunderline} 15 | \def \@@@parinunderline {\@eunderline\@oldpar\@bunderline} 16 | \def\@eunderline{\egroup\underline{\box0}} 17 | \def\@camlnoop{} 18 | 19 | \def\caml{ 20 | \bgroup 21 | \parindent 0pt 22 | \parskip 0pt 23 | \let\do\@makeother\dospecials 24 | \catcode13=\active % 13 = ^M = CR 25 | \catcode92=0 % 92 = \ 26 | \catcode32=\active % 32 = SPC 27 | \frenchspacing 28 | \@vobeyspaces 29 | \let\@oldpar\par 30 | \let\?\@camlinputline 31 | \let\:\@camloutputline 32 | \let\;\@camlblankline 33 | \let\<\@bunderline 34 | \let\>\@eunderline 35 | \let\\\@camlbackslash 36 | \let\-\@camlnoop 37 | } 38 | 39 | \def\endcaml{ 40 | \egroup 41 | \addvspace{\medskipamount} 42 | } 43 | 44 | % Caml-example related command 45 | \def\camlexample#1{ 46 | \ifnum\pdfstrcmp{#1}{toplevel}=0 47 | \renewcommand{\hash}{\#} 48 | \else 49 | \renewcommand{\hash}{} 50 | \fi 51 | \begin{flushleft} 52 | } 53 | \def\endcamlexample{\end{flushleft}\renewcommand{\hash}{\#}} 54 | \def\camlinput{} 55 | \def\endcamlinput{} 56 | \def\camloutput{} 57 | \def\endcamloutput{} 58 | \def\camlerror{} 59 | \def\endcamlerror{} 60 | \def\camlwarn{} 61 | \def\endcamlwarn{} 62 | -------------------------------------------------------------------------------- /manual/refman/compunit.etex: -------------------------------------------------------------------------------- 1 | \section{Compilation units} 2 | %HEVEA\cutname{compunit.html} 3 | 4 | \begin{syntax} 5 | unit-interface: { specification [';;'] } 6 | ; 7 | unit-implementation: [ module-items ] 8 | \end{syntax} 9 | 10 | Compilation units bridge the module system and the separate 11 | compilation system. A compilation unit is composed of two parts: an 12 | interface and an implementation. The interface contains a sequence of 13 | specifications, just as the inside of a @'sig' \ldots 'end'@ 14 | signature expression. The implementation contains a sequence of 15 | definitions and expressions, just as the inside of a 16 | @'struct' \ldots 'end'@ module 17 | expression. A compilation unit also has a name @unit-name@, derived 18 | from the names of the files containing the interface and the 19 | implementation (see chapter~\ref{c:camlc} for more details). A 20 | compilation unit behaves roughly as the module definition 21 | \begin{center} 22 | @'module' unit-name ':' 'sig' unit-interface 'end' '=' 23 | 'struct' unit-implementation 'end'@ 24 | \end{center} 25 | 26 | A compilation unit can refer to other compilation units by their 27 | names, as if they were regular modules. For instance, if "U" is a 28 | compilation unit that defines a type "t", other compilation units can 29 | refer to that type under the name "U.t"; they can also refer to "U" as 30 | a whole structure. Except for names of other compilation units, a unit 31 | interface or unit implementation must not have any other free variables. 32 | In other terms, the type-checking and compilation of an interface or 33 | implementation proceeds in the initial environment 34 | \begin{center} 35 | @name_1 ':' 'sig' specification_1 'end' \ldots 36 | name_n ':' 'sig' specification_n 'end'@ 37 | \end{center} 38 | where @name_1 \ldots name_n@ are the names of the other 39 | compilation units available in the search path (see 40 | chapter~\ref{c:camlc} for more details) and @specification_1 \ldots 41 | specification_n@ are their respective interfaces. 42 | -------------------------------------------------------------------------------- /manual/manual.hva: -------------------------------------------------------------------------------- 1 | % \input{book.hva} 2 | % dirty hack for chinese support 3 | 4 | \renewcommand\today{\theyear~年~\themonth~月~\theday~日} 5 | \renewcommand\contentsname{目录} 6 | 7 | % dirty CJK since hevea not support loop and math operators 8 | % command like \roman is implemented by ocaml func roman_of_int 9 | % considering we only have a few parts, so that can be enough 10 | \newcommand{\CJK}[1] 11 | {\ifthenelse{\equal{#1}{\string I}}{一} 12 | {\ifthenelse{\equal{#1}{\string II}}{二} 13 | {\ifthenelse{\equal{#1}{\string III}}{三} 14 | {\ifthenelse{\equal{#1}{\string IV}}{四} 15 | {\ifthenelse{\equal{#1}{\string V}}{五} 16 | {\ifthenelse{\equal{#1}{\string VI}}{六} 17 | {\ifthenelse{\equal{#1}{\string VII}}{七} 18 | {\ifthenelse{\equal{#1}{\string VIII}}{八} 19 | {\ifthenelse{\equal{#1}{\string IX}}{九} 20 | {十}}}}}}}}}} 21 | 22 | \ifstyleloaded\relax 23 | \else 24 | \input{bookcommon.hva} 25 | \renewcommand \thepart {\CJK{\Roman{part}}} 26 | \newcommand{\@book@attr}[1]{\@secid\envclass@attr{#1}} 27 | \@makesection 28 | {\part}{-2}{part} 29 | {\@opencell{class="center"}{}{}\@open{h1}{\@book@attr{part}}}% 30 | {第\thepart部分}{\\}% 31 | {\@close{h1}\@closecell} 32 | \newstyle{.part}{margin:2ex auto;text-align:center} 33 | \@makesection 34 | {\chapter}{-1}{chapter} 35 | {\@open{h1}{\@book@attr{chapter}}}{第~\thechapter~章}{\quad}{\@close{h1}} 36 | \@makesection 37 | {\section}{0}{section} 38 | {\@open{h2}{\@book@attr{section}}}{\thesection}{\quad}{\@close{h2}}% 39 | \@makesection 40 | {\subsection}{1}{subsection} 41 | {\@open{h3}{\@book@attr{subsection}}}{\thesubsection}{\quad}{\@close{h3}}% 42 | \@makesection 43 | {\subsubsection}{2}{subsubsection} 44 | {\@open{h4}{\@book@attr{subsubsection}}}{\thesubsubsection}{\quad}{\@close{h4}}% 45 | \@makesection 46 | {\paragraph}{3}{paragraph} 47 | {\@open{h5}{\@book@attr{paragraph}}}{\theparagraph}{\quad}{\@close{h5}}% 48 | \@makesection 49 | {\subparagraph}{4}{subparagraph} 50 | {\@open{h6}{\@book@attr{subparagraph}}}{\thesubparagraph}{\quad}{\@close{h6}}% 51 | \newcommand{\hacha@style}{book}% 52 | \styleloadedtrue 53 | \fi 54 | \input{macros.hva} 55 | \newif\ifouthtml\outhtmltrue 56 | -------------------------------------------------------------------------------- /manual/library/Makefile: -------------------------------------------------------------------------------- 1 | SRC = ../../ocaml 2 | 3 | CSLDIR = $(SRC) 4 | 5 | LD_PATH := "$(SRC)/otherlibs/unix/:$(SRC)/otherlibs/str/" 6 | SET_LD_PATH = CAML_LD_LIBRARY_PATH=$(LD_PATH) 7 | 8 | 9 | OCAMLDOC = $(if $(wildcard $(CSLDIR)/ocamldoc/ocamldoc.opt),\ 10 | $(CSLDIR)/ocamldoc/ocamldoc.opt,\ 11 | $(SET_LD_PATH) $(CSLDIR)/runtime/ocamlrun $(CSLDIR)/ocamldoc/ocamldoc) \ 12 | -hide Stdlib -lib Stdlib -nostdlib \ 13 | -pp "$(AWK) -v ocamldoc=true -f $(SRC)/stdlib/expand_module_aliases.awk" 14 | 15 | 16 | #Import mli file lists 17 | include $(SRC)/ocamldoc/Makefile.docfiles 18 | 19 | 20 | TEXQUOTE = $(SRC)/runtime/ocamlrun ../../tools/texquote2 21 | 22 | CORE_INTF = Stdlib.tex 23 | 24 | STDLIB_INTF = $(STDLIB_MODs:%=%.tex) 25 | 26 | COMPILER_LIBS_PLUGIN_HOOKS = Pparse.tex Typemod.tex 27 | 28 | COMPILER_LIBS_INTF = Asthelper.tex Astmapper.tex Asttypes.tex \ 29 | Lexer.tex Location.tex Longident.tex Parse.tex Pprintast.tex Printast.tex \ 30 | $(COMPILER_LIBS_PLUGIN_HOOKS) 31 | 32 | OTHERLIB_INTF = Unix.tex UnixLabels.tex Str.tex \ 33 | Graphics.tex GraphicsX11.tex \ 34 | Thread.tex Mutex.tex Condition.tex Event.tex ThreadUnix.tex \ 35 | Dynlink.tex Bigarray.tex 36 | 37 | INTF = $(CORE_INTF) $(STDLIB_INTF) $(COMPILER_LIBS_INTF) $(OTHERLIB_INTF) 38 | 39 | BLURB = core.tex builtin.tex stdlib.tex compilerlibs.tex \ 40 | libunix.tex libstr.tex libnum.tex libgraph.tex \ 41 | libthreads.tex libdynlink.tex libbigarray.tex 42 | 43 | FILES = $(BLURB) $(INTF) 44 | 45 | 46 | etex-files: $(BLURB) 47 | all: libs 48 | 49 | libs: $(FILES) 50 | 51 | 52 | # ocamldoc.out is used as witness for the generation of the stdlib tex files to 53 | # avoid issues with parallel make invocations. 54 | $(INTF): ocamldoc.out 55 | ocamldoc.out: $(DOC_ALL_MLIS) 56 | $(OCAMLDOC) -latex \ 57 | $(DOC_ALL_INCLUDES) \ 58 | $(DOC_ALL_MLIS) \ 59 | -sepfiles \ 60 | -latextitle "1,subsection*" \ 61 | -latextitle "2,subsubsection*" \ 62 | -latex-type-prefix "TYP" \ 63 | -latex-module-prefix "" \ 64 | -latex-module-type-prefix "" \ 65 | -latex-value-prefix "" 66 | mv Ast_helper.tex Asthelper.tex 67 | mv Ast_mapper.tex Astmapper.tex 68 | 69 | %.tex: %.etex 70 | $(TEXQUOTE) < $< > $*.texquote_error.tex 71 | mv $*.texquote_error.tex $@ 72 | 73 | 74 | .PHONY: clean 75 | clean: 76 | rm -f *.tex ocamldoc.out ocamldoc.sty 77 | rm -f compiler_libs.txt 78 | -------------------------------------------------------------------------------- /styles/ocamldoc.sty: -------------------------------------------------------------------------------- 1 | 2 | %% Support macros for LaTeX documentation generated by ocamldoc. 3 | %% This file is in the public domain; do what you want with it. 4 | 5 | \NeedsTeXFormat{LaTeX2e} 6 | \ProvidesPackage{ocamldoc} 7 | [2001/12/04 v1.0 ocamldoc support] 8 | 9 | \newenvironment{ocamldoccode}{% 10 | \bgroup 11 | \leftskip\@totalleftmargin 12 | \rightskip\z@skip 13 | \parindent\z@ 14 | \parfillskip\@flushglue 15 | \parskip\z@skip 16 | %\noindent 17 | \@@par\smallskip 18 | \@tempswafalse 19 | \def\par{% 20 | \if@tempswa 21 | \leavevmode\null\@@par\penalty\interlinepenalty 22 | \else 23 | \@tempswatrue 24 | \ifhmode\@@par\penalty\interlinepenalty\fi 25 | \fi} 26 | \obeylines 27 | \verbatim@font 28 | \let\org@prime~% 29 | \@noligs 30 | \let\org@dospecials\dospecials 31 | \g@remfrom@specials{\\} 32 | \g@remfrom@specials{\{} 33 | \g@remfrom@specials{\}} 34 | \let\do\@makeother 35 | \dospecials 36 | \let\dospecials\org@dospecials 37 | \frenchspacing\@vobeyspaces 38 | \everypar \expandafter{\the\everypar \unpenalty}} 39 | {\egroup\par} 40 | 41 | \def\g@remfrom@specials#1{% 42 | \def\@new@specials{} 43 | \def\@remove##1{% 44 | \ifx##1#1\else 45 | \g@addto@macro\@new@specials{\do ##1}\fi} 46 | \let\do\@remove\dospecials 47 | \let\dospecials\@new@specials 48 | } 49 | 50 | \newenvironment{ocamldocdescription} 51 | {\list{}{\rightmargin0pt \topsep0pt}\raggedright\item\noindent\relax\ignorespaces} 52 | {\endlist\medskip} 53 | 54 | \newenvironment{ocamldoccomment} 55 | {\list{}{\leftmargin 2\leftmargini \rightmargin0pt \topsep0pt}\raggedright\item\noindent\relax} 56 | {\endlist} 57 | 58 | \let \ocamldocparagraph \paragraph 59 | \def \paragraph #1{\ocamldocparagraph {#1}\noindent} 60 | \let \ocamldocsubparagraph \subparagraph 61 | \def \subparagraph #1{\ocamldocsubparagraph {#1}\noindent} 62 | 63 | \let\ocamldocvspace\vspace 64 | 65 | \newenvironment{ocamldocindent}{\list{}{}\item\relax}{\endlist} 66 | \newenvironment{ocamldocsigend} 67 | {\noindent\quad\texttt{sig}\ocamldocindent} 68 | {\endocamldocindent\vskip -\lastskip 69 | \noindent\quad\texttt{end}\medskip} 70 | \newenvironment{ocamldocobjectend} 71 | {\noindent\quad\texttt{object}\ocamldocindent} 72 | {\endocamldocindent\vskip -\lastskip 73 | \noindent\quad\texttt{end}\medskip} 74 | 75 | \endinput 76 | -------------------------------------------------------------------------------- /styles/multind.sty: -------------------------------------------------------------------------------- 1 | % indexes document style option for producing multiple indexes 2 | % for use with the modified bbok style, CHbook.sty 3 | % Written by F.W. Long, Version 1.1, 12 August 1991. 4 | 5 | % Modified by F.W. Long, Version 1.1a, 29 August 1991 6 | % to get the index heading correctly spaced. 7 | 8 | % Modified by F.W. Long, Version 1.1b, 31 August 1991 9 | % to remove the abbreviation \ix (which should be in the document, not here). 10 | 11 | % Modified \makeindex and \index commands to allow multiple indexes 12 | % in both cases the first parameter is the index name. 13 | % They now work more like \@starttoc and \addcontentsline. 14 | % \index is no longer defined inside \makeindex but determines 15 | % whether the appropriate file is defined before writing to it. 16 | 17 | \def\makeindex#1{\begingroup 18 | \makeatletter 19 | \if@filesw \expandafter\newwrite\csname #1@idxfile\endcsname 20 | \expandafter\immediate\openout \csname #1@idxfile\endcsname #1.idx\relax 21 | \typeout{Writing index file #1.idx }\fi \endgroup} 22 | 23 | \def\index#1{\@bsphack\begingroup 24 | \def\protect##1{\string##1\space}\@sanitize 25 | \@wrindex{#1}} 26 | 27 | % \@wrindex now checks that the appropriate file is defined. 28 | 29 | \def\@wrindex#1#2{\let\thepage\relax 30 | \xdef\@gtempa{\@ifundefined{#1@idxfile}{}{\expandafter 31 | \write\csname #1@idxfile\endcsname{\string 32 | \indexentry{#2}{\thepage}}}}\endgroup\@gtempa 33 | \if@nobreak \ifvmode\nobreak\fi\fi\@esphack} 34 | 35 | % Modified \printindex command to allow multiple indexes. 36 | % This now takes over much of the work of \theindex. 37 | % Again, the first parameter is the index name. 38 | % The second parameter is the index title (as printed). 39 | 40 | \newif\if@restonecol 41 | \def\printindex#1#2{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi 42 | \columnseprule \z@ \columnsep 35pt 43 | \newpage \twocolumn[{\Large\bf #2 \vskip4ex}] 44 | \markright{\uppercase{#2}} 45 | \addcontentsline{toc}{section}{#2} 46 | \@input{#1.ind}} 47 | 48 | % The following index commands are taken from book.sty. 49 | % \theindex is modified to not start a chapter. 50 | 51 | \def\theindex{\parindent\z@ 52 | \parskip\z@ plus .3pt\relax\let\item\@idxitem} 53 | \def\@idxitem{\par\hangindent 40pt} 54 | \def\subitem{\par\hangindent 40pt \hspace*{20pt}} 55 | \def\subsubitem{\par\hangindent 40pt \hspace*{30pt}} 56 | \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi} 57 | \def\indexspace{\par \vskip 10pt plus 5pt minus 3pt\relax} 58 | 59 | % the command \ix allows an abbreviation for the general index 60 | 61 | %\def\ix#1{#1\index{general}{#1}} 62 | 63 | % define the \see command from makeidx.sty 64 | 65 | \def\see#1#2{{\em see\/} #1} 66 | -------------------------------------------------------------------------------- /manual/cmds/afl-fuzz.etex: -------------------------------------------------------------------------------- 1 | \chapter{Fuzzing with afl-fuzz} 2 | %HEVEA\cutname{afl-fuzz.html} 3 | 4 | \section{Overview} 5 | 6 | American fuzzy lop (``afl-fuzz'') is a {\em fuzzer}, a tool for 7 | testing software by providing randomly-generated inputs, searching for 8 | those inputs which cause the program to crash. 9 | 10 | Unlike most fuzzers, afl-fuzz observes the internal behaviour of the 11 | program being tested, and adjusts the test cases it generates to 12 | trigger unexplored execution paths. As a result, test cases generated 13 | by afl-fuzz cover more of the possible behaviours of the tested 14 | program than other fuzzers. 15 | 16 | This requires that programs to be tested are instrumented to 17 | communicate with afl-fuzz. The native-code compiler ``ocamlopt'' can 18 | generate such instrumentation, allowing afl-fuzz to be used against 19 | programs written in OCaml. 20 | 21 | For more information on afl-fuzz, see the website at 22 | \ifouthtml 23 | \ahref{http://lcamtuf.coredump.cx/afl/}{http://lcamtuf.coredump.cx/afl/}. 24 | \else 25 | {\tt http://lcamtuf.coredump.cx/afl/} 26 | \fi 27 | 28 | \section{Generating instrumentation} 29 | 30 | The instrumentation that afl-fuzz requires is not generated by 31 | default, and must be explicitly enabled, by passing the {\tt 32 | -afl-instrument} option to {\tt ocamlopt}. 33 | 34 | To fuzz a large system without modifying build tools, OCaml's {\tt 35 | configure} script also accepts the {\tt afl-instrument} option. If 36 | OCaml is configured with {\tt afl-instrument}, then all programs 37 | compiled by {\tt ocamlopt} will be instrumented. 38 | 39 | \subsection{Advanced options} 40 | 41 | In rare cases, it is useful to control the amount of instrumentation 42 | generated. By passing the {\tt -afl-inst-ratio N} argument to {\tt 43 | ocamlopt} with {\tt N} less than 100, instrumentation can be 44 | generated for only N\% of branches. (See the afl-fuzz documentation on 45 | the parameter {\tt AFL\_INST\_RATIO} for the precise effect of this). 46 | 47 | \section{Example} 48 | 49 | As an example, we fuzz-test the following program, {\tt readline.ml}: 50 | 51 | \begin{verbatim} 52 | let _ = 53 | let s = read_line () in 54 | match Array.to_list (Array.init (String.length s) (String.get s)) with 55 | ['s'; 'e'; 'c'; 'r'; 'e'; 't'; ' '; 'c'; 'o'; 'd'; 'e'] -> failwith "uh oh" 56 | | _ -> () 57 | \end{verbatim} 58 | 59 | There is a single input (the string ``secret code'') which causes this 60 | program to crash, but finding it by blind random search is infeasible. 61 | 62 | Instead, we compile with afl-fuzz instrumentation enabled: 63 | \begin{verbatim} 64 | ocamlopt -afl-instrument readline.ml -o readline 65 | \end{verbatim} 66 | Next, we run the program under afl-fuzz: 67 | \begin{verbatim} 68 | mkdir input 69 | echo asdf > input/testcase 70 | mkdir output 71 | afl-fuzz -i input -o output ./readline 72 | \end{verbatim} 73 | By inspecting instrumentation output, the fuzzer finds the crashing input quickly. 74 | -------------------------------------------------------------------------------- /manual/style.css: -------------------------------------------------------------------------------- 1 | /* fira-sans-regular - latin */ 2 | @font-face { 3 | font-family: 'Fira Sans'; 4 | font-style: normal; 5 | font-weight: 400; 6 | src: url('../fonts/fira-sans-v8-latin-regular.eot'); /* IE9 Compat Modes */ 7 | src: local('Fira Sans Regular'), local('FiraSans-Regular'), 8 | url('../fonts/fira-sans-v8-latin-regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */ 9 | url('../fonts/fira-sans-v8-latin-regular.woff2') format('woff2'), /* Super Modern Browsers */ 10 | url('../fonts/fira-sans-v8-latin-regular.woff') format('woff'), /* Modern Browsers */ 11 | url('../fonts/fira-sans-v8-latin-regular.ttf') format('truetype'), /* Safari, Android, iOS */ 12 | url('../fonts/fira-sans-v8-latin-regular.svg#FiraSans') format('svg'); /* Legacy iOS */ 13 | } 14 | 15 | 16 | a:visited {color : #416DFF; text-decoration : none; } 17 | a:link {color : #416DFF; text-decoration : none; } 18 | a:hover {color : Black; text-decoration : underline; } 19 | a:active {color : Black; text-decoration : underline; } 20 | .keyword { font-weight : bold ; color : Red } 21 | .keywordsign { color : #C04600 } 22 | .comment { color : Green } 23 | .constructor { color : Blue } 24 | .type { color : #5C6585 } 25 | .string { color : Maroon } 26 | .warning { color : Red ; font-weight : bold } 27 | .info { margin-left : 3em; margin-right : 3em } 28 | .code { color : #465F91 ; } 29 | h1 { font-size : 2rem ; text-align: center; } 30 | 31 | h2, h3, h4, h5, h6, div.h7, div.h8, div.h9 { 32 | font-size: 1.75rem; 33 | border: 1px solid #000; 34 | margin-top: 20px; 35 | margin-bottom: 2px; 36 | text-align: center; 37 | padding: 8px; 38 | font-family: "Fira Sans", sans-serif; 39 | font-weight: normal; 40 | } 41 | h1 { 42 | font-family: "Fira Sans", sans-serif; 43 | padding: 10px; 44 | } 45 | 46 | h2 { background-color: #90BDFF; } 47 | h3 { background-color: #90DDFF; } 48 | h4 { background-color: #90EDFF; } 49 | h5 { background-color: #90FDFF; } 50 | h6 { background-color: #90BDFF; } 51 | div.h7 { background-color: #90DDFF; } 52 | div.h8 { background-color: #F0FFFF; } 53 | div.h9 { background-color: #FFFFFF; } 54 | 55 | .typetable { border-style : hidden } 56 | .indextable { border-style : hidden } 57 | .paramstable { border-style : hidden ; padding: 5pt 5pt} 58 | body { 59 | background-color : #f7f7f7; 60 | font-size: 1rem; 61 | max-width: 800px; 62 | width: 85%; 63 | margin: auto; 64 | padding-bottom: 30px; 65 | } 66 | td { 67 | font-size: 1rem; 68 | } 69 | .navbar { /* previous - up - next */ 70 | position: absolute; 71 | left: 10px; 72 | top: 10px; 73 | } 74 | tr { background-color : #f7f7f7 } 75 | td.typefieldcomment { background-color : #f7f7f7 } 76 | pre { margin-bottom: 4px; white-space: pre-wrap; } 77 | div.sig_block {margin-left: 2em} 78 | ul.info-attributes { list-style: none; margin: 0; padding: 0; } 79 | div.info > p:first-child{ margin-top:0; } 80 | div.info-desc > p:first-child { margin-top:0; margin-bottom:0; } 81 | -------------------------------------------------------------------------------- /manual/allfiles.etex: -------------------------------------------------------------------------------- 1 | \makeindex{\jobname} 2 | \makeindex{\jobname.kwd} 3 | 4 | \setlength{\emergencystretch}{50pt} % pour que TeX resolve les overfull hbox lui-meme 5 | \def\refmanBaseUrl{https://github.com/lkwq007/ocaml-manual-cn/releases/download/} 6 | \begin{document} 7 | 8 | \thispagestyle{empty} 9 | \begin{maintitle} 10 | ~\vfill 11 | \Huge OCaml 系统 \\ 12 | 版本 \ocamlversion \\[1cm] 13 | \Large 文档与用户手册 \\[1cm] 14 | \large Xavier Leroy, \\ 15 | Damien Doligez, Alain Frisch, Jacques Garrigue, Didier Rémy and Jérôme Vouillon \\[1cm] 16 | \today \\ 17 | ~ 18 | \vfill 19 | \normalsize Copyright \copyright\ \number\year\ Institut National de 20 | Recherche en Informatique et en Automatique. \\法国国家信息与自动化研究所版权所有 21 | \end{maintitle} 22 | \cleardoublepage 23 | \setcounter{page}{1} 24 | 25 | 26 | \begin{htmlonly} 27 | \begin{quote} 28 | \rule{}{} 29 | 30 | 本文档同时也具有~ 31 | \ahref{\refmanBaseUrl\ocamlversion/ocaml-\ocamlversion-refman.pdf}{PDF 格式}、 32 | \ahref{\refmanBaseUrl\ocamlversion/ocaml-\ocamlversion-refman.txt}{纯文本格式}、 33 | \ahref{\refmanBaseUrl\ocamlversion/ocaml-\ocamlversion-refman-html.tar.gz}{HTML 格式} 34 | 与~ 35 | \ahref{\refmanBaseUrl\ocamlversion/ocaml-\ocamlversion-refman.info.tar.gz}{Emacs Info 格式}的副本。 36 | \rule{}{} 37 | \end{quote} 38 | \end{htmlonly} 39 | 40 | \tableofcontents 41 | 42 | \input{foreword.tex} 43 | 44 | \part{OCaml 简介} 45 | \label{p:tutorials} 46 | \input{coreexamples.tex} 47 | \input{moduleexamples.tex} 48 | \input{objectexamples.tex} 49 | \input{lablexamples.tex} 50 | \input{polymorphism.tex} 51 | \input{advexamples.tex} 52 | 53 | \part{OCaml 语言} 54 | \label{p:refman} 55 | \input{refman.tex} 56 | \input{exten.tex} 57 | 58 | \part{OCaml 工具} 59 | \label{p:commands} 60 | 61 | \input{comp.tex} 62 | \input{top.tex} 63 | \input{runtime.tex} 64 | \input{native.tex} 65 | \input{lexyacc.tex} 66 | \input{depend.tex} 67 | \input{browser.tex} 68 | \input{ocamldoc.tex} 69 | \input{debugger.tex} 70 | \input{profil.tex} 71 | \input{ocamlbuild.tex} 72 | % \input emacs.tex 73 | \input{intf-c.tex} 74 | \input{flambda.tex} 75 | \input{spacetime.tex} 76 | \input{afl-fuzz.tex} 77 | \input{plugins} 78 | 79 | \part{OCaml 库} 80 | \label{p:library} 81 | \input{core.tex} 82 | \input{stdlib.tex} 83 | \input{compilerlibs.tex} 84 | \input{libunix.tex} 85 | \input{libnum.tex} 86 | \input{libstr.tex} 87 | \input{libthreads.tex} 88 | \input{libgraph.tex} 89 | \input{libdynlink.tex} 90 | \input{libbigarray.tex} 91 | 92 | \part{附录} 93 | \label{p:appendix} 94 | 95 | \ifouthtml 96 | \begin{links} 97 | \item \ahref{libref/index_modules.html}{模块索引} 98 | \item \ahref{libref/index_module_types.html}{模块类型索引} 99 | \item \ahref{libref/index_types.html}{类型索引} 100 | \item \ahref{libref/index_exceptions.html}{异常索引} 101 | \item \ahref{libref/index_values.html}{值索引} 102 | \end{links} 103 | \else 104 | \printindex{\jobname}{库索引} 105 | \fi 106 | \printindex{\jobname.kwd}{关键字索引} 107 | 108 | \end{document} 109 | -------------------------------------------------------------------------------- /manual/library/libthreads.etex: -------------------------------------------------------------------------------- 1 | \chapter{The threads library} 2 | \label{c:threads}\cutname{threads.html} 3 | %HEVEA\cutname{libthreads.html} 4 | 5 | \textbf{Warning:} the "threads" library is deprecated since version 6 | 4.08.0 of OCaml. Please switch to system threads, which have the same 7 | API. Lightweight threads with VM-level scheduling are provided by 8 | third-party libraries such as Lwt, but with a different API. 9 | 10 | The "threads" library allows concurrent programming in OCaml. 11 | It provides multiple threads of control (also called lightweight 12 | processes) that execute concurrently in the same memory space. Threads 13 | communicate by in-place modification of shared data structures, or by 14 | sending and receiving data on communication channels. 15 | 16 | The "threads" library is implemented by time-sharing on a single 17 | processor. It will not take advantage of multi-processor machines. 18 | Using this library will therefore never make programs run 19 | faster. However, many programs are easier to write when structured as 20 | several communicating processes. 21 | 22 | Two implementations of the "threads" library are available, depending 23 | on the capabilities of the operating system: 24 | \begin{itemize} 25 | \item System threads. This implementation builds on the OS-provided threads 26 | facilities: POSIX 1003.1c threads for Unix, and Win32 threads for 27 | Windows. When available, system threads support both bytecode and 28 | native-code programs. 29 | \item VM-level threads. This implementation performs time-sharing and 30 | context switching at the level of the OCaml virtual machine (bytecode 31 | interpreter). It is available on Unix systems, and supports only 32 | bytecode programs. It cannot be used with native-code programs. 33 | \end{itemize} 34 | Programs that use system threads must be linked as follows: 35 | \begin{alltt} 36 | ocamlc -I +threads \var{other options} unix.cma threads.cma \var{other files} 37 | ocamlopt -I +threads \var{other options} unix.cmxa threads.cmxa \var{other files} 38 | \end{alltt} 39 | Compilation units that use the "threads" library must also be compiled with 40 | the "-I +threads" option (see chapter~\ref{c:camlc}). 41 | 42 | Programs that use VM-level threads must be compiled with the "-vmthread" 43 | option to "ocamlc" (see chapter~\ref{c:camlc}), and be linked as follows: 44 | \begin{alltt} 45 | ocamlc -vmthread \var{other options} threads.cma \var{other files} 46 | \end{alltt} 47 | Compilation units that use "threads" library must also be compiled with 48 | the "-vmthread" option (see chapter~\ref{c:camlc}). 49 | 50 | \ifouthtml 51 | \begin{links} 52 | \item \ahref{libref/Thread.html}{Module \texttt{Thread}: lightweight threads} 53 | \item \ahref{libref/Mutex.html}{Module \texttt{Mutex}: locks for mutual exclusion} 54 | \item \ahref{libref/Condition.html}{Module \texttt{Condition}: condition variables to synchronize between threads} 55 | \item \ahref{libref/Event.html}{Module \texttt{Event}: first-class synchronous communication} 56 | \item \ahref{libref/ThreadUnix.html}{Module \texttt{ThreadUnix}: thread-compatible system calls} 57 | \end{links} 58 | \else 59 | \input{Thread.tex} 60 | \input{Mutex.tex} 61 | \input{Condition.tex} 62 | \input{Event.tex} 63 | \input{ThreadUnix.tex} 64 | \fi 65 | -------------------------------------------------------------------------------- /tools/transf.mll: -------------------------------------------------------------------------------- 1 | { 2 | open Lexing;; 3 | open Printf;; 4 | 5 | let print_char_repr c = 6 | match c with 7 | | '\'' -> printf "{\\textquotesingle}" 8 | | '`' -> printf "{\\textasciigrave}" 9 | | _ -> printf "\\char%d" (int_of_char c); 10 | ;; 11 | } 12 | 13 | rule main = parse 14 | "\\begin{syntax}" { 15 | print_string "\\begin{syntax}"; 16 | syntax lexbuf } 17 | | "\\begin{verbatim}" | "\\camlexample" as s { 18 | print_string s; 19 | verbatim lexbuf } 20 | | "\\@" { 21 | print_string "@"; 22 | main lexbuf } 23 | | "@" { 24 | print_string "\\synt{"; 25 | syntax lexbuf } 26 | | _ { 27 | print_char (lexeme_char lexbuf 0); main lexbuf } 28 | | eof { 29 | () } 30 | 31 | and syntax = parse 32 | "\\end{syntax}" { 33 | print_string "\\end{syntax}"; 34 | main lexbuf } 35 | | "@" { 36 | print_string "}"; 37 | main lexbuf } 38 | | '\'' { 39 | print_string "\\token{"; 40 | inquote lexbuf } 41 | | '\"' { 42 | print_string "\\token{"; 43 | indoublequote lexbuf } 44 | | "epsilon" { print_string "\\emptystring"; syntax lexbuf } 45 | | ['a'-'z' 'A'-'Z'] ['a'-'z' 'A'-'Z' '0'-'9' '-'] * as lxm { 46 | print_string "\\nonterm{"; 47 | print_string lxm ; 48 | print_string"}"; 49 | syntax lexbuf } 50 | | '@' (['a'-'z' 'A'-'Z'] ['a'-'z' 'A'-'Z' '0'-'9' '-'] * as lxm) '@' { 51 | print_string "\\nt{"; 52 | print_string lxm ; 53 | print_string"}"; 54 | syntax lexbuf } 55 | 56 | | '\\' ['a'-'z''A'-'Z'] + { 57 | print_string (lexeme lexbuf); 58 | syntax lexbuf } 59 | | ['_' '^'] _ { 60 | print_string (lexeme lexbuf); 61 | syntax lexbuf } 62 | | "{" { print_string "\\brepet{}"; syntax lexbuf } 63 | | "}" { print_string "\\erepet{}"; syntax lexbuf } 64 | | "{{" { print_string "\\brepets{}"; syntax lexbuf } 65 | | "}}" { print_string "\\erepets{}"; syntax lexbuf } 66 | | "[" { print_string "\\boption{}"; syntax lexbuf } 67 | | "]" { print_string "\\eoption{}"; syntax lexbuf } 68 | | "(" { print_string "\\bparen{}"; syntax lexbuf } 69 | | ")" { print_string "\\eparen{}"; syntax lexbuf } 70 | | "||" { print_string "\\orelse{}"; syntax lexbuf } 71 | | ":" { print_string "\\is{}"; syntax lexbuf } 72 | | "|" { print_string "\\alt{}"; syntax lexbuf } 73 | | ";" { print_string "\\sep{}"; syntax lexbuf } 74 | | "\\\\" { print_string "\\cutline{}"; syntax lexbuf } 75 | | _ { 76 | print_char (lexeme_char lexbuf 0); 77 | syntax lexbuf } 78 | 79 | and inquote = parse 80 | ['A'-'Z' 'a'-'z' '0'-'9'] { 81 | print_char (lexeme_char lexbuf 0); 82 | inquote lexbuf } 83 | | '\'' { 84 | print_string "}"; 85 | syntax lexbuf } 86 | | _ { 87 | print_char_repr (lexeme_char lexbuf 0); 88 | inquote lexbuf } 89 | 90 | and indoublequote = parse 91 | ['A'-'Z' 'a'-'z' '0'-'9'] { 92 | print_char (lexeme_char lexbuf 0); 93 | indoublequote lexbuf } 94 | | '"' { 95 | print_string "}"; 96 | syntax lexbuf } 97 | | _ { 98 | print_char_repr (lexeme_char lexbuf 0); 99 | indoublequote lexbuf } 100 | 101 | and verbatim = parse 102 | "\n\\end{verbatim}"|"\\endcamlexample" as s { 103 | print_string s; 104 | main lexbuf } 105 | | _ { 106 | print_char (lexeme_char lexbuf 0); 107 | verbatim lexbuf } 108 | -------------------------------------------------------------------------------- /manual/manual.inf: -------------------------------------------------------------------------------- 1 | \input{book.hva} 2 | \renewcommand{\@indexsection}[1]{\chapter{#1}} 3 | \newcommand{\black}{\htmlcolor{#000000}} 4 | \newcommand{\machine}{\tt} 5 | \newenvironment{machineenv}{\begin{alltt}}{\end{alltt}} 6 | \newenvironment{camlunder}{\@style{U}}{} 7 | \newcommand{\caml}{\begin{alltt}\renewcommand{\\}{\char92}\def\<{\begin{camlunder}}\def\>{\end{camlunder}}\activebracefalse} 8 | \newcommand{\endcaml}{\activebracetrue\end{alltt}} 9 | \newcommand{\?}{\black\#\blue } 10 | \renewcommand{\:}{\maroon} 11 | \def\camlinput{} 12 | \def\endcamlinput{} 13 | \def\camloutput{} 14 | \def\endcamloutput{} 15 | \def\camlerror{} 16 | \def\endcamlerror{} 17 | \def\camlwarn{} 18 | \def\endcamlwarn{} 19 | \newcommand{\var}[1]{\textit{#1}} 20 | 21 | \newenvironment{library}{}{} 22 | \newcounter{page} 23 | \newenvironment{comment}{\begin{quote}}{\end{quote}} 24 | \newcommand{\nth}[2]{\({#1}_{#2}\)} 25 | \newenvironment{options}{\begin{description}}{\end{description}} 26 | 27 | 28 | %%venant de macros.tex 29 | \newif\ifouthtml\outhtmlfalse 30 | \def\versionspecific#1{ 31 | \quad\textsf{#1:} 32 | \begin{quote}} 33 | 34 | \def\unix{\versionspecific{Unix}} 35 | \def\endunix{\end{quote}} 36 | \def\macos{\versionspecific{MacOS}} 37 | \def\endmacos{\end{quote}} 38 | \def\windows{\versionspecific{Windows}} 39 | \def\endwindows{\end{quote}} 40 | 41 | \def\requirements{\trivlist \item[\hskip\labelsep {\bf Requirements.}]} 42 | \def\endrequirements{\endtrivlist} 43 | \def\installation{\trivlist \item[\hskip\labelsep {\bf Installation.}]} 44 | \def\endinstallation{\endtrivlist} 45 | \def\troubleshooting{\trivlist \item[\hskip\labelsep {\bf Troubleshooting.}]} 46 | \def\endtroubleshooting{\endtrivlist} 47 | 48 | \newtheorem{gcrule}{Rule} 49 | 50 | % Pour les tables de priorites et autres tableaux a deux colonnes, encadres 51 | 52 | %\def\entree#1#2{#1 & #2 \\} 53 | %\def\tableau#1#2#3{% 54 | %\par\begin{center}% 55 | %\begin{tabular}{#1}% 56 | %\multicolumn{1}{c}{\textbf{#2}} & 57 | %\multicolumn{1}{c}{\textbf{#3}} \\ 58 | %%#2 & #3 \\% 59 | %}% 60 | %\def\endtableau{\end{tabular}\end{center}\par} 61 | 62 | % Pour les tables de priorites et autres tableaux a deux colonnes, encadres 63 | 64 | \def\tableau#1#2#3{% 65 | \begin{center} 66 | \begin{tabular}{#1} 67 | \hline 68 | \multicolumn{1}{|c|}{\textbf{#2}} & \multicolumn{1}{c|}{\textbf{#3}} \\ 69 | \hline 70 | } 71 | \def\endtableau{\hline\end{tabular}\end{center}} 72 | \def\entree#1#2{#1 & #2 \\} 73 | 74 | 75 | 76 | % L'environnement library (pour composer les descriptions des modules 77 | % de bibliotheque). 78 | 79 | 80 | \def\restoreindent{\begingroup\let\@listI=\@savedlistI} 81 | \def\endrestoreindent{\endgroup} 82 | 83 | 84 | % PDF stuff 85 | 86 | \def\pdfchapterfold#1#2{} 87 | \def\pdfsection#1{} 88 | \def\pdfchapter{\pdfchapterfold{0}} 89 | 90 | %%% Pour camlidl 91 | 92 | \def\transl#1{$[\![\mbox{#1}]\!]$} 93 | 94 | % Pour l'index 95 | \usepackage{multind} 96 | \let\indexentry=\index 97 | \renewcommand{\index}[1]{\indexentry{\jobname}{#1}} 98 | \def\ikwd#1{\indexentry{\jobname.kwd}{#1}} 99 | 100 | 101 | % nth 102 | \def\th{^{\mbox{\scriptsize th}}} 103 | \renewcommand{\hbox}[1]{\mbox{#1}} 104 | 105 | % Notations pour les metavariables 106 | \def\nmth#1#2#3{\({#1}_{#2}^{#3}\)} 107 | \def\optvar#1{[\var{#1}\/]} 108 | \def\event{§§} 109 | \def\fromoneto#1#2{$#1 = 1,\ldots{} , #2$} 110 | 111 | \newcommand{\vfill}{} 112 | \def\number{} 113 | \def\year{2013} 114 | 115 | % Pour alltt 116 | 117 | \def\rminalltt#1{{\rm #1}} 118 | 119 | \def\goodbreak{\ \\} 120 | 121 | \def\@savedlistI{} 122 | -------------------------------------------------------------------------------- /tools/htmltransf.mll: -------------------------------------------------------------------------------- 1 | { 2 | open Lexing;; 3 | 4 | let need_space = 5 | ref false;; 6 | 7 | let addspace () = 8 | if !need_space then begin print_char ' '; need_space := false end;; 9 | } 10 | 11 | rule main = parse 12 | "\\begin{syntax}" { 13 | print_string "\\begin{rawhtml}\n
\n";
 14 |       need_space := false;
 15 |       syntax lexbuf;
 16 |       print_string "
\n\\end{rawhtml}\n"; 17 | main lexbuf } 18 | | "\\@" { 19 | print_string "@"; 20 | main lexbuf } 21 | | "@" { 22 | print_string "%\n\\begin{rawhtml}"; 23 | need_space := false; 24 | syntax lexbuf; 25 | print_string "\\end{rawhtml}%\n"; 26 | main lexbuf } 27 | | _ { 28 | print_char (lexeme_char lexbuf 0); main lexbuf } 29 | | eof { 30 | () } 31 | 32 | and syntax = parse 33 | "\\end{syntax}" { () } 34 | | "@" { () } 35 | | '\'' { 36 | addspace(); 37 | print_string ""; 38 | inquote lexbuf; 39 | print_string ""; 40 | need_space := true; 41 | syntax lexbuf } 42 | | '\"' { 43 | addspace(); 44 | print_string ""; 45 | indoublequote lexbuf; 46 | print_string ""; 47 | need_space := true; 48 | syntax lexbuf } 49 | | ['a'-'z'] ['a'-'z' '0'-'9' '-'] * { 50 | addspace(); 51 | print_string ""; 52 | print_string (lexeme lexbuf); 53 | print_string ""; 54 | need_space := true; 55 | syntax lexbuf } 56 | | '\\' ['a'-'z''A'-'Z'] + { 57 | begin match lexeme lexbuf with 58 | "\\ldots" -> print_string "..."; need_space := false 59 | | s -> Printf.eprintf "Warning: %s ignored.\n" s 60 | end; 61 | syntax lexbuf } 62 | | '_' _ { 63 | print_string ""; 64 | print_char(lexeme_char lexbuf 1); 65 | print_string ""; 66 | syntax lexbuf } 67 | | '^' _ { 68 | print_string ""; 69 | print_char(lexeme_char lexbuf 1); 70 | print_string ""; 71 | syntax lexbuf } 72 | | ":" { 73 | print_string ":\n "; 74 | need_space := false; 75 | syntax lexbuf } 76 | | "|" { 77 | print_string "\n | "; 78 | need_space := false; 79 | syntax lexbuf } 80 | | ";" { 81 | print_string "\n\n"; 82 | need_space := false; 83 | syntax lexbuf } 84 | | [ '{' '[' '('] { 85 | addspace(); print_string (lexeme lexbuf); syntax lexbuf } 86 | | [ '}' ']' ')'] { 87 | print_string (lexeme lexbuf); syntax lexbuf } 88 | | "{{" { 89 | addspace(); print_string "{"; syntax lexbuf } 90 | | "}}" { 91 | print_string "}+"; syntax lexbuf } 92 | | "||" { 93 | print_string " | "; need_space := false; syntax lexbuf } 94 | | [ ' ' '\n' '\t' '~'] { 95 | syntax lexbuf } 96 | | [ ',' ] { 97 | print_char(lexeme_char lexbuf 0); syntax lexbuf } 98 | | _ { 99 | Printf.eprintf "Warning: %s ignored at char %d.\n" 100 | (lexeme lexbuf) (lexeme_start lexbuf); 101 | syntax lexbuf } 102 | 103 | and inquote = parse 104 | '\'' { () } 105 | | '&' { print_string "&"; inquote lexbuf } 106 | | '<' { print_string "<"; inquote lexbuf } 107 | | '>' { print_string ">"; inquote lexbuf } 108 | | _ { print_char (lexeme_char lexbuf 0); inquote lexbuf } 109 | 110 | and indoublequote = parse 111 | '"' { () } 112 | | '&' { print_string "&"; indoublequote lexbuf } 113 | | '<' { print_string "<"; indoublequote lexbuf } 114 | | '>' { print_string ">"; indoublequote lexbuf } 115 | | _ { print_char (lexeme_char lexbuf 0); indoublequote lexbuf } 116 | 117 | 118 | -------------------------------------------------------------------------------- /manual/library/libgraph.etex: -------------------------------------------------------------------------------- 1 | \chapter{The graphics library} 2 | %HEVEA\cutname{libgraph.html} 3 | 4 | The "graphics" library provides a set of portable drawing primitives. 5 | Drawing takes place 6 | in a separate window that is created when "Graphics.open_graph" is called. 7 | 8 | \begin{unix} 9 | This library is implemented under the X11 windows system. 10 | Programs that use the "graphics" library must be linked as follows: 11 | \begin{alltt} 12 | ocamlc \var{other options} graphics.cma \var{other files} 13 | \end{alltt} 14 | For interactive use of the "graphics" library, do: 15 | \begin{alltt} 16 | ocamlmktop -o mytop graphics.cma 17 | ./mytop 18 | \end{alltt} 19 | or (if dynamic linking of C libraries is supported on your platform), 20 | start "ocaml" and type "#load \"graphics.cma\";;". 21 | 22 | Here are the graphics mode specifications supported by 23 | "Graphics.open_graph" on 24 | the X11 implementation of this library: 25 | the argument to "Graphics.open_graph" has the format 26 | "\""{\it display-name} {\it geometry\/}"\"", 27 | where {\it display-name} is the name of the X-windows display to 28 | connect to, and {\it geometry} is a standard X-windows geometry 29 | specification. The two components are separated by a space. Either can 30 | be omitted, or both. Examples: 31 | \begin{options} 32 | \item["Graphics.open_graph \"foo:0\""] 33 | connects to the display "foo:0" and creates a window with the default geometry 34 | \item["Graphics.open_graph \"foo:0 300x100+50-0\""] 35 | connects to the display "foo:0" and creates a window 300 pixels wide 36 | by 100 pixels tall, at location $(50,0)$ 37 | \item["Graphics.open_graph \" 300x100+50-0\""] 38 | connects to the default display and creates a window 300 pixels wide 39 | by 100 pixels tall, at location $(50,0)$ 40 | \item["Graphics.open_graph \"\""] 41 | connects to the default display and creates a window with the default 42 | geometry. 43 | \end{options} 44 | \end{unix} 45 | 46 | \begin{windows} 47 | This library is available both for standalone compiled programs and 48 | under the toplevel application "ocamlwin.exe". For the latter, this 49 | library must be loaded in-core by typing 50 | \begin{verbatim} 51 | #load "graphics.cma";; 52 | \end{verbatim} 53 | \end{windows} 54 | 55 | The screen coordinates are interpreted as shown in the figure below. 56 | Notice that the coordinate system used is the same as in mathematics: 57 | $y$ increases from the bottom of the screen to the top of the screen, 58 | and angles are measured counterclockwise (in degrees). 59 | Drawing is clipped to the screen. 60 | % 61 | \begin{latexonly} 62 | \begin{center} 63 | \setlength{\unitlength}{0.5mm} 64 | \begin{picture}(130,100)(-10,-10) 65 | \thicklines 66 | \put(-10,0){\vector(1,0){130}} 67 | \put(125,0){\makebox(0,0)[l]{$x$}} 68 | \put(0,-10){\vector(0,1){100}} 69 | \put(0,95){\makebox(0,0){$y$}} 70 | \thinlines 71 | \put(100,80){\line(-1,0){105}} 72 | \put(100,80){\line(0,-1){85}} 73 | \put(95,75){\makebox(0,0)[tr]{Screen}} 74 | \put(100,-10){\makebox(0,0){\tt size\_x()}} 75 | \put(-10,80){\makebox(0,0)[r]{\tt size\_y()}} 76 | \put(30,40){\makebox(4,4){\rule{2mm}{2mm}}} 77 | \put(36,40){pixel at $(x,y)$} 78 | \put(30,40){\line(-1,0){35}} 79 | \put(30,-10){\makebox(0,0){$x$}} 80 | \put(30,40){\line(0,-1){45}} 81 | \put(-10,40){\makebox(0,0)[r]{$y$}} 82 | \end{picture} 83 | \end{center} 84 | \end{latexonly} 85 | 86 | \begin{htmlonly} 87 | \begin{center} 88 | \imgsrc{libgraph.gif} 89 | \end{center} 90 | \end{htmlonly} 91 | % 92 | 93 | \ifouthtml 94 | \begin{links} 95 | \item \ahref{libref/Graphics.html}{Module \texttt{Graphics}: machine-independent graphics primitives} 96 | \end{links} 97 | \else 98 | \input{Graphics.tex} 99 | \fi 100 | -------------------------------------------------------------------------------- /manual/library/compilerlibs.etex: -------------------------------------------------------------------------------- 1 | \chapter{The compiler front-end} \label{c:parsinglib}\cutname{parsing.html} 2 | 3 | This chapter describes the OCaml front-end, which declares the abstract 4 | syntax tree used by the compiler, provides a way to parse, print 5 | and pretty-print OCaml code, and ultimately allows to write abstract 6 | syntax tree preprocessors invoked via the {\tt -ppx} flag (see chapters~\ref{c:camlc} 7 | and~\ref{c:nativecomp}) and plugins invoked via the {\tt -plugin} flag 8 | (see chapter~\ref{c:plugins}). 9 | 10 | It is important to note that the exported front-end interface follows the evolution of the OCaml language and implementation, and thus does not provide {\bf any} backwards compatibility guarantees. 11 | 12 | The front-end is a part of "compiler-libs" library. 13 | Programs that use the "compiler-libs" library should be built as follows: 14 | \begin{alltt} 15 | ocamlfind ocamlc \var{other options} -package compiler-libs.common \var{other files} 16 | ocamlfind ocamlopt \var{other options} -package compiler-libs.common \var{other files} 17 | \end{alltt} 18 | Use of the {\tt ocamlfind} utility is recommended. However, if this is not possible, an alternative method may be used: 19 | \begin{alltt} 20 | ocamlc \var{other options} -I +compiler-libs ocamlcommon.cma \var{other files} 21 | ocamlopt \var{other options} -I +compiler-libs ocamlcommon.cmxa \var{other files} 22 | \end{alltt} 23 | For interactive use of the "compiler-libs" library, start "ocaml" and 24 | type\\*"#load \"compiler-libs/ocamlcommon.cma\";;". 25 | 26 | % Some of the files below are commented out as the documentation is too poor 27 | % or they are thought to be nonessential. 28 | 29 | \ifouthtml 30 | \begin{links} 31 | \item \ahref{compilerlibref/Ast\_helper.html}{Module \texttt{Ast_helper}: helper functions for AST construction} 32 | \item \ahref{compilerlibref/Ast\_mapper.html}{Module \texttt{Ast_mapper}: -ppx rewriter interface} 33 | \item \ahref{compilerlibref/Asttypes.html}{Module \texttt{Asttypes}: auxiliary types used by Parsetree} 34 | % \item \ahref{compilerlibref/Lexer.html}{Module \texttt{Lexer}: OCaml syntax lexing} 35 | \item \ahref{compilerlibref/Location.html}{Module \texttt{Location}: source code locations} 36 | \item \ahref{compilerlibref/Longident.html}{Module \texttt{Longident}: long identifiers} 37 | \item \ahref{compilerlibref/Parse.html}{Module \texttt{Parse}: OCaml syntax parsing} 38 | \item \ahref{compilerlibref/Parsetree.html}{Module \texttt{Parsetree}: OCaml syntax tree} 39 | \item \ahref{compilerlibref/Pprintast.html}{Module \texttt{Pprintast}: OCaml syntax printing} 40 | % \item \ahref{compilerlibref/Printast.html}{Module \texttt{Printast}: AST printing} 41 | \end{links} 42 | 43 | \else 44 | % Ast_helper is excluded from the PDF and text manuals. 45 | % It is over 20 pages long and does not have doc-comments. It is expected 46 | % that Ast_helper will be only useful in the HTML manual (to look up signatures). 47 | % \input{Asthelper.tex} 48 | \input{Astmapper.tex} 49 | \input{Asttypes.tex} 50 | % \input{Lexer.tex} 51 | \input{Location.tex} 52 | \input{Longident.tex} 53 | \input{Parse.tex} 54 | \input{Parsetree.tex} 55 | \input{Pprintast.tex} 56 | % \input{Printast.tex} 57 | \fi 58 | 59 | \ifouthtml 60 | The following modules provides hooks for compiler plugins: 61 | \begin{links} 62 | \item \ahref{compilerlibref/Pparse.html}{Module \texttt{Pparse}: OCaml parser driver} 63 | \item \ahref{compilerlibref/Typemod.html}{Module \texttt{Typemod}: 64 | OCaml module type checking} 65 | \item \ahref{compilerlibref/Simplif.html}{Module \texttt{Simplif}: Lambda simplification} 66 | \item \ahref{compilerlibref/Clflags.html}{Module \texttt{Clflags}: command line flags} 67 | \end{links} 68 | \else 69 | \input{Pparse.tex} 70 | \input{Typemod.tex} 71 | \input{Simplif.tex} 72 | \input{Clflags.tex} 73 | \fi 74 | -------------------------------------------------------------------------------- /manual/refman/values.etex: -------------------------------------------------------------------------------- 1 | \section{Values} 2 | %HEVEA\cutname{values.html} 3 | 4 | This section describes the kinds of values that are manipulated by 5 | OCaml programs. 6 | 7 | \subsection{Base values} 8 | 9 | \subsubsection*{Integer numbers} 10 | 11 | Integer values are integer numbers from $-2^{30}$ to $2^{30}-1$, that 12 | is $-1073741824$ to $1073741823$. The implementation may support a 13 | wider range of integer values: on 64-bit platforms, the current 14 | implementation supports integers ranging from $-2^{62}$ to $2^{62}-1$. 15 | 16 | \subsubsection*{Floating-point numbers} 17 | 18 | Floating-point values are numbers in floating-point representation. 19 | The current implementation uses double-precision floating-point 20 | numbers conforming to the IEEE 754 standard, with 53 bits of mantissa 21 | and an exponent ranging from $-1022$ to $1023$. 22 | 23 | \subsubsection*{Characters} 24 | 25 | Character values are represented as 8-bit integers between 0 and 255. 26 | Character codes between 0 and 127 are interpreted following the ASCII 27 | standard. The current implementation interprets character codes 28 | between 128 and 255 following the ISO 8859-1 standard. 29 | 30 | \subsubsection*{Character strings} \label{s:string-val} 31 | 32 | String values are finite sequences of characters. The current 33 | implementation supports strings containing up to $2^{24} - 5$ 34 | characters (16777211 characters); on 64-bit platforms, the limit is 35 | $2^{57} - 9$. 36 | 37 | \subsection{Tuples} 38 | 39 | Tuples of values are written @'('@v@_1',' \ldots',' @v@_n')'@, standing for the 40 | $n$-tuple of values @@v@_1@ to @@v@_n@. The current implementation 41 | supports tuple of up to $2^{22} - 1$ elements (4194303 elements). 42 | 43 | \subsection{Records} 44 | 45 | Record values are labeled tuples of values. The record value written 46 | @'{' field_1 '=' @v@_1';' \ldots';' field_n '=' @v@_n '}'@ associates the value 47 | @@v@_i@ to the record field @field_i@, for $i = 1 \ldots n$. The current 48 | implementation supports records with up to $2^{22} - 1$ fields 49 | (4194303 fields). 50 | 51 | \subsection{Arrays} 52 | 53 | Arrays are finite, variable-sized sequences of values of the same 54 | type. The current implementation supports arrays containing up to 55 | $2^{22} - 1$ elements (4194303 elements) unless the elements are 56 | floating-point numbers (2097151 elements in this case); on 64-bit 57 | platforms, the limit is $2^{54} - 1$ for all arrays. 58 | 59 | \subsection{Variant values} 60 | 61 | Variant values are either a constant constructor, or a non-constant 62 | constructor applied to a number of values. The former case is written 63 | @constr@; the latter case is written @constr '('@v@_1',' ... ',' @v@_n 64 | ')'@, where the @@v@_i@ are said to be the arguments of the non-constant 65 | constructor @constr@. The parentheses may be omitted if there is only 66 | one argument. 67 | 68 | The following constants are treated like built-in constant 69 | constructors: 70 | \begin{tableau}{|l|l|}{Constant}{Constructor} 71 | \entree{"false"}{the boolean false} 72 | \entree{"true"}{the boolean true} 73 | \entree{"()"}{the ``unit'' value} 74 | \entree{"[]"}{the empty list} 75 | \end{tableau} 76 | 77 | The current implementation limits each variant type to have at most 78 | 246 non-constant constructors and $2^{30}-1$ constant constructors. 79 | 80 | \subsection{Polymorphic variants} 81 | 82 | Polymorphic variants are an alternate form of variant values, not 83 | belonging explicitly to a predefined variant type, and following 84 | specific typing rules. They can be either constant, written 85 | @"`"tag-name@, or non-constant, written @"`"tag-name'('@v@')'@. 86 | 87 | \subsection{Functions} 88 | 89 | Functional values are mappings from values to values. 90 | 91 | \subsection{Objects} 92 | 93 | Objects are composed of a hidden internal state which is a 94 | record of instance variables, and a set of methods for accessing and 95 | modifying these variables. The structure of an object is described by 96 | the toplevel class that created it. 97 | -------------------------------------------------------------------------------- /manual/cmds/plugins.etex: -------------------------------------------------------------------------------- 1 | \chapter{Compiler plugins\label{c:plugins}} 2 | %HEVEA\cutname{plugins.html} 3 | 4 | \section{Overview} 5 | 6 | Starting from OCaml 4.03, it is possible to extend the native and bytecode compilers 7 | with plugins using the "-plugin" command line option of both tools. 8 | This possibility is also available for "ocamldep" for OCaml version ulterior to 4.05. 9 | Beware however that plugins are an advanced feature of which the design 10 | is still in flux and breaking changes may happen in the future. Plugins features 11 | are based on the compiler library API. In complement, new hooks have been added to 12 | the compiler to increase its flexibility. 13 | 14 | In particular, hooks are available in the 15 | \ifouthtml\ahref{libref/Pparse.html}{\texttt{Pparse} module} 16 | \else\texttt{Pparse} module (see section~\ref{Pparse})\fi 17 | to transform the parsed abstract syntax tree, providing similar functionality 18 | to extension point based preprocessors. 19 | Other hooks are available to analyze the typed tree in the 20 | \ifouthtml\ahref{libref/Typemod.html}{\texttt{Typemod} module} 21 | \else\texttt{Typemod} module (see section~\ref{Typemod})\fi 22 | after the type-checking phase of the compiler. Since the typed tree relies 23 | on numerous invariants that play a vital part in ulterior phases of the 24 | compiler, it is not possible however to transform the typed tree. 25 | Similarly, the intermediary lambda representation can be modified by using the 26 | hooks provided in the 27 | \ifouthtml\ahref{libref/Simplif.html}{\texttt{Simplif} module} 28 | \else\texttt{Simplif} module (see section~\ref{Simplif})\fi. 29 | A plugin can also add new options to a tool through the 30 | "Clflags.add_arguments" function (see 31 | \ifouthtml\ahref{libref/Clflags.html}{\texttt{Clflags} module} 32 | \else\texttt{Clflags} module (see section~\ref{Clflags})\fi). 33 | 34 | Plugins are dynamically loaded and need to be compiled in the same mode (i.e. 35 | native or bytecode) that the tool they extend. 36 | 37 | \section{Basic example} 38 | 39 | As an illustration, we shall build a simple "Hello world" plugin that adds 40 | a simple statement "print_endline \"Hello from:$sourcefile\"" to a compiled file. 41 | 42 | The simplest way to implement this feature is to modify the abstract syntax 43 | tree. We will therefore add an hooks to the "Pparse.ImplementationHooks". 44 | Since the proposed modification is very basic, we could implement the hook 45 | directly. However, for the sake of this illustration, we use the "Ast_mapper" 46 | structure that provides a better path to build more interesting plugins. 47 | 48 | The first step is to build the AST fragment corresponding to the 49 | evaluation of "print_endline": 50 | \begin{verbatim} 51 | let print_endline name = 52 | let open Ast_helper in 53 | let print_endline = Exp.ident 54 | @@ Location.mknoloc @@Longident.Lident "print_endline" in 55 | let hello = Exp.constant @@ Const.string @@ "Hello from: " ^ name in 56 | Str.eval @@ Exp.apply print_endline [Asttypes.Nolabel, hello] 57 | \end{verbatim}% 58 | Then, we can construct an ast mapper that adds this fragment to the parsed 59 | ast tree. 60 | \begin{verbatim} 61 | let add_hello name (mapper:Ast_mapper.mapper) structure = 62 | let default = Ast_mapper.default_mapper in 63 | (print_endline name) :: (default.structure default structure) 64 | 65 | let ast_mapper name = 66 | { Ast_mapper.default_mapper with structure = add_hello name } 67 | \end{verbatim}% 68 | % 69 | Once this AST mapper is constructed, we need to convert it to a hook and adds this 70 | hook to the "Pparse.ImplementationsHooks". 71 | \begin{verbatim} 72 | let transform hook_info structure = 73 | let astm = ast_mapper hook_info.Misc.sourcefile in 74 | astm.structure astm structure 75 | 76 | let () = Pparse.ImplementationHooks.add_hook "Hello world hook" transform 77 | \end{verbatim} 78 | % 79 | The resulting simplistic plugin can then be compiled with 80 | \begin{verbatim} 81 | $ ocamlopt -I +compiler-libs -shared plugin.ml -o plugin.cmxs 82 | \end{verbatim} 83 | % 84 | Compiling other files with this plugin enabled is then as simple as 85 | \begin{verbatim} 86 | $ ocamlopt -plugin plugin.cmxs test.ml -o test 87 | \end{verbatim} 88 | -------------------------------------------------------------------------------- /manual/library/libunix.etex: -------------------------------------------------------------------------------- 1 | \chapter{The unix library: Unix system calls} 2 | %HEVEA\cutname{libunix.html} 3 | \label{c:unix} 4 | 5 | The "unix" library makes many Unix 6 | system calls and system-related library functions available to 7 | OCaml programs. This chapter describes briefly the functions 8 | provided. Refer to sections 2~and~3 of the Unix manual for more 9 | details on the behavior of these functions. 10 | 11 | \ifouthtml 12 | \begin{links} 13 | \item \ahref{libref/Unix.html}{Module \texttt{Unix}: Unix system calls} 14 | \item \ahref{libref/UnixLabels.html}{Module \texttt{UnixLabels}: Labeled 15 | Unix system calls} 16 | \end{links} 17 | \fi 18 | 19 | Not all functions are provided by all Unix variants. If some functions 20 | are not available, they will raise "Invalid_arg" when called. 21 | 22 | Programs that use the "unix" library must be linked as follows: 23 | \begin{alltt} 24 | ocamlc \var{other options} unix.cma \var{other files} 25 | ocamlopt \var{other options} unix.cmxa \var{other files} 26 | \end{alltt} 27 | For interactive use of the "unix" library, do: 28 | \begin{alltt} 29 | ocamlmktop -o mytop unix.cma 30 | ./mytop 31 | \end{alltt} 32 | or (if dynamic linking of C libraries is supported on your platform), 33 | start "ocaml" and type "#load \"unix.cma\";;". 34 | 35 | \begin{windows} 36 | A fairly complete emulation of the Unix system calls is provided in 37 | the Windows version of OCaml. The end of this chapter gives 38 | more information on the functions that are not supported under Windows. 39 | \end{windows} 40 | 41 | \begin{latexonly} 42 | \input{Unix.tex} 43 | 44 | \section{Module \texttt{UnixLabels}: labelized version of the interface} 45 | \label{UnixLabels} 46 | \index{UnixLabels (module)@\verb~UnixLabels~ (module)}% 47 | 48 | This module is identical to "Unix"~(\ref{Unix}), and only differs by 49 | the addition of labels. You may see these labels directly by looking 50 | at "unixLabels.mli", or by using the "ocamlbrowser" tool. 51 | 52 | \newpage 53 | \end{latexonly} 54 | 55 | \begin{windows} 56 | The Cygwin port of OCaml fully implements all functions from 57 | the Unix module. The native Win32 ports implement a subset of them. 58 | Below is a list of the functions that are not implemented, or only 59 | partially implemented, by the Win32 ports. Functions not mentioned are 60 | fully implemented and behave as described previously in this chapter. 61 | 62 | \begin{tableau}{|l|p{8cm}|}{Functions}{Comment} 63 | \entree{"fork"}{not implemented, use "create_process" or threads} 64 | \entree{"wait"}{not implemented, use "waitpid"} 65 | \entree{"waitpid"}{can only wait for a given PID, not any child process} 66 | \entree{"getppid"}{not implemented (meaningless under Windows)} 67 | \entree{"nice"}{not implemented} 68 | \entree{"truncate", "ftruncate"}{not implemented} 69 | \entree{"link"}{implemented (since 3.02)} 70 | \entree{"symlink", "readlink"}{implemented (since 4.03.0)} 71 | \entree{"access"}{execute permission "X_OK" cannot be tested, 72 | it just tests for read permission instead} 73 | \entree{"fchmod"}{not implemented} 74 | \entree{"chown", "fchown"}{not implemented (make no sense on a DOS 75 | file system)} 76 | \entree{"umask"}{not implemented} 77 | \entree{"mkfifo"}{not implemented} 78 | \entree{"kill"}{partially implemented (since 4.00.0): only the "sigkill" signal 79 | is implemented} 80 | \entree{"pause"}{not implemented (no inter-process signals in Windows)} 81 | \entree{"alarm"}{not implemented} 82 | \entree{"times"}{partially implemented, will not report timings for child 83 | processes} 84 | \entree{"getitimer", "setitimer"}{not implemented} 85 | \entree{"getuid", "geteuid", "getgid", "getegid"}{always return 1} 86 | \entree{"getgroups"}{always returns "[|1|]" (since 2.00)} 87 | \entree{"setuid", "setgid", "setgroups"}{not implemented} 88 | \entree{"getpwnam", "getpwuid"}{always raise "Not_found"} 89 | \entree{"getgrnam", "getgrgid"}{always raise "Not_found"} 90 | \entree{type "socket_domain"}{"PF_INET" is fully supported; 91 | "PF_INET6" is fully supported (since 4.01.0); "PF_UNIX" is not supported } 92 | \entree{"establish_server"}{not implemented; use threads} 93 | \entree{terminal functions ("tc*")}{not implemented} 94 | \end{tableau} 95 | 96 | \end{windows} 97 | -------------------------------------------------------------------------------- /tools/texquote2.ml: -------------------------------------------------------------------------------- 1 | type environment = 2 | | Normal 3 | | Caml 4 | | Verbatim of string * string 5 | | Verbatim_like 6 | 7 | let in_quotes = ref false 8 | 9 | let is_alpha c = 10 | ('A' <= c && c <= 'Z') || ('a' <= c && c <= 'z') 11 | 12 | let is_prefix prefix str = 13 | let length_prefix = String.length prefix in 14 | let length_str = String.length str in 15 | if length_prefix > length_str 16 | then false 17 | else (String.sub str 0 length_prefix) = prefix 18 | 19 | let escape = function 20 | | ' ' | '\n' -> "\\ " 21 | | '{' -> "{\\char123}" 22 | | '}' -> "{\\char125}" 23 | | '^' -> "{\\char94}" 24 | | '_' -> "{\\char95}" 25 | | '\\' -> "{\\char92}" 26 | | '~' -> "{\\char126}" 27 | | '$' -> "\\$" 28 | | '&' -> "{\\char38}" 29 | | '#' -> "\\#" 30 | | '%' -> "\\%" 31 | | '\'' -> "{\\textquotesingle}" 32 | | '`' -> "{\\textasciigrave}" 33 | | _ -> "" 34 | 35 | let process_normal_line line = 36 | let (verb_mark : char option ref) = ref None in 37 | let l = String.length line in 38 | let i = ref 0 in 39 | while !i 42 | (match line.[!i] with 43 | | '"' -> 44 | let r = if !in_quotes then "}}" else "{\\machine{" in 45 | print_string r; 46 | in_quotes := not !in_quotes; 47 | incr i; 48 | | '\\' -> 49 | if !in_quotes 50 | then begin 51 | if (!i < l-1) && (line.[!i+1] = '"' || line.[!i+1] = '\\') 52 | then incr i; 53 | let t = escape line.[!i] in 54 | if t<>"" then print_string t else print_char line.[!i]; 55 | incr i; 56 | end else if is_prefix "\\verb" (String.sub line !i (l - !i)) 57 | && not (is_alpha line.[!i+5]) 58 | then begin 59 | i := !i+5; 60 | verb_mark := Some line.[!i]; 61 | print_string "\\verb"; 62 | print_char line.[!i]; 63 | incr i; 64 | end else (print_char '\\'; incr i) 65 | | _ -> 66 | if !in_quotes && (escape line.[!i] <> "") 67 | then print_string (escape line.[!i]) 68 | else print_char line.[!i]; 69 | incr i; 70 | ) 71 | | Some mark -> 72 | if line.[!i] = mark 73 | then verb_mark := None 74 | else if line.[!i] = '\'' || line.[!i] = '`' 75 | then Printf.eprintf "Warning: %c found in \\verb\n" line.[!i]; 76 | print_char line.[!i]; 77 | incr i; 78 | done 79 | 80 | let process_line line = function 81 | | Normal -> 82 | if is_prefix "\\begin{caml_" line || is_prefix "\\begin{rawhtml}" line 83 | then (print_string line; Verbatim_like) 84 | else if is_prefix "\\camlexample" line 85 | then (print_endline line; Caml) 86 | else if is_prefix "\\begin{verbatim}" line 87 | then begin 88 | print_string "\\begin{machineenv}"; 89 | (Verbatim ("\\end{verbatim}", "\\end{machineenv}")) 90 | end else if is_prefix "\\begin{ocamldoccode}" line 91 | then begin 92 | print_string "\\begin{ocamldoccode}"; 93 | (Verbatim ("\\end{ocamldoccode}", "\\end{ocamldoccode}")) 94 | end else begin 95 | process_normal_line line; 96 | if !in_quotes 97 | then print_string (escape '\n') 98 | else print_newline(); 99 | Normal 100 | end 101 | | Caml -> 102 | print_endline line; 103 | if is_prefix "\\endcamlexample" line then Normal else Caml 104 | | Verbatim (verbatim_end_in, verbatim_end_out) as env -> 105 | if is_prefix verbatim_end_in line 106 | then begin 107 | print_string verbatim_end_out; 108 | Normal 109 | end else begin 110 | for i=0 to (String.length line) - 1 do 111 | let c = line.[i] in 112 | let t = escape c in 113 | if c=' ' || c='\n' || t="" 114 | then print_char c 115 | else print_string t 116 | done; 117 | print_newline(); 118 | env 119 | end 120 | | Verbatim_like -> 121 | print_endline line; 122 | if is_prefix "\\end{caml_" line || is_prefix "\\end{rawhtml}" line 123 | then Normal 124 | else Verbatim_like 125 | 126 | let rec process_input env = match input_line stdin with 127 | | exception End_of_file -> () 128 | | line -> 129 | let env = process_line line env in 130 | process_input env 131 | 132 | let main() = 133 | print_endline "% THIS FILE IS GENERATED."; 134 | print_newline(); 135 | process_input Normal 136 | 137 | let _ = main() 138 | -------------------------------------------------------------------------------- /manual/refman/names.etex: -------------------------------------------------------------------------------- 1 | \section{Names} \label{s:names} 2 | %HEVEA\cutname{names.html} 3 | 4 | Identifiers are used to give names to several classes of language 5 | objects and refer to these objects by name later: 6 | \begin{itemize} 7 | \item value names (syntactic class @value-name@), 8 | \item value constructors and exception constructors (class @constr-name@), 9 | \item labels (@label-name@, defined in section~\ref{s:labelname}), 10 | \item polymorphic variant tags (@tag-name@), 11 | \item type constructors (@typeconstr-name@), 12 | \item record fields (@field-name@), 13 | \item class names (@class-name@), 14 | \item method names (@method-name@), 15 | \item instance variable names (@inst-var-name@), 16 | \item module names (@module-name@), 17 | \item module type names (@modtype-name@). 18 | \end{itemize} 19 | These eleven name spaces are distinguished both by the context and by the 20 | capitalization of the identifier: whether the first letter of the 21 | identifier is in lowercase (written @lowercase-ident@ below) or in 22 | uppercase (written @capitalized-ident@). Underscore is considered a 23 | lowercase letter for this purpose. 24 | 25 | \subsubsection*{Naming objects} 26 | \ikwd{mod\@\texttt{mod}} 27 | \ikwd{land\@\texttt{land}} 28 | \ikwd{lor\@\texttt{lor}} 29 | \ikwd{lxor\@\texttt{lxor}} 30 | \ikwd{lsl\@\texttt{lsl}} 31 | \ikwd{lsr\@\texttt{lsr}} 32 | \ikwd{asr\@\texttt{asr}} 33 | 34 | \begin{syntax} 35 | value-name: 36 | lowercase-ident 37 | | '(' operator-name ')' 38 | ; 39 | operator-name: 40 | prefix-symbol || infix-op 41 | ; 42 | infix-op: 43 | infix-symbol 44 | | '*' || '+' || '-' || '-.' || '=' || '!=' || '<' || '>' || 'or' || '||' 45 | || '&' || '&&' || ':=' 46 | | 'mod' || 'land' || 'lor' || 'lxor' || 'lsl' || 'lsr' || 'asr' 47 | ; 48 | constr-name: 49 | capitalized-ident 50 | ; 51 | tag-name: 52 | capitalized-ident 53 | ; 54 | typeconstr-name: 55 | lowercase-ident 56 | ; 57 | field-name: 58 | lowercase-ident 59 | ; 60 | module-name: 61 | capitalized-ident 62 | ; 63 | modtype-name: 64 | ident 65 | ; 66 | class-name: 67 | lowercase-ident 68 | ; 69 | inst-var-name: 70 | lowercase-ident 71 | ; 72 | method-name: 73 | lowercase-ident 74 | \end{syntax} 75 | See also the following language extension: 76 | \hyperref[s:index-operators]{extended indexing operators}. 77 | 78 | As shown above, prefix and infix symbols as well as some keywords can 79 | be used as value names, provided they are written between parentheses. 80 | The capitalization rules are summarized in the table below. 81 | 82 | \begin{tableau}{|l|l|}{Name space}{Case of first letter} 83 | \entree{Values}{lowercase} 84 | \entree{Constructors}{uppercase} 85 | \entree{Labels}{lowercase} 86 | \entree{Polymorphic variant tags}{uppercase} 87 | \entree{Exceptions}{uppercase} 88 | \entree{Type constructors}{lowercase} 89 | \entree{Record fields}{lowercase} 90 | \entree{Classes}{lowercase} 91 | \entree{Instance variables}{lowercase} 92 | \entree{Methods}{lowercase} 93 | \entree{Modules}{uppercase} 94 | \entree{Module types}{any} 95 | \end{tableau} 96 | 97 | {\it Note on polymorphic variant tags:\/} the current implementation accepts 98 | lowercase variant tags in addition to capitalized variant tags, but we 99 | suggest you avoid lowercase variant tags for portability and 100 | compatibility with future OCaml versions. 101 | 102 | \subsubsection*{Referring to named objects} 103 | 104 | \begin{syntax} 105 | value-path: 106 | [ module-path '.' ] value-name 107 | ; 108 | constr: 109 | [ module-path '.' ] constr-name 110 | ; 111 | typeconstr: 112 | [ extended-module-path '.' ] typeconstr-name 113 | ; 114 | field: 115 | [ module-path '.' ] field-name 116 | ; 117 | modtype-path: 118 | [ extended-module-path '.' ] modtype-name 119 | ; 120 | class-path: 121 | [ module-path '.' ] class-name 122 | ; 123 | classtype-path: 124 | [ extended-module-path '.' ] class-name 125 | ; 126 | module-path: 127 | module-name { '.' module-name } 128 | ; 129 | extended-module-path: 130 | extended-module-name { '.' extended-module-name } 131 | ; 132 | extended-module-name: 133 | module-name { '(' extended-module-path ')' } 134 | \end{syntax} 135 | 136 | A named object can be referred to either by its name (following the 137 | usual static scoping rules for names) or by an access path @prefix '.' name@, 138 | where @prefix@ designates a module and @name@ is the name of an object 139 | defined in that module. The first component of the path, @prefix@, is 140 | either a simple module name or an access path @name_1 '.' name_2 \ldots@, 141 | in case the defining module is itself nested inside other modules. 142 | For referring to type constructors, module types, or class types, 143 | the @prefix@ can 144 | also contain simple functor applications (as in the syntactic class 145 | @extended-module-path@ above) in case the defining module is the 146 | result of a functor application. 147 | 148 | Label names, tag names, method names and instance variable names need 149 | not be qualified: the former three are global labels, while the latter 150 | are local to a class. 151 | -------------------------------------------------------------------------------- /styles/syntaxdef.hva: -------------------------------------------------------------------------------- 1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2 | % Hevea code for syntax definitions of the ocaml manual % 3 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 4 | % Important commands 5 | % \token, for typesetting grammar terminals 6 | % \nonterm, for typesetting grammar non-terminals 7 | % 8 | % Beware: \nonterm introduces either a local anchor or a local reference 9 | % -Anchors are introduced when \nonterm occurs in the first column of 10 | % syntax definitions (environment 'syntax') 11 | % - References are introduced everywhere else 12 | % 13 | % For pure typesetting effect without links (eg. to typeset 'e' as 'expr') 14 | % use the \nt command (eg. \nt{e}). 15 | % In syntax definitions, the tool 'transf' translates @word@ into \nt{word}. 16 | % 17 | % Warnings are produced 18 | % - For references to non-defined non terminals 19 | % - For multiple definitions of the same non-terminal 20 | % Warnings can be avoided for a given non-terminal 'expr' by issuing 21 | % the command \stx@silent{'expr'} 22 | % 23 | %It is also possible to alias a nonterminal: 24 | %\stx@alias{name}{othername} 25 | %will make reference to 'name' point to the definition of non-terminal 26 | %'othername' 27 | \newif\ifspace 28 | \def\addspace{\ifspace\;\spacefalse\fi} 29 | \ifhtml 30 | \newcommand{\token}[1]{\texttt{\blue#1}} 31 | \else 32 | \newcommand{\token}[1]{\texttt{#1}} 33 | \fi 34 | %%% warnings 35 | \def\stx@warning#1#2{\@ifundefined{stx@#1@silent}{\hva@warn{#2}}{}} 36 | \def\stx@silent#1{\def\csname stx@#1@silent\endcsname{}} 37 | %%% Do not warn about those 38 | %initial example 39 | \stx@silent{like}\stx@silent{that}% 40 | %Not defined 41 | \stx@silent{regular-char}% 42 | \stx@silent{regular-string-char}% 43 | %\stx@silent{regular-char-str}% 44 | \stx@silent{lowercase-ident}% 45 | \stx@silent{capitalized-ident}% 46 | \stx@silent{space}% 47 | \stx@silent{tab}% 48 | \stx@silent{newline}% 49 | %Used in many places 50 | \stx@silent{prefix}% 51 | \stx@silent{name}% 52 | \stx@silent{xname}% 53 | %Not defined 54 | \stx@silent{external-declaration}% 55 | \stx@silent{unit-name}% 56 | %%Redefined in exten.etex 57 | \stx@silent{parameter}% 58 | \stx@silent{pattern}% 59 | \stx@silent{constr-decl}% 60 | \stx@silent{type-param}% 61 | \stx@silent{let-binding}% 62 | \stx@silent{expr}% 63 | \stx@silent{typexpr}% 64 | \stx@silent{module-expr}% 65 | \stx@silent{type-representation}% 66 | \stx@silent{definition}% 67 | \stx@silent{specification}% 68 | \stx@silent{type-equation}% 69 | \stx@silent{class-field}% 70 | \stx@silent{mod-constraint}% 71 | \stx@silent{module-type}% 72 | \stx@silent{constant}% 73 | %%Redefined in names.etex 74 | \stx@silent{label-name}% 75 | %%Not really defined in lexyacc.etex 76 | \stx@silent{character-set}% 77 | \stx@silent{symbol}% 78 | %%Not defined in debugger.etex 79 | \stx@silent{integer} 80 | %%Not defined in ocamldoc.etex 81 | \stx@silent{string} 82 | \stx@silent{id} 83 | \stx@silent{Exc} 84 | \stx@silent{URL} 85 | %%%%%%%%%%%%% 86 | %% Aliases %% 87 | %%%%%%%%%%%%% 88 | \newcommand{\stx@alias}[2]{\def\csname stx@#1@alias\endcsname{#2}} 89 | \stx@alias{typ}{typexpr}% 90 | \stx@alias{met}{method-name}% 91 | \stx@alias{tag}{tag-name}% 92 | \stx@alias{lab}{label-name}% 93 | \stx@alias{C}{constr-name} 94 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%% 95 | %%special anchor 96 | \newstyle{a.syntax:link}{color:maroon;text-decoration:underline} 97 | \newstyle{a.syntax:visited}{color:maroon;text-decoration:underline} 98 | \newstyle{a.syntax:hover}{color:black;text-decoration:none;background-color:\#FF6060} 99 | %compatibility for hevea-1.1?/heeva-2.?? 100 | \ifu\@tr@url 101 | \providecommand{\@tr@url}[1]{#1}\def\stx@id{NAME}\else 102 | \def\stx@id{id}\fi 103 | \newcommand{\@syntaxlocref}[2] 104 | {\@aelement{href="\@print{#}\@tr@url{#1}" class="syntax"}{#2}} 105 | \newcommand{\@syntaxaname}[2] 106 | {\@aelement{\stx@id="#1" class="syntax"}{#2}} 107 | %%Refer to anchor, internal : 108 | %#1 -> anchor #2 -> visible tag 109 | \def\@ref@anchor#1#2{% 110 | \@ifundefined{stx@#1@exists} 111 | {\stx@warning{#1}{Undefined non-terminal: '#1'}#2} 112 | {\@syntaxlocref{#1}{#2}}} 113 | %%Refer to anchor 114 | \def\ref@anchor#1{% 115 | \ifu\csname stx@#1@alias\endcsname 116 | \@ref@anchor{#1}{#1}\else 117 | \@ref@anchor{\csname stx@#1@alias\endcsname}{#1}\fi} 118 | \def\stx@exists#1{\def\csname stx@#1@exists\endcsname{}} 119 | %%Define anachor 120 | \def\def@anchor#1{% 121 | \@ifundefined{stx@#1} 122 | {{\@nostyle\@auxdowrite{\string\stx@exists\{#1\}}}% 123 | \gdef\csname stx@#1\endcsname{}\@syntaxaname{#1}{#1}} 124 | {\@ifundefined{stx@#1@silent} 125 | {\hva@warn{Redefinition of non-terminal '#1'}#1} 126 | {\ref@anchor{#1}}}} 127 | %%%Change \@anchor and initial definition, for html only, of course! 128 | \ifhtml 129 | \def\set@name{\let\@anchor\def@anchor} 130 | \let\@anchor\ref@anchor 131 | \else 132 | \def\set@name{} 133 | \def\@anchor{} 134 | \fi 135 | %%%Format non-terminal 136 | \def\nt#1{\textit{\maroon#1}} 137 | %%%Link for non-terminal and format 138 | \def\nonterm#1{\addspace\nt{\@anchor{#1}}\spacetrue} 139 | \def\brepet{\addspace\{} 140 | \def\erepet{\}} 141 | \def\boption{\addspace[} 142 | \def\eoption{]} 143 | \def\brepets{\addspace\{} 144 | \def\erepets{\}^+} 145 | \def\bparen{\addspace(} 146 | \def\eparen{)} 147 | \def\orelse{\mid \spacefalse} 148 | \def\is{ & ::= & \spacefalse } 149 | \def\alt{ \\ & \mid & \spacefalse } 150 | \def\sep{ \\ \\ \spacefalse } 151 | \def\cutline{} 152 | \def\emptystring{\epsilon} 153 | \def\syntax{\@open{div}{class="syntax"}$$\begin{array}{>{\set@name}rcl}\spacefalse} 154 | \def\endsyntax{\end{array}$$\@close{div}} 155 | \def\syntaxleft{\@open{div}{class="syntaxleft"}$\begin{array}{>{\set@name}rcl}\spacefalse} 156 | \def\endsyntaxleft{\end{array}$\@close{div}} 157 | \def\synt#1{$\spacefalse#1$} 158 | -------------------------------------------------------------------------------- /manual/Makefile: -------------------------------------------------------------------------------- 1 | SRC = $(abspath ../ocaml) 2 | 3 | export LD_LIBRARY_PATH ?= "$(SRC)/otherlibs/unix/:$(SRC)/otherlibs/str/" 4 | export DYLD_LIBRARY_PATH ?= "$(SRC)/otherlibs/unix/:$(SRC)/otherlibs/str/" 5 | SET_LD_PATH = CAML_LD_LIBRARY_PATH=$(LD_LIBRARY_PATH) 6 | 7 | OCAMLDOC = $(if $(wildcard $(SRC)/ocamldoc/ocamldoc.opt),\ 8 | $(SRC)/ocamldoc/ocamldoc.opt,\ 9 | $(SET_LD_PATH) $(SRC)/runtime/ocamlrun $(SRC)/ocamldoc/ocamldoc)\ 10 | -hide Stdlib -lib Stdlib -nostdlib \ 11 | -pp "$(AWK) -v ocamldoc=true -f $(SRC)/stdlib/expand_module_aliases.awk" 12 | 13 | 14 | # Import the list of mli files for the library docs 15 | include $(SRC)/ocamldoc/Makefile.docfiles 16 | 17 | 18 | 19 | TEXQUOTE = $(SRC)/runtime/ocamlrun ../tools/texquote2 20 | 21 | 22 | FILES = allfiles.tex biblio.tex foreword.tex version.tex warnings-help.etex 23 | 24 | TEXINPUTS = ".:..:../refman:../library:../cmds:../tutorials:../../styles:" 25 | RELEASE = ../release/$${RELEASENAME} 26 | HEVEA = hevea 27 | HACHA = hacha 28 | INFO_FLAGS = -fix -exec xxdate.exe -info -w 79 29 | HTML_FLAGS = -fix -exec xxdate.exe -O 30 | TEXT_FLAGS = -fix -exec xxdate.exe -text -w 79 31 | 32 | 33 | manual: files 34 | cd texstuff \ 35 | && TEXINPUTS=$(TEXINPUTS) xelatex manual.tex -interaction=nonstopmode -halt-on-error 36 | 37 | index: 38 | cd texstuff \ 39 | && sh ../../tools/fix_index.sh manual.idx \ 40 | && makeindex manual.idx \ 41 | && makeindex manual.kwd.idx 42 | 43 | 44 | # libref/style.css and comilerlibref/style.css are used as witness 45 | # for the generation of the html stdlib and compilerlibs reference. 46 | html: htmlman/libref/style.css htmlman/compilerlibref/style.css etex-files 47 | cd htmlman \ 48 | && $(HEVEA) $(HTML_FLAGS) \ 49 | -I .. -I ../cmds -I ../library -I ../refman -I ../tutorials \ 50 | -I ../../styles -I ../texstuff \ 51 | manual.hva -e macros.tex ../manual.tex \ 52 | && $(HACHA) -tocter manual.html 53 | 54 | htmlman/libref/style.css: style.css $(STDLIB_MLIS) 55 | mkdir -p htmlman/libref 56 | $(OCAMLDOC) -colorize-code -sort -html \ 57 | -d htmlman/libref \ 58 | $(DOC_STDLIB_INCLUDES) \ 59 | $(STDLIB_MLIS) 60 | cp style.css $@ 61 | 62 | COMPILERLIBS_MODULES=$(shell echo $(basename $(notdir $(COMPILERLIBS_MLIS))) \ 63 | | sed "s/\<./\U&/g") 64 | 65 | library/compiler_libs.txt: library/compiler_libs.mld 66 | cp $< $@ && echo "{!modules:$(COMPILERLIBS_MODULES)}" >> $@ 67 | 68 | 69 | htmlman/compilerlibref/style.css: library/compiler_libs.txt style.css \ 70 | $(COMPILERLIBS_MLIS) 71 | mkdir -p htmlman/compilerlibref 72 | $(OCAMLDOC) -colorize-code -sort -html \ 73 | -d htmlman/compilerlibref \ 74 | -I $(SRC)/stdlib \ 75 | $(DOC_COMPILERLIBS_INCLUDES) \ 76 | -intro library/compiler_libs.txt \ 77 | library/compiler_libs.txt \ 78 | $(COMPILERLIBS_MLIS) 79 | cp style.css $@ 80 | 81 | 82 | info: files 83 | cd infoman \ 84 | && rm -f ocaml.info* \ 85 | && $(HEVEA) $(INFO_FLAGS) -o ocaml.info.body \ 86 | -I .. -I ../cmds -I ../library -I ../refman -I ../tutorials \ 87 | -I ../../styles -I ../texstuff \ 88 | ../manual.inf -e macros.tex ../manual.tex 89 | cat manual.info.header infoman/ocaml.info.body > infoman/ocaml.info 90 | cd infoman \ 91 | && rm -f ocaml.info.tmp ocaml.info.body \ 92 | && gzip -9 ocaml.info* 93 | 94 | text: files 95 | cd textman \ 96 | && $(HEVEA) $(TEXT_FLAGS) \ 97 | -I .. -I ../cmds -I ../library -I ../refman -I ../tutorials \ 98 | -I ../../styles -I ../texstuff \ 99 | ../manual.inf -e macros.tex ../manual.tex 100 | 101 | 102 | all: 103 | $(MAKE) html text info manual 104 | $(MAKE) manual 105 | $(MAKE) index 106 | $(MAKE) manual 107 | 108 | release: all 109 | cp htmlman/manual.html $(RELEASE)refman.html 110 | rm -f htmlman/manual.{html,haux,hmanual*,htoc} 111 | tar zcf $(RELEASE)refman-html.tar.gz \ 112 | htmlman/*.* htmlman/libref htmlman/fonts 113 | zip -8 $(RELEASE)refman-html.zip \ 114 | htmlman/*.* htmlman/libref/*.* htmlman/fonts/*.* 115 | cp texstuff/manual.pdf $(RELEASE)refman.pdf 116 | cp textman/manual.txt $(RELEASE)refman.txt 117 | tar cf - infoman/ocaml.info* | gzip > $(RELEASE)refman.info.tar.gz 118 | 119 | 120 | files: $(FILES) 121 | $(MAKE) -C cmds all 122 | $(MAKE) -C library all 123 | $(MAKE) -C refman all 124 | $(MAKE) -C tutorials all 125 | 126 | etex-files: $(FILES) 127 | $(MAKE) -C cmds etex-files 128 | $(MAKE) -C library etex-files 129 | $(MAKE) -C refman etex-files 130 | $(MAKE) -C tutorials etex-files 131 | 132 | 133 | %.tex: %.etex 134 | $(TEXQUOTE) < $< > $*.texquote_error.tex 135 | mv $*.texquote_error.tex $@ 136 | 137 | version.tex: $(SRC)/VERSION 138 | sed -n -e '1s/^\([0-9]*\.[0-9]*\).*$$/\\def\\ocamlversion{\1}/p' $< > $@ 139 | 140 | warnings-help.etex: $(SRC)/utils/warnings.ml $(SRC)/ocamlc 141 | (echo "% This file is generated from (ocamlc -warn-help)";\ 142 | echo "% according to a rule in manual/manual/Makefile.";\ 143 | echo "% In particular, the reference to documentation sections";\ 144 | echo "% are inserted through the Makefile, which should be updated";\ 145 | echo "% when a new warning is documented.";\ 146 | echo "%";\ 147 | $(SET_LD_PATH) $(SRC)/boot/ocamlrun $(SRC)/ocamlc -warn-help \ 148 | | sed -e 's/^ *\([0-9A-Z][0-9]*\)\(.*\)/\\item[\1] \2/'\ 149 | ) >$@ 150 | # sed --inplace is not portable, emulate 151 | for i in 52 57; do\ 152 | sed\ 153 | s'/\\item\['$$i'\]/\\item\['$$i' (see \\ref{ss:warn'$$i'})\]/'\ 154 | $@ > $@.tmp;\ 155 | mv $@.tmp $@;\ 156 | done 157 | 158 | 159 | .PHONY: clean 160 | clean: 161 | rm -f $(FILES) *.texquote_error 162 | $(MAKE) -C cmds clean 163 | $(MAKE) -C library clean 164 | $(MAKE) -C refman clean 165 | $(MAKE) -C tutorials clean 166 | -rm -f texstuff/* 167 | cd htmlman; rm -rf libref compilerlibref index.html \ 168 | manual*.html *.haux *.hind *.svg 169 | cd textman; rm -f manual.txt *.haux *.hind 170 | cd infoman; rm -f ocaml.info ocaml.info-* *.haux *.hind 171 | -------------------------------------------------------------------------------- /styles/multicols.sty: -------------------------------------------------------------------------------- 1 | % Save file as: MULTICOLS.STY Source: FILESERV@SHSU.BITNET 2 | % multicols.sty version 1.0 3 | % Allows for multiple column typesetting 4 | % From TUGboat, voulme 10 (1989), No. 3 5 | % 6 | % Frank Mittelback 7 | % Electronic Data Systems 8 | % (Deutschland) GmbH 9 | % Eisenstrasse 56 10 | % D-6090 Russelsheim 11 | % Federal Republic of Germany 12 | % Bitnet: pzf5hz@drueds2 13 | % 14 | % Variables: 15 | % \premulticols - If the space left on the page is less than this, a new 16 | % page is started before the multiple columns. Otherwise, a \vskip 17 | % of \multicolsep is added. 18 | % \postmulticols - analogous to \premulticols 19 | % \columnseprule - the width of the rule separating the columns. 20 | % 21 | % Commands: 22 | % \raggedcolumns - don't align bottom lines of columns 23 | % \flushcolumns - align bottom lines (default) 24 | % 25 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 26 | \@ifundefined{mult@cols}{}{\endinput} 27 | 28 | \def\multicols#1{\col@number#1\relax 29 | \ifnum\col@number<\@ne 30 | \@warning{Using '\number\col@number' columns doesn't seem a good idea.^^J 31 | I therefore use two columns instead}% 32 | \col@number\tw@ \fi 33 | \@ifnextchar[\mult@cols{\mult@cols[]}} 34 | 35 | \def\mult@cols[#1]{\@ifnextchar[% 36 | {\mult@@cols{#1}}% 37 | {\mult@@cols{#1}[\premulticols]}} 38 | 39 | \def\mult@@cols#1[#2]{% 40 | \enough@room#2% 41 | #1\par\addvspace\multicolsep 42 | \begingroup 43 | \prepare@multicols\ignorespaces} 44 | 45 | \def\enough@room#1{\par \penalty\z@ 46 | \page@free \pagegoal 47 | \advance \page@free -\pagetotal 48 | \ifdim \page@free <#1\newpage \fi} 49 | 50 | \def\prepare@multicols{% 51 | \output{\global\setbox\partial@page 52 | \vbox{\unvbox\@cclv}}\eject 53 | \vbadness9999 \hbadness5000 54 | \tolerance\multicoltolerance 55 | \doublecol@number\col@number 56 | \multiply\doublecol@number\tw@ 57 | \advance\baselineskip\multicolbaselineskip 58 | \advance\@colroom-\ht\partial@page 59 | \vsize\col@number\@colroom 60 | \advance\vsize\c@collectmore\baselineskip 61 | \hsize\columnwidth \advance\hsize\columnsep 62 | \advance\hsize-\col@number\columnsep 63 | \divide\hsize\col@number 64 | \linewidth\hsize 65 | \output{\multi@columnout}% 66 | \multiply\count\footins\col@number 67 | \multiply\skip \footins\col@number 68 | \reinsert@footnotes} 69 | 70 | \def\endmulticols{\par\penalty\z@ 71 | \output{\balance@columns}\eject 72 | \endgroup \reinsert@footnotes 73 | \global\c@unbalance\z@ 74 | \enough@room\postmulticols 75 | \addvspace\multicolsep} 76 | 77 | \newcount\c@unbalance \c@unbalance = 0 78 | \newcount\c@collectmore \c@collectmore = 0 79 | \newcount\col@number 80 | \newcount\doublecol@number 81 | \newcount\multicoltolerance \multicoltolerance = 9999 82 | \newdimen\page@free 83 | \newdimen\premulticols \premulticols = 50pt 84 | \newdimen\postmulticols \postmulticols = 20pt 85 | \newskip\multicolsep \multicolsep = 12pt plus 4pt minus 3pt 86 | \newskip\multicolbaselineskip \multicolbaselineskip=0pt 87 | \newbox\partial@page 88 | 89 | \def\process@cols#1#2{\count@#1\relax 90 | \loop #2% 91 | \advance\count@\tw@ 92 | \ifnum\count@<\doublecol@number 93 | \repeat} 94 | 95 | \def\page@sofar{\unvbox\partial@page 96 | \process@cols\z@{\wd\count@\hsize}% 97 | \hbox to\textwidth{% 98 | \process@cols\tw@{\box\count@ 99 | \hss\vrule\@width\columnseprule\hss}% 100 | \box\z@}} 101 | 102 | \def\reinsert@footnotes{\ifvoid\footins\else 103 | \insert\footins{\unvbox\footins}\fi} 104 | 105 | \def\multi@columnout{% 106 | \ifnum\outputpenalty <-\@Mi 107 | \speci@ls \else 108 | \splittopskip\topskip 109 | \splitmaxdepth\maxdepth 110 | \dimen@\@colroom 111 | \divide\skip\footins\col@number 112 | \ifvoid\footins \else 113 | \advance\dimen@-\skip\footins 114 | \advance\dimen@-\ht\footins \fi 115 | \process@cols\tw@{\setbox\count@ 116 | \vsplit\@cclv to\dimen@}% 117 | \setbox\z@\vsplit\@cclv to\dimen@ 118 | \ifvoid\@cclv \else 119 | \unvbox\@cclv 120 | \penalty\outputpenalty 121 | \fi 122 | \setbox\@cclv\vbox{\page@sofar}% 123 | \@makecol\@outputpage 124 | \global\@colroom\@colht 125 | \process@deferreds 126 | \global\vsize\col@number\@colroom 127 | \global\advance\vsize 128 | \c@collectmore\baselineskip 129 | \multiply\skip\footins\col@number\fi} 130 | 131 | \def\speci@ls{% 132 | \typeout{floats and marginpars not allowed inside `multicols' environment}% 133 | \unvbox\@cclv\reinsert@footnotes 134 | \gdef\@currlist{}} 135 | 136 | \def\process@deferreds{% 137 | \@floatplacement 138 | \begingroup 139 | \let\@tempb\@deferlist 140 | \gdef\@deferlist{}% 141 | \let\@elt\@scolelt 142 | \@tempb \endgroup} 143 | 144 | \newif\ifshr@nking 145 | 146 | \def\raggedcolumns{% 147 | \@bsphack\shr@nkingtrue\@esphack} 148 | \def\flushcolumns{% 149 | \@bsphack\shr@nkingfale\@esphack} 150 | 151 | \def\balance@columns{% 152 | \splittopskip\topskip 153 | \splitmaxdepth\maxdepth 154 | \setbox\z@\vbox{\unvbox\@cclv}\dimen@\ht\z@ 155 | \advance\dimen@\col@number\topskip 156 | \advance\dimen@-\col@number\baselineskip 157 | \divide\dimen@\col@number 158 | \advance\dimen@\c@unbalance\baselineskip 159 | {\vbadness\@M \loop 160 | {\process@cols\@ne{\global\setbox\count@\box\voidb@x}}% 161 | \global\setbox\@ne\copy\z@ 162 | {\process@cols\thr@@{\global\setbox\count@\vsplit\@ne to\dimen@}}% 163 | \ifshr@nking \global\setbox\thr@@\vbox{\unvbox\thr@@}% 164 | \fi 165 | \ifdim\ht\@ne >\ht\thr@@ 166 | \global\advance\dimen@\p@ 167 | \repeat}% 168 | \dimen@\ht\thr@@ 169 | \process@cols\z@{\@tempcnta\count@ 170 | \advance\@tempcnta\@ne 171 | \setbox\count@\vtop to\dimen@ 172 | {\unvbox\@tempcnta 173 | \ifshr@nking\vfill\fi}}% 174 | \global\vsize\@colroom 175 | \global\advance\vsize\ht\partial@page 176 | \page@sofar} 177 | -------------------------------------------------------------------------------- /manual/cmds/spacetime.etex: -------------------------------------------------------------------------------- 1 | \chapter{Memory profiling with Spacetime} 2 | %HEVEA\cutname{spacetime.html} 3 | 4 | \section{Overview} 5 | 6 | Spacetime is the name given to functionality within the OCaml compiler that 7 | provides for accurate profiling of the memory behaviour of a program. 8 | Using Spacetime it is possible to determine the source of memory leaks 9 | and excess memory allocation quickly and easily. Excess allocation slows 10 | programs down both by imposing a higher load on the garbage collector and 11 | reducing the cache locality of the program's code. Spacetime provides 12 | full backtraces for every allocation that occurred on the OCaml heap 13 | during the lifetime of the program including those in C stubs. 14 | 15 | Spacetime only analyses the memory behaviour of a program with respect to 16 | the OCaml heap allocators and garbage collector. It does not analyse 17 | allocation on the C heap. Spacetime does not affect the memory behaviour 18 | of a program being profiled with the exception of any change caused by the 19 | overhead of profiling (see section\ \ref{runtimeoverhead})---for example 20 | the program running slower might cause it to allocate less memory in total. 21 | 22 | Spacetime is currently only available for x86-64 targets and has only been 23 | tested on Linux systems (although it is expected to work on most modern 24 | Unix-like systems and provision has been made for running under 25 | Windows). It is expected that the set of supported platforms will 26 | be extended in the future. 27 | 28 | \section{How to use it} 29 | 30 | \subsection{Building} 31 | 32 | To use Spacetime it is necessary to use an OCaml compiler that was 33 | configured with the {\tt -spacetime} option. It is not possible to select 34 | Spacetime on a per-source-file basis or for a subset of files in a project; 35 | all files involved in the executable being profiled must be built with the 36 | Spacetime compiler. Only native code compilation is supported (not 37 | bytecode). 38 | 39 | If the {\tt libunwind} library is not available on the system then it will 40 | not be possible for Spacetime to profile allocations occurring within 41 | C stubs. If the {\tt libunwind} library is available but in an unusual 42 | location then that location may be specified to the {\tt configure} script 43 | using the {\tt -libunwinddir} option (or alternatively, using separate 44 | {\tt -libunwindinclude} and {\tt -libunwindlib} options). 45 | 46 | OPAM switches will be provided for Spacetime-configured compilers. 47 | 48 | Once the appropriate compiler has been selected the program should be 49 | built as normal (ensuring that all files are built with the Spacetime 50 | compiler---there is currently no protection to ensure this is the case, but 51 | it is essential). For many uses it will not be necessary to change the 52 | code of the program to use the profiler. 53 | 54 | Spacetime-configured compilers run slower and occupy more memory than their 55 | counterparts. It is hoped this will be fixed in the future as part of 56 | improved cross compilation support. 57 | 58 | \subsection{Running} 59 | 60 | Programs built with Spacetime instrumentation have a dependency on 61 | the {\tt libunwind} library unless that was unavailable at configure time or 62 | the {\tt -disable-libunwind} option was specified 63 | (see section\ \ref{runtimeoverhead}). 64 | 65 | Setting the {\tt OCAML\_SPACETIME\_INTERVAL} environment variable to an 66 | integer representing a number of milliseconds before running a program built 67 | with Spacetime will cause memory profiling to be in operation when the 68 | program is started. The contents of the OCaml heap will be sampled each 69 | time the number of milliseconds that the program has spent executing since the 70 | last sample exceeds the given number. (Note that the time base is combined 71 | user plus system time---{\em not} wall clock time. This peculiarity may be 72 | changed in future.) 73 | 74 | The program being profiled must exit normally or be caused to exit using 75 | the {\tt SIGINT} signal (e.g. by pressing Ctrl+C). When the program exits 76 | files will be written in the directory that was the working directory when 77 | the program was started. One Spacetime file will be written for each 78 | process that was involved, indexed by process ID; there will normally only 79 | be one such. The Spacetime files may be substantial. The directory to which 80 | they are written may be overridden by setting 81 | the {\tt OCAML\_SPACETIME\_SNAPSHOT\_DIR} environment variable before the 82 | program is started. 83 | 84 | Instead of using the automatic snapshot facility described above it is also 85 | possible to manually control Spacetime profiling. (The environment variables 86 | {\tt OCAML\_SPACETIME\_INTERVAL} and {\tt OCAML\_SPACETIME\_SNAPSHOT\_DIR} 87 | are then not relevant.) Full documentation as regards this method of profiling 88 | is provided in the standard library documentation (section\ \ref{c:stdlib}) 89 | for the {\tt Spacetime} module. 90 | 91 | \subsection{Analysis} 92 | 93 | The compiler distribution does not itself provide the facility for analysing 94 | Spacetime output files; this is left to external tools. The first such tool 95 | will appear in OPAM as a package called {\tt prof_spacetime}. That tool will 96 | provide interactive graphical and terminal-based visualisation of 97 | the results of profiling. 98 | 99 | \section{Runtime overhead}\label{runtimeoverhead} 100 | 101 | The runtime overhead imposed by Spacetime varies considerably depending on 102 | the particular program being profiled. The overhead may be as low as 103 | ten percent---but more usually programs should be expected to run at perhaps 104 | a third or quarter of their normal speed. It is expected that this overhead 105 | will be reduced in future versions of the compiler. 106 | 107 | Execution speed of instrumented programs may be increased by using a compiler 108 | configured with the {\tt -disable-libunwind} option. This prevents collection 109 | of profiling information from C stubs. 110 | 111 | Programs running with Spacetime instrumentation consume significantly more 112 | memory than their non-instrumented counterparts. It is expected that this 113 | memory overhead will also be reduced in the future. 114 | 115 | \section{For developers} 116 | 117 | The compiler distribution provides an ``{\tt otherlibs}'' library called 118 | {\tt raw\_spacetime\_lib} for decoding Spacetime files. This library 119 | provides facilities to read not only memory profiling information but also 120 | the full dynamic call graph of the profiled program which is written into 121 | Spacetime output files. 122 | 123 | A library package {\tt spacetime\_lib} will be provided in OPAM 124 | to provide an interface for decoding profiling information at a higher 125 | level than that provided by {\tt raw\_spacetime\_lib}. 126 | -------------------------------------------------------------------------------- /manual/macros.hva: -------------------------------------------------------------------------------- 1 | % Colors for links 2 | \def\visited@color{\#0d46a3} 3 | \def\link@color{\#4286f4} 4 | \def\hover@color{\@getstylecolor{subsection}} 5 | \newstyle{a:link}{color:\link@color;text-decoration:underline;} 6 | \newstyle{a:visited}{color:\visited@color;text-decoration:underline;} 7 | \newstyle{a:hover}{color:black;text-decoration:underline;background-color:\hover@color} 8 | 9 | 10 | \newstyle{@media all}{@font-face \{ 11 | /* fira-sans-regular - latin */ 12 | font-family: 'Fira Sans'; 13 | font-style: normal; 14 | font-weight: 400; 15 | src: url('fonts/fira-sans-v8-latin-regular.eot'); /* IE9 Compat Modes */ 16 | src: local('Fira Sans Regular'), local('FiraSans-Regular'), 17 | url('fonts/fira-sans-v8-latin-regular.eot?\#iefix') format('embedded-opentype'), /* IE6-IE8 */ 18 | url('fonts/fira-sans-v8-latin-regular.woff2') format('woff2'), /* Super Modern Browsers */ 19 | url('fonts/fira-sans-v8-latin-regular.woff') format('woff'), /* Modern Browsers */ 20 | url('fonts/fira-sans-v8-latin-regular.ttf') format('truetype'), /* Safari, Android, iOS */ 21 | url('fonts/fira-sans-v8-latin-regular.svg\#FiraSans') format('svg'); /* Legacy iOS */ 22 | \}} 23 | 24 | % Compact layout 25 | \newstyle{body}{ 26 | max-width:750px; 27 | width: 85\%; 28 | margin: auto; 29 | background: \#f7f7f7; 30 | margin-top: 80px; 31 | font-size: 1rem; 32 | } 33 | 34 | % selects the index's title 35 | \newstyle{.maintitle}{ 36 | font-family: "Fira Sans", sans-serif; 37 | text-align: center; 38 | } 39 | 40 | \newstyle{h1, h2, h3}{ 41 | font-family: "Fira Sans", sans-serif; 42 | font-weight: normal; 43 | border-bottom: 1px solid black; 44 | } 45 | 46 | \newstyle{pre}{ 47 | font-size: 1rem; 48 | background: beige; 49 | border: 1px solid grey; 50 | padding: 10px; 51 | overflow-y:auto; 52 | white-space: pre-wrap; 53 | } 54 | 55 | % More spacing between lines and inside tables 56 | \newstyle{p,ul}{line-height:1.3em} 57 | \newstyle{.cellpadding1 tr td}{padding:1px 4px} 58 | 59 | %Styles for caml-example and friends 60 | \newstyle{div.caml-output}{color:maroon;} 61 | \newstyle{div.caml-example pre}{margin:2ex 0px;} 62 | % Styles for toplevel mode only 63 | \newstyle{div.caml-example.toplevel div.caml-input::before} 64 | {content:"\#"; color:black;} 65 | \newstyle{div.caml-example.toplevel div.caml-input}{color:\#006000;} 66 | %%% 67 | \newcommand{\input@color}{\htmlcolor{006000}} 68 | \newcommand{\output@color}{\maroon} 69 | \newcommand{\machine}{\tt} 70 | \newenvironment{machineenv}{\begin{alltt}}{\end{alltt}} 71 | \newcommand{\firstline}{\ } 72 | \newcommand{\examplespace}{\ } 73 | \newcommand{\nextline}{\examplespace\ } 74 | \newcommand{\@zyva}{\firstline\renewcommand{\?}{\nextline}} 75 | \let\?=\@zyva 76 | \newenvironment{camlunder}{\@style{U}}{} 77 | \newcommand{\caml}{\begin{alltt}\renewcommand{\;}{}\renewcommand{\\}{\char92}\def\<{\begin{camlunder}}\def\>{\end{camlunder}}\activebracefalse} 78 | \newcommand{\endcaml}{\activebracetrue\end{alltt} 79 | } 80 | \renewcommand{\:}{\renewcommand{\?}{\@zyva}} 81 | \newcommand{\var}[1]{\textit{#1}} 82 | 83 | % Caml-example environment 84 | \newcommand{\camlexample}[1]{ 85 | \ifthenelse{\equal{#1}{toplevel}} 86 | {\renewcommand{\examplespace}{\ }} 87 | {\renewcommand{\examplespace}{}} 88 | \fi 89 | \@open{div}{class="caml-example #1"} 90 | } 91 | \newcommand{\endcamlexample}{ 92 | \@close{div} 93 | \renewcommand{\examplespace}{\ } 94 | } 95 | 96 | \newcommand{\camlinput}{\@open{div}{class="caml-input"}} 97 | \newcommand{\endcamlinput}{\@close{div}} 98 | \newcommand{\camloutput}{\@open{div}{class="caml-output ok"}} 99 | \newcommand{\endcamloutput}{\@close{div}} 100 | \newcommand{\camlerror}{\@open{div}{class="caml-output error"}} 101 | \newcommand{\endcamlerror}{\@close{div}} 102 | \newcommand{\camlwarn}{\@open{div}{class="caml-output warn"}} 103 | \newcommand{\endcamlwarn}{\@close{div}} 104 | 105 | \newenvironment{library}{}{} 106 | \newcounter{page} 107 | \newenvironment{comment}{\begin{quote}}{\end{quote}} 108 | \newcommand{\nth}[2]{\({#1}_{#2}\)} 109 | \newenvironment{options}{\begin{description}}{\end{description}} 110 | 111 | 112 | %%venant de macros.tex 113 | 114 | \def\versionspecific#1{\begin{quote}\textsf{#1:}\quad} 115 | \def\unix{\versionspecific{Unix}} 116 | \def\endunix{\end{quote}} 117 | \def\macos{\versionspecific{MacOS~9}} 118 | \def\endmacos{\end{quote}} 119 | \def\windows{\versionspecific{Windows}} 120 | \def\endwindows{\end{quote}} 121 | 122 | \def\requirements{\trivlist \item[\hskip\labelsep {\bf Requirements.}]} 123 | \def\endrequirements{\endtrivlist} 124 | \def\installation{\trivlist \item[\hskip\labelsep {\bf Installation.}]} 125 | \def\endinstallation{\endtrivlist} 126 | \def\troubleshooting{\trivlist \item[\hskip\labelsep {\bf Troubleshooting.}]} 127 | \def\endtroubleshooting{\endtrivlist} 128 | 129 | \newtheorem{gcrule}{Rule} 130 | 131 | % Pour les tables de priorites et autres tableaux a deux colonnes, encadres 132 | 133 | \def\entree#1#2{#1 & #2 \\} 134 | \def\tableau#1#2#3{% 135 | \par 136 | \@open{div}{class="tableau"} 137 | \begin{center}% 138 | \begin{tabular*}{.8\linewidth}{#1}% 139 | \multicolumn{1}{c}{\textbf{#2}} & 140 | \multicolumn{1}{c}{\textbf{#3}} \\ 141 | %%#2 & #3 \\% 142 | }% 143 | \def\endtableau{\end{tabular*}\end{center}\@close{div}\par} 144 | 145 | \newstyle{.tableau, .syntax, .syntaxleft}{ 146 | /* same width as body */ 147 | max-width: 750px; 148 | overflow-y: auto; 149 | } 150 | 151 | % L'environnement library (pour composer les descriptions des modules 152 | % de bibliotheque). 153 | 154 | 155 | \def\restoreindent{\begingroup\let\@listI=\@savedlistI} 156 | \def\endrestoreindent{\endgroup} 157 | 158 | 159 | % PDF stuff 160 | 161 | \def\pdfchapterfold#1#2{} 162 | \def\pdfsection#1{} 163 | \def\pdfchapter{\pdfchapterfold{0}} 164 | 165 | %%% Pour camlidl 166 | 167 | \def\transl#1{$[\![\mbox{#1}]\!]$} 168 | 169 | % Pour l'index 170 | \usepackage{multind} 171 | \let\indexentry=\index 172 | \renewcommand{\index}[1]{\indexentry{\jobname}{#1}} 173 | \def\ikwd#1{\indexentry{\jobname.kwd}{#1}} 174 | % nth 175 | 176 | \def\th{^{\mbox{\scriptsize th}}} 177 | \renewcommand{\hbox}[1]{\mbox{#1}} 178 | 179 | % Notations pour les metavariables 180 | \def\nmth#1#2#3{\({#1}_{#2}^{#3}\)} 181 | \def\optvar#1{[\var{#1}\/]} 182 | \def\event{§§} 183 | \def\fromoneto#1#2{$#1 = 1,\ldots{} , #2$} 184 | 185 | \newcommand{\vfill}{} 186 | \def\number{} 187 | \def\year{2013} 188 | 189 | % Pour alltt 190 | \def\rminalltt#1{{\rm #1}} 191 | \def\goodbreak{\ \\} 192 | \def\@savedlistI{} 193 | 194 | %List of links with no space around items 195 | \newstyle{.li-links}{margin:0ex 0ex;} 196 | \newenvironment{links} 197 | {\setenvclass{itemize}{ftoc2}\setenvclass{li-itemize}{li-links}\itemize} 198 | {\enditemize} 199 | 200 | \newenvironment{maintitle}{\@open{div}{class="maintitle"}}{\@close{div}} 201 | -------------------------------------------------------------------------------- /manual/macros.tex: -------------------------------------------------------------------------------- 1 | \makeatletter 2 | % Pour hevea 3 | \newif\ifouthtml\outhtmlfalse 4 | \newcommand{\cutname}[1]{} 5 | % Notations pour les metavariables 6 | \def\var#1{{\it#1}} 7 | \def\nth#1#2{${\it#1}_{#2}$} 8 | \def\nmth#1#2#3{${\it#1}_{#2}^{#3}$} 9 | \def\optvar#1{\textrm{[}\var{#1}\/\textrm{]}} 10 | \def\event{$\bowtie$} 11 | \def\fromoneto#1#2{$#1 = 1, \ldots, #2$} 12 | 13 | % Numerotation 14 | \setcounter{secnumdepth}{2} % Pour numeroter les \subsection 15 | \setcounter{tocdepth}{1} % Pour ne pas mettre les \subsection 16 | % dans la table des matieres 17 | 18 | % Pour avoir "_" qui marche en mode math et en mode normal 19 | \catcode`\_=13 20 | \catcode`\=8 21 | \def\_{\hbox{\tt\char95}} 22 | \def_{\ifmmode\else\_\fi} 23 | 24 | \def\ttstretch{\tt\spaceskip=5.77pt plus 1.83pt minus 1.22pt} 25 | % La fonte cmr10 a normalement des espaces de 5.25pt non extensibles. 26 | % En 11 pt ca fait 5.77 pt. On lui ajoute la meme flexibilite que 27 | % cmr10 agrandie a 11 pt. 28 | 29 | % Pour la traduction "xxxx" -> {\machine{xxxx}} faite par texquote2 30 | \def\machine#1{\mbox{\ttstretch{#1}}} 31 | 32 | % Pour la traduction "\begin{verbatim}...\end{verbatim}" 33 | % -> "\begin{machineenv}...\end{machineenv}" 34 | % faite aussi par texquote2. 35 | \newenvironment{machineenv}{\alltt}{\endalltt} 36 | 37 | % Environnements 38 | 39 | \newlength{\versionwidth} 40 | \setbox0=\hbox{\bf Windows:} \setlength{\versionwidth}{\wd0} 41 | 42 | \def\versionspecific#1{ 43 | \begin{description}\item[#1:]~\\} 44 | 45 | \def\unix{\versionspecific{Unix}} 46 | \def\endunix{\end{description}} 47 | %\def\macos{\versionspecific{MacOS 9}} 48 | %\def\endmacos{\end{description}} 49 | \def\windows{\versionspecific{Windows}} 50 | \def\endwindows{\end{description}} 51 | 52 | \def\requirements{\trivlist \item[\hskip\labelsep {\bf Requirements.}]} 53 | \def\endrequirements{\endtrivlist} 54 | \def\installation{\trivlist \item[\hskip\labelsep {\bf Installation.}]} 55 | \def\endinstallation{\endtrivlist} 56 | \def\troubleshooting{\trivlist \item[\hskip\labelsep {\bf Troubleshooting.}]} 57 | \def\endtroubleshooting{\endtrivlist} 58 | 59 | \newtheorem{gcrule}{Rule} 60 | 61 | % Pour les tables de priorites et autres tableaux a deux colonnes, encadres 62 | 63 | \def\tableau#1#2#3{% 64 | \begin{center} 65 | \begin{tabular}{#1} 66 | \hline 67 | #2 & #3 \\ 68 | \hline 69 | } 70 | \def\endtableau{\hline\end{tabular}\end{center}} 71 | \def\entree#1#2{#1 & #2 \\} 72 | 73 | % L'environnement option 74 | 75 | \def\optionitem[#1]{\if@noparitem \@donoparitem 76 | \else \if@inlabel \indent \par \fi 77 | \ifhmode \unskip\unskip \par \fi 78 | \if@newlist \if@nobreak \@nbitem \else 79 | \addpenalty\@beginparpenalty 80 | \addvspace\@topsep \addvspace{-\parskip}\fi 81 | \else \addpenalty\@itempenalty \addvspace\itemsep 82 | \fi 83 | \global\@inlabeltrue 84 | \fi 85 | \everypar{\global\@minipagefalse\global\@newlistfalse 86 | \if@inlabel\global\@inlabelfalse \hskip -\parindent \box\@labels 87 | \penalty\z@ \fi 88 | \everypar{}}\global\@nobreakfalse 89 | \if@noitemarg \@noitemargfalse \if@nmbrlist \refstepcounter{\@listctr}\fi \fi 90 | \setbox\@tempboxa\hbox{\makelabel{#1}}% 91 | \global\setbox\@labels 92 | \ifdim \wd\@tempboxa >\labelwidth 93 | \hbox{\unhbox\@labels 94 | \hskip -\leftmargin 95 | \box\@tempboxa}\hfil\break 96 | \else 97 | \hbox{\unhbox\@labels 98 | \hskip -\leftmargin 99 | \hbox to\leftmargin {\makelabel{#1}\hfil}} 100 | \fi 101 | \ignorespaces} 102 | 103 | \def\optionlabel#1{\bf #1} 104 | \def\options{\list{}{\let\makelabel\optionlabel\let\@item\optionitem}} 105 | \def\endoptions{\endlist} 106 | 107 | % L'environnement library (pour composer les descriptions des modules 108 | % de bibliotheque). 109 | 110 | \def\comment{\penalty200\list{}{}\item[]} 111 | \def\endcomment{\endlist\penalty-100} 112 | 113 | \def\library{ 114 | \begingroup 115 | \raggedright 116 | \let\@savedlistI=\@listI% 117 | \def\@listI{\leftmargin\leftmargini\parsep 0pt plus 1pt\topsep 0pt plus 2pt}% 118 | \itemsep 0pt 119 | \topsep 0pt plus 2pt 120 | \partopsep 0pt 121 | } 122 | 123 | \def\endlibrary{ 124 | \endgroup 125 | } 126 | 127 | \def\restoreindent{\begingroup\let\@listI=\@savedlistI} 128 | \def\endrestoreindent{\endgroup} 129 | 130 | % ^^A...^^A: compose l'interieur en \tt, comme \verb 131 | 132 | \catcode`\^^A=\active 133 | \def{% 134 | \begingroup\catcode``=13\@noligs\ttstretch\let\do\@makeother\dospecials% 135 | \def\@xobeysp{\leavevmode\penalty100\ }% 136 | \@vobeyspaces\frenchspacing\catcode`\^^A=\active\def{\endgroup}} 137 | 138 | % Pour l'index 139 | 140 | \let\indexentry=\index 141 | \def\index{\indexentry{\jobname}} 142 | \def\ikwd{\indexentry{\jobname.kwd}} 143 | 144 | % Les en-tetes personnalises 145 | 146 | \pagestyle{myheadings} 147 | \def\partmark#1{\markboth{Part \thepart. \ #1}{}} 148 | \def\chaptermark#1{\markright{Chapter \thechapter. \ #1}} 149 | 150 | % nth 151 | 152 | \def\th{^{\hbox{\scriptsize th}}} 153 | 154 | % Pour annuler l'espacement vertical qui suit un "verbatim" 155 | \def\cancelverbatim{\vspace{-\topsep}\vspace{-\parskip}}% exact. 156 | 157 | % Pour annuler l'espacement vertical entre deux \item consecutifs dans \options 158 | \def\cancelitemspace{\vspace{-8mm}}% determine empiriquement 159 | 160 | % Pour faire la cesure apres _ dans les identificateurs 161 | \def\={\discretionary{}{}{}} 162 | \def\cuthere{\discretionary{}{}{}} 163 | 164 | % Pour la coupure en petits documents 165 | 166 | \let\mysection=\section 167 | 168 | %%% Augmenter l'espace entre numero de section 169 | % et nom de section dans la table des matieres. 170 | 171 | \def\l@section{\@dottedtocline{1}{1.5em}{2.8em}} % D'origine: 2.3 172 | 173 | % Pour alltt 174 | 175 | \def\rminalltt#1{{\rm #1}} 176 | 177 | % redefinition de l'environnement alltt pour que les {} \ et % soient 178 | % dans la bonne fonte 179 | 180 | \let\@oldalltt=\alltt 181 | \let\@oldendalltt=\endalltt 182 | \renewenvironment{alltt}{% 183 | \begingroup% 184 | \renewcommand{\{}{\char`\{}% 185 | \renewcommand{\}}{\char`\}}% 186 | \renewcommand{\\}{\char`\\}% 187 | \renewcommand{\%}{\char`\%}% 188 | \@oldalltt% 189 | }{% 190 | \@oldendalltt% 191 | \endgroup% 192 | } 193 | 194 | % Index stuff -- cf multind.sty 195 | 196 | \def\printindex#1#2{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi 197 | \columnseprule \z@ \columnsep 35pt 198 | \newpage \phantomsection \twocolumn[{\Large\bf #2 \vskip4ex}] 199 | \markright{\uppercase{#2}} 200 | \addcontentsline{toc}{chapter}{#2} 201 | \@input{#1.ind}} 202 | 203 | %%% Pour les references des modules 204 | \newcommand{\moduleref}[1]{\ref{#1}} 205 | %%% Fin des hacks 206 | 207 | \newenvironment{maintitle}{\begin{center}}{\end{center}} 208 | 209 | \makeatother 210 | -------------------------------------------------------------------------------- /manual/cmds/profil.etex: -------------------------------------------------------------------------------- 1 | \chapter{Profiling (ocamlprof)} \label{c:profiler} 2 | %HEVEA\cutname{profil.html} 3 | 4 | This chapter describes how the execution of OCaml 5 | programs can be profiled, by recording how many times functions are 6 | called, branches of conditionals are taken, \ldots 7 | 8 | \section{Compiling for profiling} 9 | 10 | Before profiling an execution, the program must be compiled in 11 | profiling mode, using the "ocamlcp" front-end to the "ocamlc" compiler 12 | (see chapter~\ref{c:camlc}) or the "ocamloptp" front-end to the 13 | "ocamlopt" compiler (see chapter~\ref{c:nativecomp}). When compiling 14 | modules separately, "ocamlcp" or "ocamloptp" must be used when 15 | compiling the modules (production of ".cmo" or ".cmx" files), and can 16 | also be used (though this is not strictly necessary) when linking them 17 | together. 18 | 19 | \paragraph{Note} If a module (".ml" file) doesn't have a corresponding 20 | interface (".mli" file), then compiling it with "ocamlcp" will produce 21 | object files (".cmi" and ".cmo") that are not compatible with the ones 22 | produced by "ocamlc", which may lead to problems (if the ".cmi" or 23 | ".cmo" is still around) when switching between profiling and 24 | non-profiling compilations. To avoid this problem, you should always 25 | have a ".mli" file for each ".ml" file. The same problem exists with 26 | "ocamloptp". 27 | 28 | \paragraph{Note} To make sure your programs can be compiled in 29 | profiling mode, avoid using any identifier that begins with 30 | "__ocaml_prof". 31 | 32 | The amount of profiling information can be controlled through the "-P" 33 | option to "ocamlcp" or "ocamloptp", followed by one or several letters 34 | indicating which parts of the program should be profiled: 35 | 36 | %% description des options 37 | \begin{options} 38 | \item["a"] all options 39 | \item["f"] function calls : a count point is set at the beginning of 40 | each function body 41 | \item["i"] {\bf if \ldots then \ldots else \ldots} : count points are set in 42 | both {\bf then} branch and {\bf else} branch 43 | \item["l"] {\bf while, for} loops: a count point is set at the beginning of 44 | the loop body 45 | \item["m"] {\bf match} branches: a count point is set at the beginning of the 46 | body of each branch 47 | \item["t"] {\bf try \ldots with \ldots} branches: a count point is set at the 48 | beginning of the body of each branch 49 | \end{options} 50 | 51 | For instance, compiling with "ocamlcp -P film" profiles function calls, 52 | if\ldots then\ldots else\ldots, loops and pattern matching. 53 | 54 | Calling "ocamlcp" or "ocamloptp" without the "-P" option defaults to 55 | "-P fm", meaning that only function calls and pattern matching are 56 | profiled. 57 | 58 | \paragraph{Note} For compatibility with previous releases, "ocamlcp" 59 | also accepts the "-p" option, with the same arguments and behaviour as 60 | "-P". 61 | 62 | The "ocamlcp" and "ocamloptp" commands also accept all the options of 63 | the corresponding "ocamlc" or "ocamlopt" compiler, except the "-pp" 64 | (preprocessing) option. 65 | 66 | 67 | \section{Profiling an execution} 68 | 69 | Running an executable that has been compiled with "ocamlcp" or 70 | "ocamloptp" records the execution counts for the specified parts of 71 | the program and saves them in a file called "ocamlprof.dump" in the 72 | current directory. 73 | 74 | If the environment variable "OCAMLPROF_DUMP" is set when the program 75 | exits, its value is used as the file name instead of "ocamlprof.dump". 76 | 77 | The dump file is written only if the program terminates 78 | normally (by calling "exit" or by falling through). It is not written 79 | if the program terminates with an uncaught exception. 80 | 81 | If a compatible dump file already exists in the current directory, then the 82 | profiling information is accumulated in this dump file. This allows, for 83 | instance, the profiling of several executions of a program on 84 | different inputs. Note that dump files produced by byte-code 85 | executables (compiled with "ocamlcp") are compatible with the dump 86 | files produced by native executables (compiled with "ocamloptp"). 87 | 88 | \section{Printing profiling information} 89 | 90 | The "ocamlprof" command produces a source listing of the program modules 91 | where execution counts have been inserted as comments. For instance, 92 | \begin{verbatim} 93 | ocamlprof foo.ml 94 | \end{verbatim} 95 | prints the source code for the "foo" module, with comments indicating 96 | how many times the functions in this module have been called. Naturally, 97 | this information is accurate only if the source file has not been modified 98 | after it was compiled. 99 | 100 | The following options are recognized by "ocamlprof": 101 | 102 | \begin{options} 103 | 104 | \item["-args" \var{filename}] 105 | Read additional newline-terminated command line arguments from \var{filename}. 106 | 107 | \item["-args0" \var{filename}] 108 | Read additional null character terminated command line arguments from \var{filename}. 109 | 110 | \item["-f" \var{dumpfile}] 111 | Specifies an alternate dump file of profiling information to be read. 112 | 113 | \item["-F" \var{string}] 114 | Specifies an additional string to be output with profiling information. 115 | By default, "ocamlprof" will annotate programs with comments of the form 116 | {\tt (* \var{n} *)} where \var{n} is the counter value for a profiling 117 | point. With option {\tt -F \var{s}}, the annotation will be 118 | {\tt (* \var{s}\var{n} *)}. 119 | 120 | \item["-impl" \var{filename}] 121 | Process the file \var{filename} as an implementation file, even if its 122 | extension is not ".ml". 123 | 124 | \item["-intf" \var{filename}] 125 | Process the file \var{filename} as an interface file, even if its 126 | extension is not ".mli". 127 | 128 | \item["-version"] 129 | Print version string and exit. 130 | 131 | \item["-vnum"] 132 | Print short version number and exit. 133 | 134 | \item["-help" or "--help"] 135 | Display a short usage summary and exit. 136 | % 137 | \end{options} 138 | 139 | \section{Time profiling} 140 | 141 | Profiling with "ocamlprof" only records execution counts, not the actual 142 | time spent within each function. There is currently no way to perform 143 | time profiling on bytecode programs generated by "ocamlc". 144 | 145 | Native-code programs generated by "ocamlopt" can be profiled for time 146 | and execution counts using the "-p" option and the standard Unix 147 | profiler "gprof". Just add the "-p" option when compiling and linking 148 | the program: 149 | \begin{alltt} 150 | ocamlopt -o myprog -p \var{other-options} \var{files} 151 | ./myprog 152 | gprof myprog 153 | \end{alltt} 154 | OCaml function names in the output of "gprof" have the following format: 155 | \begin{alltt} 156 | \var{Module-name}_\var{function-name}_\var{unique-number} 157 | \end{alltt} 158 | Other functions shown are either parts of the OCaml run-time system or 159 | external C functions linked with the program. 160 | 161 | The output of "gprof" is described in the Unix manual page for 162 | "gprof(1)". It generally consists of two parts: a ``flat'' profile 163 | showing the time spent in each function and the number of invocation 164 | of each function, and a ``hierarchical'' profile based on the call 165 | graph. Currently, only the Intel x86 ports of "ocamlopt" under 166 | Linux, BSD and MacOS X support the two profiles. On other platforms, 167 | "gprof" will report only the ``flat'' profile with just time 168 | information. When reading the output of "gprof", keep in mind that 169 | the accumulated times computed by "gprof" are based on heuristics and 170 | may not be exact. 171 | 172 | \paragraph{Note} The "ocamloptp" command also accepts the "-p" 173 | option. In that case, both kinds of profiling are performed by the 174 | program, and you can display the results with the "gprof" and "ocamlprof" 175 | commands, respectively. 176 | -------------------------------------------------------------------------------- /manual/cmds/depend.etex: -------------------------------------------------------------------------------- 1 | \chapter{Dependency generator (ocamldep)} \label{c:camldep} 2 | %HEVEA\cutname{depend.html} 3 | 4 | The "ocamldep" command scans a set of OCaml source files 5 | (".ml" and ".mli" files) for references to external compilation units, 6 | and outputs dependency lines in a format suitable for the "make" 7 | utility. This ensures that "make" will compile the source files in the 8 | correct order, and recompile those files that need to when a source 9 | file is modified. 10 | 11 | The typical usage is: 12 | \begin{alltt} 13 | ocamldep \var{options} *.mli *.ml > .depend 14 | \end{alltt} 15 | where "*.mli *.ml" expands to all source files in the current 16 | directory and ".depend" is the file that should contain the 17 | dependencies. (See below for a typical "Makefile".) 18 | 19 | Dependencies are generated both for compiling with the bytecode 20 | compiler "ocamlc" and with the native-code compiler "ocamlopt". 21 | 22 | \section{Options} 23 | 24 | The following command-line options are recognized by "ocamldep". 25 | 26 | \begin{options} 27 | 28 | \item["-absname"] 29 | Show absolute filenames in error messages. 30 | 31 | \item["-all"] 32 | Generate dependencies on all required files, rather than assuming 33 | implicit dependencies. 34 | 35 | \item["-allow-approx"] 36 | Allow falling back on a lexer-based approximation when parsing fails. 37 | 38 | \item["-args" \var{filename}] 39 | Read additional newline-terminated command line arguments from \var{filename}. 40 | 41 | \item["-args0" \var{filename}] 42 | Read additional null character terminated command line arguments from \var{filename}. 43 | 44 | \item["-as-map"] 45 | For the following files, do not include delayed dependencies for 46 | module aliases. 47 | This option assumes that they are compiled using options 48 | "-no-alias-deps -w -49", and that those files or their interface are 49 | passed with the "-map" option when computing dependencies for other 50 | files. Note also that for dependencies to be correct in the 51 | implementation of a map file, its interface should not coerce any of 52 | the aliases it contains. 53 | 54 | \item["-debug-map"] 55 | Dump the delayed dependency map for each map file. 56 | 57 | \item["-I" \var{directory}] 58 | Add the given directory to the list of directories searched for 59 | source files. If a source file "foo.ml" mentions an external 60 | compilation unit "Bar", a dependency on that unit's interface 61 | "bar.cmi" is generated only if the source for "bar" is found in the 62 | current directory or in one of the directories specified with "-I". 63 | Otherwise, "Bar" is assumed to be a module from the standard library, 64 | and no dependencies are generated. For programs that span multiple 65 | directories, it is recommended to pass "ocamldep" the same "-I" options 66 | that are passed to the compiler. 67 | 68 | \item["-impl" \var{file}] 69 | Process \var{file} as a ".ml" file. 70 | 71 | \item["-intf" \var{file}] 72 | Process \var{file} as a ".mli" file. 73 | 74 | \item["-map" \var{file}] 75 | Read an propagate the delayed dependencies for module aliases in 76 | \var{file}, so that the following files will depend on the 77 | exported aliased modules if they use them. See the example below. 78 | 79 | \item["-ml-synonym" \var{.ext}] 80 | Consider the given extension (with leading dot) to be a synonym for .ml. 81 | 82 | \item["-mli-synonym" \var{.ext}] 83 | Consider the given extension (with leading dot) to be a synonym for .mli. 84 | 85 | \item["-modules"] 86 | Output raw dependencies of the form 87 | \begin{verbatim} 88 | filename: Module1 Module2 ... ModuleN 89 | \end{verbatim} 90 | where "Module1", \ldots, "ModuleN" are the names of the compilation 91 | units referenced within the file "filename", but these names are not 92 | resolved to source file names. Such raw dependencies cannot be used 93 | by "make", but can be post-processed by other tools such as "Omake". 94 | 95 | \item["-native"] 96 | Generate dependencies for a pure native-code program (no bytecode 97 | version). When an implementation file (".ml" file) has no explicit 98 | interface file (".mli" file), "ocamldep" generates dependencies on the 99 | bytecode compiled file (".cmo" file) to reflect interface changes. 100 | This can cause unnecessary bytecode recompilations for programs that 101 | are compiled to native-code only. The flag "-native" causes 102 | dependencies on native compiled files (".cmx") to be generated instead 103 | of on ".cmo" files. (This flag makes no difference if all source files 104 | have explicit ".mli" interface files.) 105 | 106 | \item["-one-line"] 107 | Output one line per file, regardless of the length. 108 | 109 | \item["-open" \var{module}] 110 | Assume that module \var{module} is opened before parsing each of the 111 | following files. 112 | 113 | \item["-plugin" \var{plugin}] 114 | Dynamically load the code of the given \var{plugin} 115 | (a ".cmo", ".cma" or ".cmxs" file) in "ocamldep". \var{plugin} must exist in 116 | the same kind of code as "ocamldep" ("ocamldep.byte" must load bytecode 117 | plugins, while "ocamldep.opt" must load native code plugins), and 118 | extension adaptation is done automatically for ".cma" files (to ".cmxs" files 119 | if "ocamldep" is compiled in native code). 120 | 121 | \item["-pp" \var{command}] 122 | Cause "ocamldep" to call the given \var{command} as a preprocessor 123 | for each source file. 124 | 125 | \item["-ppx" \var{command}] 126 | Pipe abstract syntax trees through preprocessor \var{command}. 127 | 128 | \item["-shared"] 129 | Generate dependencies for native plugin files (.cmxs) in addition to 130 | native compiled files (.cmx). 131 | 132 | \item["-slash"] 133 | Under Windows, use a forward slash (/) as the path separator instead 134 | of the usual backward slash ($\backslash$). Under Unix, this option does 135 | nothing. 136 | 137 | \item["-sort"] 138 | Sort files according to their dependencies. 139 | 140 | \item["-version"] 141 | Print version string and exit. 142 | 143 | \item["-vnum"] 144 | Print short version number and exit. 145 | 146 | \item["-help" or "--help"] 147 | Display a short usage summary and exit. 148 | % 149 | \end{options} 150 | 151 | \section{A typical Makefile} 152 | 153 | Here is a template "Makefile" for a OCaml program. 154 | 155 | \begin{verbatim} 156 | OCAMLC=ocamlc 157 | OCAMLOPT=ocamlopt 158 | OCAMLDEP=ocamldep 159 | INCLUDES= # all relevant -I options here 160 | OCAMLFLAGS=$(INCLUDES) # add other options for ocamlc here 161 | OCAMLOPTFLAGS=$(INCLUDES) # add other options for ocamlopt here 162 | 163 | # prog1 should be compiled to bytecode, and is composed of three 164 | # units: mod1, mod2 and mod3. 165 | 166 | # The list of object files for prog1 167 | PROG1_OBJS=mod1.cmo mod2.cmo mod3.cmo 168 | 169 | prog1: $(PROG1_OBJS) 170 | $(OCAMLC) -o prog1 $(OCAMLFLAGS) $(PROG1_OBJS) 171 | 172 | # prog2 should be compiled to native-code, and is composed of two 173 | # units: mod4 and mod5. 174 | 175 | # The list of object files for prog2 176 | PROG2_OBJS=mod4.cmx mod5.cmx 177 | 178 | prog2: $(PROG2_OBJS) 179 | $(OCAMLOPT) -o prog2 $(OCAMLFLAGS) $(PROG2_OBJS) 180 | 181 | # Common rules 182 | .SUFFIXES: .ml .mli .cmo .cmi .cmx 183 | 184 | .ml.cmo: 185 | $(OCAMLC) $(OCAMLFLAGS) -c $< 186 | 187 | .mli.cmi: 188 | $(OCAMLC) $(OCAMLFLAGS) -c $< 189 | 190 | .ml.cmx: 191 | $(OCAMLOPT) $(OCAMLOPTFLAGS) -c $< 192 | 193 | # Clean up 194 | clean: 195 | rm -f prog1 prog2 196 | rm -f *.cm[iox] 197 | 198 | # Dependencies 199 | depend: 200 | $(OCAMLDEP) $(INCLUDES) *.mli *.ml > .depend 201 | 202 | include .depend 203 | \end{verbatim} 204 | 205 | If you use module aliases to give shorter names to modules, you need 206 | to change the above definitions. Assuming that your map file is called 207 | "mylib.mli", here are minimal modifications. 208 | \begin{verbatim} 209 | OCAMLFLAGS=$(INCLUDES) -open Mylib 210 | 211 | mylib.cmi: mylib.mli 212 | $(OCAMLC) $(INCLUDES) -no-alias-deps -w -49 -c $< 213 | 214 | depend: 215 | $(OCAMLDEP) $(INCLUDES) -map mylib.mli $(PROG1_OBJS:.cmo=.ml) > .depend 216 | \end{verbatim} 217 | Note that in this case you should not compute dependencies for 218 | "mylib.mli" together with the other files, hence the need to pass 219 | explicitly the list of files to process. 220 | If "mylib.mli" itself has dependencies, you should compute them using 221 | "-as-map". 222 | -------------------------------------------------------------------------------- /tests/cross_reference_checker.ml: -------------------------------------------------------------------------------- 1 | (** Check reference to manual section in ml files 2 | 3 | [cross-reference-cheker -auxfile tex.aux src.ml ] 4 | checks that all expression and let bindings in [src.ml] annotated 5 | with [[@manual.ref "tex_label"]] are integer tuple literals, e.g 6 | {[ 7 | let[@manual.ref "sec:major"] ref = 1, 1 8 | (* or *) 9 | let ref = (3 [@manual.ref "ch:pentatonic"]) 10 | ]} 11 | and that their values are consistent with the computed references for the 12 | payload labels (e.g "sec:major", "ch:pentatonic") present in the TeX 13 | auxiliary file [tex.aux] 14 | 15 | *) 16 | 17 | 18 | (** {1 Error printing } *) 19 | type error = 20 | | Reference_mismatch of 21 | {loc:Location.t; label:string; ocaml:int list; tex:int list} 22 | | Unknown_label of Location.t * string 23 | | Tuple_expected of Location.t 24 | | No_aux_file 25 | | Wrong_attribute_payload of Location.t 26 | 27 | let pp_ref ppf = Format.pp_print_list ~pp_sep:( fun ppf () -> 28 | Format.pp_print_string ppf ".") Format.pp_print_int ppf 29 | 30 | let print_error error = 31 | Location.print_report Format.std_formatter @@ match error with 32 | | Tuple_expected loc -> 33 | Location.errorf ~loc 34 | "Integer tuple expected after manual reference annotation@." 35 | | Unknown_label (loc,label) -> 36 | Location.errorf ~loc 37 | "@[Unknown manual label:@ %s@]@." label 38 | | Reference_mismatch r -> 39 | Location.errorf ~loc:r.loc 40 | "@[References for label %S do not match:@,\ 41 | OCaml side %a,@,\ 42 | manual %a@]@." 43 | r.label 44 | pp_ref r.ocaml 45 | pp_ref r.tex 46 | | No_aux_file -> 47 | Location.errorf "No aux file provided@." 48 | | Wrong_attribute_payload loc -> 49 | Location.errorf ~loc "Wrong payload for \"@manual.ref\"@." 50 | 51 | 52 | (** {1 Main types} *) 53 | 54 | (** Maps of ocaml reference to manual labels *) 55 | module Refs = Map.Make(String) 56 | 57 | (** Reference extracted from TeX aux files *) 58 | type tex_reference = 59 | { label: string; 60 | pos: int list; 61 | level: string 62 | } 63 | 64 | type status = Ok | Bad | Unknown 65 | 66 | (** Reference extracted from OCaml source files *) 67 | type ml_reference = { loc: Location.t; pos: int list; status:status } 68 | 69 | (** {1 Consistency check } *) 70 | 71 | let check_consistency (ref:tex_reference) {loc; pos; _ } = 72 | if ref.pos = pos then 73 | { loc; pos; status = Ok } 74 | else begin 75 | print_error @@ Reference_mismatch {loc;label=ref.label;tex=ref.pos;ocaml=pos}; 76 | {loc; pos; status = Bad } 77 | end 78 | 79 | let rec check_final_status label error = function 80 | | { status = Ok; _ } -> error 81 | | { status = Bad; _ } -> true 82 | | { status = Unknown; loc; _} -> 83 | print_error (Unknown_label (loc,label)); 84 | true 85 | 86 | (** {1 Data extraction from TeX side} *) 87 | 88 | module TeX = struct 89 | 90 | (** Read reference information from a line of the aux file *) 91 | let scan s = 92 | try 93 | Scanf.sscanf s 94 | "\\newlabel{%s@}{{%s@}{%_d}{%_s@}{%s@.%_s@}{%_s@}}" 95 | (fun label position_string level -> 96 | let pos = 97 | List.map int_of_string (String.split_on_char '.' position_string) in 98 | Some {label;level;pos} ) 99 | with 100 | | Scanf.Scan_failure _ -> None 101 | | Failure _ -> None 102 | 103 | let check_line refs line = 104 | match scan line with 105 | | None -> refs 106 | | Some ref -> 107 | match Refs.find_opt ref.label refs with 108 | | None -> refs 109 | | Some l -> 110 | Refs.add ref.label 111 | (List.map (check_consistency ref) l) 112 | refs 113 | 114 | let check_all aux refs = 115 | let chan = open_in aux in 116 | let rec lines refs = 117 | let s = try Some (input_line chan) with End_of_file -> None in 118 | match s with 119 | | None -> refs 120 | | Some line -> 121 | lines @@ check_line refs line in 122 | let refs = lines refs in 123 | close_in chan; 124 | let error = Refs.fold (fun label ocaml_refs error -> 125 | List.fold_left (check_final_status label) error ocaml_refs) 126 | refs false in 127 | if error then exit 2 else exit 0 128 | end 129 | 130 | (** {1 Extract references from Ocaml source files} *) 131 | module OCaml_refs = struct 132 | 133 | let parse sourcefile = 134 | Pparse.parse_implementation ~tool_name:"manual_cross_reference_check" 135 | sourcefile 136 | 137 | (** search for an attribute [[@manual.ref "tex_label_name"]] *) 138 | let manual_reference_attribute attr = 139 | let open Parsetree in 140 | if attr.attr_name.Location.txt <> "manual.ref" 141 | then None 142 | else begin match attr.attr_payload with 143 | | PStr [{pstr_desc= Pstr_eval 144 | ({ pexp_desc = Pexp_constant Pconst_string (s,_) },_) } ] -> 145 | Some s 146 | | _ -> print_error (Wrong_attribute_payload attr.attr_loc); 147 | Some "" (* triggers an error *) 148 | end 149 | 150 | let rec label_from_attributes = function 151 | | [] -> None 152 | | a :: q -> match manual_reference_attribute a with 153 | | Some _ as x -> x 154 | | None -> label_from_attributes q 155 | 156 | let int e = 157 | let open Parsetree in 158 | match e.pexp_desc with 159 | | Pexp_constant Pconst_integer (s, _ ) -> int_of_string s 160 | | _ -> raise Exit 161 | 162 | let int_list l = 163 | try Some (List.map int l) with 164 | | Exit -> None 165 | 166 | (** We keep a list of OCaml-side references to the same label *) 167 | let add_ref label ref refs = 168 | let l = match Refs.find_opt label refs with 169 | | None -> [ref] 170 | | Some l -> ref :: l in 171 | Refs.add label l refs 172 | 173 | let inner_expr loc e = 174 | let tuple_expected () = print_error (Tuple_expected loc) in 175 | match e.Parsetree.pexp_desc with 176 | | Parsetree.Pexp_tuple l -> 177 | begin match int_list l with 178 | | None -> tuple_expected (); [] 179 | | Some pos -> pos 180 | end 181 | | Parsetree.Pexp_constant Pconst_integer (n,_) -> 182 | [int_of_string n] 183 | | _ -> tuple_expected (); [] 184 | 185 | (** extract from [let[@manual.ref "label"] x= 1, 2] *) 186 | let value_binding m iterator vb = 187 | let open Parsetree in 188 | begin match label_from_attributes vb.pvb_attributes with 189 | | None -> () 190 | | Some label -> 191 | let pos = inner_expr vb.pvb_loc vb.pvb_expr in 192 | m := add_ref label {loc = vb.pvb_loc; pos; status = Unknown } !m 193 | end; 194 | iterator.Ast_iterator.expr iterator vb.pvb_expr 195 | 196 | 197 | (** extract from [ (1,2)[@manual.ref "label"]] *) 198 | let expr m iterator e = 199 | let open Parsetree in 200 | begin match label_from_attributes e.pexp_attributes with 201 | | None -> () 202 | | Some label -> 203 | let pos = inner_expr e.pexp_loc e in 204 | m := add_ref label {loc = e.pexp_loc; pos; status = Unknown } !m 205 | end; 206 | Ast_iterator.default_iterator.expr iterator e 207 | 208 | let from_ast m ast = 209 | let iterator = 210 | let value_binding = value_binding m in 211 | let expr = expr m in 212 | Ast_iterator.{ default_iterator with value_binding; expr } in 213 | iterator.structure iterator ast 214 | 215 | let from_file m f = 216 | from_ast m @@ parse f 217 | end 218 | 219 | 220 | (** {1 Argument handling and main function } *) 221 | 222 | let usage = 223 | "cross-reference-check -auxfile [file.aux] file_1 ... file_n checks that \ 224 | the cross reference annotated with [@manual_cross_reference] are consistent \ 225 | with the provided auxiliary TeX file" 226 | 227 | (** the auxiliary file containing reference to be checked *) 228 | let aux_file = ref None 229 | 230 | let args = 231 | [ 232 | "-auxfile",Arg.String (fun s -> aux_file := Some s), 233 | "set the reference file" 234 | ] 235 | 236 | let () = 237 | let m = ref Refs.empty in 238 | Arg.parse args (OCaml_refs.from_file m) usage; 239 | match !aux_file with 240 | | None -> print_error No_aux_file; exit 2 241 | | Some aux -> 242 | let error = TeX.check_all aux !m in 243 | if error then exit 2 else exit 0 244 | -------------------------------------------------------------------------------- /styles/html.sty: -------------------------------------------------------------------------------- 1 | % LaTeX2HTML Version 0.6.4 : html.sty 2 | % 3 | % This file contains definitions of LaTeX commands which are 4 | % processed in a special way by the translator. 5 | % For example, there are commands for embedding external hypertext links, 6 | % for cross-references between documents or for including 7 | % raw HTML. 8 | % This file includes the comments.sty file v2.0 by Victor Eijkhout 9 | % In most cases these commands do nothing when processed by LaTeX. 10 | 11 | % Modifications: 12 | % 13 | % nd = Nikos Drakos 14 | % jz = Jelle van Zeijl 15 | 16 | % jz 22-APR-94 - Added support for htmlref 17 | % nd - Created 18 | 19 | 20 | 21 | % Exit if the style file is already loaded 22 | % (suggested by Lee Shombert 23 | \ifx \htmlstyloaded\relax \endinput\else\let\htmlstyloaded\relax\fi 24 | 25 | %%% LINKS TO EXTERNAL DOCUMENTS 26 | % 27 | % This can be used to provide links to arbitrary documents. 28 | % The first argumment should be the text that is going to be 29 | % highlighted and the second argument a URL. 30 | % The hyperlink will appear as a hyperlink in the HTML 31 | % document and as a footnote in the dvi or ps files. 32 | % 33 | \newcommand{\htmladdnormallinkfoot}[2]{ #1\footnote{#2}} 34 | 35 | % This is an alternative definition of the command above which 36 | % will ignore the URL in the dvi or ps files. 37 | \newcommand{\htmladdnormallink}[2]{ #1 } 38 | 39 | % This command takes as argument a URL pointing to an image. 40 | % The image will be embedded in the HTML document but will 41 | % be ignored in the dvi and ps files. 42 | % 43 | \newcommand{\htmladdimg}[1]{ } 44 | 45 | %%% CROSS-REFERENCES BETWEEN (LOCAL OR REMOTE) DOCUMENTS 46 | % 47 | % This can be used to refer to symbolic labels in other Latex 48 | % documents that have already been processed by the translator. 49 | % The arguments should be: 50 | % #1 : the URL to the directory containing the external document 51 | % #2 : the path to the labels.pl file of the external document. 52 | % If the external document lives on a remote machine then labels.pl 53 | % must be copied on the local machine. 54 | % 55 | %e.g. \externallabels{http://cbl.leeds.ac.uk/nikos/WWW/doc/tex2html/latex2html} 56 | % {/usr/cblelca/nikos/tmp/labels.pl} 57 | % The arguments are ignored in the dvi and ps files. 58 | % 59 | \newcommand{\externallabels}[2]{ } 60 | 61 | % This complements the \externallabels command above. The argument 62 | % should be a label defined in another latex document and will be 63 | % ignored in the dvi and ps files. 64 | % 65 | \newcommand{\externalref}[1]{ } 66 | 67 | 68 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 69 | % Comment.sty version 2.0, 19 June 1992 70 | % selectively in/exclude pieces of text: the user can define new 71 | % comment versions, and each is controlled separately. 72 | % This style can be used with plain TeX or LaTeX, and probably 73 | % most other packages too. 74 | % 75 | % Examples of use in LaTeX and TeX follow \endinput 76 | % 77 | % Author 78 | % Victor Eijkhout 79 | % Department of Computer Science 80 | % University Tennessee at Knoxville 81 | % 104 Ayres Hall 82 | % Knoxville, TN 37996 83 | % USA 84 | % 85 | % eijkhout@cs.utk.edu 86 | % 87 | % Usage: all text included in between 88 | % \comment ... \endcomment 89 | % or \begin{comment} ... \end{comment} 90 | % is discarded. The closing command should appear on a line 91 | % of its own. No starting spaces, nothing after it. 92 | % This environment should work with arbitrary amounts 93 | % of comment. 94 | % 95 | % Other 'comment' environments are defined by 96 | % and are selected/deselected with 97 | % \includecomment{versiona} 98 | % \excludecoment{versionb} 99 | % 100 | % These environments are used as 101 | % \versiona ... \endversiona 102 | % or \begin{versiona} ... \end{versiona} 103 | % with the closing command again on a line of its own. 104 | % 105 | % Basic approach: 106 | % to comment something out, scoop up every line in verbatim mode 107 | % as macro argument, then throw it away. 108 | % For inclusions, both the opening and closing comands 109 | % are defined as noop 110 | % 111 | % Changed \next to \html@next to prevent clashes with other sty files 112 | % (mike@emn.fr) 113 | % Changed \html@next to \htmlnext so the \makeatletter and 114 | % \makeatother commands could be removed (they were cuasing other 115 | % style files - changebar.sty - to crash) (nikos@cbl.leeds.ac.uk) 116 | 117 | 118 | \def\makeinnocent#1{\catcode`#1=12 } 119 | \def\csarg#1#2{\expandafter#1\csname#2\endcsname} 120 | 121 | \def\ThrowAwayComment#1{\begingroup 122 | \def\CurrentComment{#1}% 123 | \let\do\makeinnocent \dospecials 124 | \makeinnocent\^^L% and whatever other special cases 125 | \endlinechar`\^^M \catcode`\^^M=12 \xComment} 126 | {\catcode`\^^M=12 \endlinechar=-1 % 127 | \gdef\xComment#1^^M{\def\test{#1} 128 | \csarg\ifx{PlainEnd\CurrentComment Test}\test 129 | \let\htmlnext\endgroup 130 | \else \csarg\ifx{LaLaEnd\CurrentComment Test}\test 131 | \edef\htmlnext{\endgroup\noexpand\end{\CurrentComment}} 132 | \else \let\htmlnext\xComment 133 | \fi \fi \htmlnext} 134 | } 135 | 136 | \def\includecomment 137 | #1{\expandafter\def\csname#1\endcsname{}% 138 | \expandafter\def\csname end#1\endcsname{}} 139 | \def\excludecomment 140 | #1{\expandafter\def\csname#1\endcsname{\ThrowAwayComment{#1}}% 141 | {\escapechar=-1\relax 142 | \csarg\xdef{PlainEnd#1Test}{\string\\end#1}% 143 | \csarg\xdef{LaLaEnd#1Test}{\string\\end\string\{#1\string\}}% 144 | }} 145 | 146 | \excludecomment{comment} 147 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 148 | 149 | %%% RAW HTML 150 | % 151 | % Enclose raw HTML between a \begin{rawhtml} and \end{rawhtml}. 152 | % The html environment ignores its body 153 | % 154 | \excludecomment{rawhtml} 155 | 156 | %%% HTML ONLY 157 | % 158 | % Enclose LaTeX constructs which will only appear in the 159 | % HTML output and will be ignored by LaTeX with 160 | % \begin{htmlonly} and \end{htmlonly} 161 | % 162 | \excludecomment{htmlonly} 163 | 164 | %%% LaTeX ONLY 165 | % Enclose LaTeX constructs which will only appear in the 166 | % DVI output and will be ignored by latex2html with 167 | %\begin{latexonly} and \end{latexonly} 168 | % 169 | \newenvironment{latexonly}{}{} 170 | 171 | %%% HYPERREF 172 | % Suggested by Eric M. Carol 173 | % Similar to \ref but accepts conditional text. 174 | % The first argument is HTML text which will become ``hyperized'' 175 | % (underlined). 176 | % The second and third arguments are text which will appear only in the paper 177 | % version (DVI file), enclosing the fourth argument which is a reference to a label. 178 | % 179 | %e.g. \hyperref{using the tracer}{using the tracer (see Section}{)}{trace} 180 | % where there is a corresponding \label{trace} 181 | % 182 | \newcommand{\hyperref}[4]{#2\ref{#4}#3} 183 | 184 | %%% HTMLREF 185 | % Reference in HTML version only. 186 | % Mix between \htmladdnormallink and \hyperref. 187 | % First arg is text for in both versions, second is label for use in HTML 188 | % version. 189 | \newcommand{\htmlref}[2]{#1} 190 | 191 | %%% HTMLIMAGE 192 | % This command can be used inside any environment that is converted 193 | % into an inlined image (eg a "figure" environment) in order to change 194 | % the way the image will be translated. The argument of \htmlimage 195 | % is really a string of options separated by commas ie 196 | % [scale=],[external],[thumbnail= 197 | % The scale option allows control over the size of the final image. 198 | % The ``external'' option will cause the image not to be inlined 199 | % (images are inlined by default). External images will be accessible 200 | % via a hypertext link. 201 | % The ``thumbnail'' option will cause a small inlined image to be 202 | % placed in the caption. The size of the thumbnail depends on the 203 | % reduction factor. The use of the ``thumbnail'' option implies 204 | % the ``external'' option. 205 | % 206 | % Example: 207 | % \htmlimage{scale=1.5,external,thumbnail=0.2} 208 | % will cause a small thumbnail image 1/5th of the original size to be 209 | % placed in the final document, pointing to an external image 1.5 210 | % times bigger than the original. 211 | % 212 | \newcommand{\htmlimage}[1]{} 213 | 214 | %%% HTMLADDTONAVIGATION 215 | % This command appends its argument to the buttons in the navigation 216 | % panel. It is ignored by LaTeX. 217 | % 218 | % Example: 219 | % \htmladdtonavigation{\htmladdnormallink 220 | % {\htmladdimg{http://server/path/to/gif}} 221 | % {http://server/path}} 222 | \newcommand{\htmladdtonavigation}[1]{} 223 | -------------------------------------------------------------------------------- /manual/refman/patterns.etex: -------------------------------------------------------------------------------- 1 | \section{Patterns} 2 | \ikwd{as\@\texttt{as}} 3 | %HEVEA\cutname{patterns.html} 4 | \begin{syntax} 5 | pattern: 6 | value-name 7 | | '_' 8 | | constant 9 | | pattern 'as' value-name 10 | | '(' pattern ')' 11 | | '(' pattern ':' typexpr ')' 12 | | pattern '|' pattern 13 | | constr pattern 14 | | "`"tag-name pattern 15 | | "#"typeconstr 16 | | pattern {{ ',' pattern }} 17 | | '{' field [':' typexpr] ['=' pattern]% 18 | { ';' field [':' typexpr] ['=' pattern] } [';' '_' ] [ ';' ] '}' 19 | | '[' pattern { ';' pattern } [ ';' ] ']' 20 | | pattern '::' pattern 21 | | '[|' pattern { ';' pattern } [ ';' ] '|]' 22 | | char-literal '..' char-literal 23 | | 'exception' pattern 24 | \end{syntax} 25 | See also the following language extensions: \hyperref[s:lazypat]{lazy patterns}, 26 | \hyperref[s:local-opens]{local opens}, 27 | \hyperref[s-first-class-modules]{first-class modules}, 28 | \hyperref[s:attributes]{attributes} and 29 | \hyperref[s:extension-nodes]{extension nodes}. 30 | 31 | The table below shows the relative precedences and associativity of 32 | operators and non-closed pattern constructions. The constructions with 33 | higher precedences come first. 34 | \ikwd{as\@\texttt{as}} 35 | \begin{tableau}{|l|l|}{Operator}{Associativity} 36 | \entree{".."}{--} 37 | \entree{"lazy" (see section~\ref{s:lazypat})}{--} 38 | \entree{Constructor application, Tag application}{right} 39 | \entree{"::"}{right} 40 | \entree{","}{--} 41 | \entree{"|"}{left} 42 | \entree{"as"}{--} 43 | \end{tableau} 44 | 45 | Patterns are templates that allow selecting data structures of a 46 | given shape, and binding identifiers to components of the data 47 | structure. This selection operation is called pattern matching; its 48 | outcome is either ``this value does not match this pattern'', or 49 | ``this value matches this pattern, resulting in the following bindings 50 | of names to values''. 51 | 52 | \subsubsection*{Variable patterns} 53 | 54 | A pattern that consists in a value name matches any value, 55 | binding the name to the value. The pattern @"_"@ also matches 56 | any value, but does not bind any name. 57 | 58 | Patterns are {\em linear\/}: a variable cannot be bound several times by 59 | a given pattern. In particular, there is no way to test for equality 60 | between two parts of a data structure using only a pattern (but 61 | @"when"@ guards can be used for this purpose). 62 | 63 | \subsubsection*{Constant patterns} 64 | 65 | A pattern consisting in a constant matches the values that 66 | are equal to this constant. 67 | 68 | %% FIXME for negative numbers, blanks are allowed between the minus 69 | %% sign and the first digit. 70 | 71 | \subsubsection*{Alias patterns} 72 | \ikwd{as\@\texttt{as}} 73 | 74 | The pattern @pattern_1 "as" value-name@ matches the same values as 75 | @pattern_1@. If the matching against @pattern_1@ is successful, 76 | the name @value-name@ is bound to the matched value, in addition to the 77 | bindings performed by the matching against @pattern_1@. 78 | 79 | \subsubsection*{Parenthesized patterns} 80 | 81 | The pattern @"(" pattern_1 ")"@ matches the same values as 82 | @pattern_1@. A type constraint can appear in a 83 | parenthesized pattern, as in @"(" pattern_1 ":" typexpr ")"@. This 84 | constraint forces the type of @pattern_1@ to be compatible with 85 | @typexpr@. 86 | 87 | \subsubsection*{``Or'' patterns} 88 | 89 | The pattern @pattern_1 "|" pattern_2@ represents the logical ``or'' of 90 | the two patterns @pattern_1@ and @pattern_2@. A value matches 91 | @pattern_1 "|" pattern_2@ if it matches @pattern_1@ or 92 | @pattern_2@. The two sub-patterns @pattern_1@ and @pattern_2@ 93 | must bind exactly the same identifiers to values having the same types. 94 | Matching is performed from left to right. 95 | More precisely, 96 | in case some value~$v$ matches @pattern_1 "|" pattern_2@, the bindings 97 | performed are those of @pattern_1@ when $v$ matches @pattern_1@. 98 | Otherwise, value~$v$ matches @pattern_2@ whose bindings are performed. 99 | 100 | 101 | \subsubsection*{Variant patterns} 102 | 103 | The pattern @constr '(' pattern_1 ',' \ldots ',' pattern_n ')'@ matches 104 | all variants whose 105 | constructor is equal to @constr@, and whose arguments match 106 | @pattern_1 \ldots pattern_n@. It is a type error if $n$ is not the 107 | number of arguments expected by the constructor. 108 | 109 | The pattern @constr '_'@ matches all variants whose constructor is 110 | @constr@. 111 | 112 | The pattern @pattern_1 "::" pattern_2@ matches non-empty lists whose 113 | heads match @pattern_1@, and whose tails match @pattern_2@. 114 | 115 | The pattern @"[" pattern_1 ";" \ldots ";" pattern_n "]"@ matches lists 116 | of length $n$ whose elements match @pattern_1@ \ldots @pattern_n@, 117 | respectively. This pattern behaves like 118 | @pattern_1 "::" \ldots "::" pattern_n "::" "[]"@. 119 | 120 | \subsubsection*{Polymorphic variant patterns} 121 | 122 | The pattern @"`"tag-name pattern_1@ matches all polymorphic variants 123 | whose tag is equal to @tag-name@, and whose argument matches 124 | @pattern_1@. 125 | 126 | \subsubsection*{Polymorphic variant abbreviation patterns} 127 | 128 | If the type @["('a,'b,"\ldots")"] typeconstr = "[" "`"tag-name_1 typexpr_1 "|" 129 | \ldots "|" "`"tag-name_n typexpr_n"]"@ is defined, then the pattern @"#"typeconstr@ 130 | is a shorthand for the following or-pattern: 131 | @"(" "`"tag-name_1"(_" ":" typexpr_1")" "|" \ldots "|" "`"tag-name_n"(_" 132 | ":" typexpr_n"))"@. It matches all values of type @"[<" typeconstr "]"@. 133 | 134 | \subsubsection*{Tuple patterns} 135 | 136 | The pattern @pattern_1 "," \ldots "," pattern_n@ matches $n$-tuples 137 | whose components match the patterns @pattern_1@ through @pattern_n@. That 138 | is, the pattern matches the tuple values $(v_1, \ldots, v_n)$ such that 139 | @pattern_i@ matches $v_i$ for \fromoneto{i}{n}. 140 | 141 | \subsubsection*{Record patterns} 142 | 143 | The pattern @"{" field_1 ["=" pattern_1] ";" \ldots ";" field_n ["=" 144 | pattern_n] "}"@ matches records that define at least the fields 145 | @field_1@ through @field_n@, and such that the value associated to 146 | @field_i@ matches the pattern @pattern_i@, for \fromoneto{i}{n}. 147 | A single identifier @field_k@ stands for @field_k '=' field_k @, 148 | and a single qualified identifier @module-path '.' field_k@ stands 149 | for @module-path '.' field_k '=' field_k @. 150 | The record value can define more fields than @field_1@ \ldots 151 | @field_n@; the values associated to these extra fields are not taken 152 | into account for matching. Optionally, a record pattern can be terminated 153 | by @';' '_'@ to convey the fact that not all fields of the record type are 154 | listed in the record pattern and that it is intentional. 155 | Optional type constraints can be added field by field with 156 | @"{" field_1 ":" typexpr_1 "=" pattern_1 ";"% 157 | \ldots ";"field_n ":" typexpr_n "=" pattern_n "}"@ to force the type 158 | of @field_k@ to be compatible with @typexpr_k@. 159 | 160 | 161 | \subsubsection*{Array patterns} 162 | 163 | The pattern @"[|" pattern_1 ";" \ldots ";" pattern_n "|]"@ 164 | matches arrays of length $n$ such that the $i$-th array element 165 | matches the pattern @pattern_i@, for \fromoneto{i}{n}. 166 | 167 | \subsubsection*{Range patterns} 168 | 169 | The pattern 170 | @"'" @c@ "'" ".." "'" @d@ "'"@ is a shorthand for the pattern 171 | \begin{center} 172 | @"'" @c@ "'" "|" "'" @c@_1 "'" "|" "'" @c@_2 "'" "|" \ldots 173 | "|" "'" @c@_n "'" "|" "'" @d@ "'"@ 174 | \end{center} 175 | where \nth{c}{1}, \nth{c}{2}, \ldots, \nth{c}{n} are the characters 176 | that occur between \var{c} and \var{d} in the ASCII character set. For 177 | instance, the pattern "'0'"@'..'@"'9'" matches all characters that are digits. 178 | 179 | \subsubsection*{Exception patterns} \label{s:exception-match} 180 | (Introduced in OCaml 4.02) 181 | 182 | A new form of exception pattern, @ 'exception' pattern, @ is allowed 183 | only as a toplevel pattern under a "match"..."with" pattern-matching 184 | (other occurrences are rejected by the type-checker). 185 | 186 | Cases with such a toplevel pattern are called ``exception cases'', 187 | as opposed to regular ``value cases''. Exception cases are applied 188 | when the evaluation of the matched expression raises an exception. 189 | The exception value is then matched against all the exception cases 190 | and re-raised if none of them accept the exception (as with a 191 | "try"..."with" block). Since the bodies of all exception and value 192 | cases are outside the scope of the exception handler, they are all 193 | considered to be in tail-position: if the "match"..."with" block 194 | itself is in tail position in the current function, any function call 195 | in tail position in one of the case bodies results in an actual tail 196 | call. 197 | 198 | A pattern match must contain at least one value case. It is an error if 199 | all cases are exceptions, because there would be no code to handle 200 | the return of a value. 201 | -------------------------------------------------------------------------------- /manual/refman/modules.etex: -------------------------------------------------------------------------------- 1 | \section{Module\label{s:module-expr} expressions (module implementations)} 2 | %HEVEA\cutname{modules.html} 3 | 4 | Module expressions are the module-level equivalent of value 5 | expressions: they evaluate to modules, thus providing implementations 6 | for the specifications expressed in module types. 7 | 8 | \ikwd{struct\@\texttt{struct}} 9 | \ikwd{end\@\texttt{end}} 10 | \ikwd{functor\@\texttt{functor}} 11 | \ikwd{let\@\texttt{let}} 12 | \ikwd{and\@\texttt{and}} 13 | \ikwd{external\@\texttt{external}} 14 | \ikwd{type\@\texttt{type}} 15 | \ikwd{exception\@\texttt{exception}} 16 | \ikwd{class\@\texttt{class}} 17 | \ikwd{module\@\texttt{module}} 18 | \ikwd{open\@\texttt{open}} 19 | \ikwd{include\@\texttt{include}} 20 | 21 | \begin{syntax} 22 | module-expr: 23 | module-path 24 | | 'struct' [ module-items ] 'end' 25 | | 'functor' '(' module-name ':' module-type ')' '->' module-expr 26 | | module-expr '(' module-expr ')' 27 | | '(' module-expr ')' 28 | | '(' module-expr ':' module-type ')' 29 | ; 30 | module-items: 31 | {';;'} ( definition || expr ) { {';;'} ( definition || ';;' expr) } {';;'} 32 | ; 33 | %\end{syntax} \begin{syntax} 34 | definition: 35 | 'let' ['rec'] let-binding { 'and' let-binding } 36 | | 'external' value-name ':' typexpr '=' external-declaration 37 | | type-definition 38 | | exception-definition 39 | | class-definition 40 | | classtype-definition 41 | | 'module' module-name { '(' module-name ':' module-type ')' } 42 | [ ':' module-type ] \\ '=' module-expr 43 | | 'module' 'type' modtype-name '=' module-type 44 | | 'open' module-path 45 | | 'include' module-expr 46 | \end{syntax} 47 | See also the following language extensions: 48 | \hyperref[s-recursive-modules]{recursive modules}, 49 | \hyperref[s-first-class-modules]{first-class modules}, 50 | \hyperref[s:explicit-overriding-open]{overriding in open statements}, 51 | \hyperref[s:attributes]{attributes}, 52 | \hyperref[s:extension-nodes]{extension nodes} and 53 | \hyperref[s:generative-functors]{generative functors}. 54 | 55 | \subsection{Simple module expressions} 56 | 57 | The expression @module-path@ evaluates to the module bound to the name 58 | @module-path@. 59 | 60 | The expression @'(' module-expr ')'@ evaluates to the same module as 61 | @module-expr@. 62 | 63 | The expression @'(' module-expr ':' module-type ')'@ checks that the 64 | type of @module-expr@ is a subtype of @module-type@, that is, that all 65 | components specified in @module-type@ are implemented in 66 | @module-expr@, and their implementation meets the requirements given 67 | in @module-type@. In other terms, it checks that the implementation 68 | @module-expr@ meets the type specification @module-type@. The whole 69 | expression evaluates to the same module as @module-expr@, except that 70 | all components not specified in @module-type@ are hidden and can no 71 | longer be accessed. 72 | 73 | \subsection{Structures} 74 | 75 | \ikwd{struct\@\texttt{struct}} 76 | \ikwd{end\@\texttt{end}} 77 | 78 | Structures @'struct' \ldots 'end'@ are collections of definitions for 79 | value names, type names, exceptions, module names and module type 80 | names. The definitions are evaluated in the order in which they appear 81 | in the structure. The scopes of the bindings performed by the 82 | definitions extend to the end of the structure. As a consequence, a 83 | definition may refer to names bound by earlier definitions in the same 84 | structure. 85 | 86 | For compatibility with toplevel phrases (chapter~\ref{c:camllight}), 87 | optional @";;"@ are allowed after and before each definition in a structure. These 88 | @";;"@ have no semantic meanings. Similarly, an @expr@ preceded by ";;" is allowed as 89 | a component of a structure. It is equivalent to @'let' '_' '=' expr@, i.e. @expr@ is 90 | evaluated for its side-effects but is not bound to any identifier. If @expr@ is 91 | the first component of a structure, the preceding ";;" can be omitted. 92 | 93 | \subsubsection*{Value definitions} 94 | 95 | \ikwd{let\@\texttt{let}} 96 | 97 | A value definition @'let' ['rec'] let-binding { 'and' let-binding }@ 98 | bind value names in the same way as a @'let' \ldots 'in' \ldots@ expression 99 | (see section~\ref{s:localdef}). The value names appearing in the 100 | left-hand sides of the bindings are bound to the corresponding values 101 | in the right-hand sides. 102 | 103 | \ikwd{external\@\texttt{external}} 104 | 105 | A value definition @'external' value-name ':' typexpr '=' external-declaration@ 106 | implements @value-name@ as the external function specified in 107 | @external-declaration@ (see chapter~\ref{c:intf-c}). 108 | 109 | \subsubsection*{Type definitions} 110 | 111 | \ikwd{type\@\texttt{type}} 112 | 113 | A definition of one or several type components is written 114 | @'type' typedef { 'and' typedef }@ and consists of a sequence 115 | of mutually recursive definitions of type names. 116 | 117 | \subsubsection*{Exception definitions} 118 | 119 | \ikwd{exception\@\texttt{exception}} 120 | 121 | Exceptions are defined with the syntax @'exception' constr-decl@ 122 | or @'exception' constr-name '=' constr@. 123 | 124 | \subsubsection*{Class definitions} 125 | 126 | \ikwd{class\@\texttt{class}} 127 | 128 | A definition of one or several classes is written @'class' 129 | class-binding { 'and' class-binding }@ and consists of a sequence of 130 | mutually recursive definitions of class names. Class definitions are 131 | described more precisely in section~\ref{s:classdef}. 132 | 133 | \subsubsection*{Class type definitions} 134 | 135 | \ikwd{class\@\texttt{class}} 136 | \ikwd{type\@\texttt{type}} 137 | 138 | A definition of one or several classes is written 139 | @'class' 'type' classtype-def { 'and' classtype-def }@ and consists of 140 | a sequence of mutually recursive definitions of class type names. 141 | Class type definitions are described more precisely in 142 | section~\ref{s:classtype}. 143 | 144 | \subsubsection*{Module definitions} 145 | 146 | \ikwd{module\@\texttt{module}} 147 | 148 | The basic form for defining a module component is 149 | @'module' module-name '=' module-expr@, which evaluates @module-expr@ and binds 150 | the result to the name @module-name@. 151 | 152 | One can write 153 | \begin{center} 154 | @'module' module-name ':' module-type '=' module-expr@ 155 | \end{center} 156 | instead of 157 | \begin{center} 158 | @'module' module-name '=' '(' module-expr ':' module-type ')'@. 159 | \end{center} 160 | Another derived form is 161 | \begin{center} 162 | @'module' module-name '(' name_1 ':' module-type_1 ')' \ldots 163 | '(' name_n ':' module-type_n ')' '=' module-expr@ 164 | \end{center} 165 | which is equivalent to 166 | \begin{center} 167 | @'module' module-name '=' 168 | 'functor' '(' name_1 ':' module-type_1 ')' '->' \ldots 169 | '->' module-expr@ 170 | \end{center} 171 | 172 | \subsubsection*{Module type definitions} 173 | 174 | \ikwd{type\@\texttt{type}} 175 | \ikwd{module\@\texttt{module}} 176 | 177 | A definition for a module type is written 178 | @'module' 'type' modtype-name '=' module-type@. 179 | It binds the name @modtype-name@ to the module type denoted by the 180 | expression @module-type@. 181 | 182 | \subsubsection*{Opening a module path} 183 | 184 | \ikwd{open\@\texttt{open}} 185 | 186 | The expression @'open' module-path@ in a structure does not define any 187 | components nor perform any bindings. It simply affects the parsing of 188 | the following items of the structure, allowing components of the 189 | module denoted by @module-path@ to be referred to by their simple names 190 | @name@ instead of path accesses @module-path '.' name@. The scope of 191 | the @"open"@ stops at the end of the structure expression. 192 | 193 | \subsubsection*{Including the components of another structure} 194 | 195 | \ikwd{include\@\texttt{include}} 196 | 197 | The expression @'include' module-expr@ in a structure re-exports in 198 | the current structure all definitions of the structure denoted by 199 | @module-expr@. For instance, if you define a module "S" as below 200 | \begin{caml_example*}{verbatim} 201 | module S = struct type t = int let x = 2 end 202 | \end{caml_example} 203 | defining the module "B" as 204 | \begin{caml_example*}{verbatim} 205 | module B = struct include S let y = (x + 1 : t) end 206 | \end{caml_example} 207 | is equivalent to defining it as 208 | \begin{caml_example*}{verbatim} 209 | module B = struct type t = S.t let x = S.x let y = (x + 1 : t) end 210 | \end{caml_example} 211 | The difference between @'open'@ and @'include'@ is that @'open'@ 212 | simply provides short names for the components of the opened 213 | structure, without defining any components of the current structure, 214 | while @'include'@ also adds definitions for the components of the 215 | included structure. 216 | 217 | \subsection{Functors} 218 | 219 | \subsubsection*{Functor definition} 220 | 221 | \ikwd{functor\@\texttt{functor}} 222 | 223 | The expression @'functor' '(' module-name ':' module-type ')' '->' 224 | module-expr@ evaluates to a functor that takes as argument modules of 225 | the type @module-type_1@, binds @module-name@ to these modules, 226 | evaluates @module-expr@ in the extended environment, and returns the 227 | resulting modules as results. No restrictions are placed on the type of the 228 | functor argument; in particular, a functor may take another functor as 229 | argument (``higher-order'' functor). 230 | 231 | \subsubsection*{Functor application} 232 | 233 | The expression @module-expr_1 '(' module-expr_2 ')'@ evaluates 234 | @module-expr_1@ to a functor and @module-expr_2@ to a module, and 235 | applies the former to the latter. The type of @module-expr_2@ must 236 | match the type expected for the arguments of the functor @module-expr_1@. 237 | 238 | -------------------------------------------------------------------------------- /manual/library/builtin.etex: -------------------------------------------------------------------------------- 1 | \section{Built-in types and predefined exceptions} 2 | 3 | The following built-in types and predefined exceptions are always 4 | defined in the 5 | compilation environment, but are not part of any module. As a 6 | consequence, they can only be referred by their short names. 7 | 8 | %\vspace{0.1cm} 9 | \subsection*{Built-in types} 10 | %\vspace{0.1cm} 11 | 12 | \begin{ocamldoccode} 13 | type int 14 | \end{ocamldoccode} 15 | \index{int@\verb`int`} 16 | \begin{ocamldocdescription} 17 | The type of integer numbers. 18 | \end{ocamldocdescription} 19 | 20 | \begin{ocamldoccode} 21 | type char 22 | \end{ocamldoccode} 23 | \index{char@\verb`char`} 24 | \begin{ocamldocdescription} 25 | The type of characters. 26 | \end{ocamldocdescription} 27 | 28 | \begin{ocamldoccode} 29 | type bytes 30 | \end{ocamldoccode} 31 | \index{bytes@\verb`bytes`} 32 | \begin{ocamldocdescription} 33 | The type of (writable) byte sequences. 34 | \end{ocamldocdescription} 35 | 36 | \begin{ocamldoccode} 37 | type string 38 | \end{ocamldoccode} 39 | \index{string@\verb`string`} 40 | \begin{ocamldocdescription} 41 | The type of (read-only) character strings. 42 | \end{ocamldocdescription} 43 | 44 | \begin{ocamldoccode} 45 | type float 46 | \end{ocamldoccode} 47 | \index{float@\verb`float`} 48 | \begin{ocamldocdescription} 49 | The type of floating-point numbers. 50 | \end{ocamldocdescription} 51 | 52 | \begin{ocamldoccode} 53 | type bool = false | true 54 | \end{ocamldoccode} 55 | \index{bool@\verb`bool`} 56 | \begin{ocamldocdescription} 57 | The type of booleans (truth values). 58 | \end{ocamldocdescription} 59 | 60 | \begin{ocamldoccode} 61 | type unit = () 62 | \end{ocamldoccode} 63 | \index{unit@\verb`unit`} 64 | \begin{ocamldocdescription} 65 | The type of the unit value. 66 | \end{ocamldocdescription} 67 | 68 | \begin{ocamldoccode} 69 | type exn 70 | \end{ocamldoccode} 71 | \index{exn@\verb`exn`} 72 | \begin{ocamldocdescription} 73 | The type of exception values. 74 | \end{ocamldocdescription} 75 | 76 | \begin{ocamldoccode} 77 | type 'a array 78 | \end{ocamldoccode} 79 | \index{array@\verb`array`} 80 | \begin{ocamldocdescription} 81 | The type of arrays whose elements have type "'a". 82 | \end{ocamldocdescription} 83 | 84 | \begin{ocamldoccode} 85 | type 'a list = [] | :: of 'a * 'a list 86 | \end{ocamldoccode} 87 | \index{list@\verb`list`} 88 | \begin{ocamldocdescription} 89 | The type of lists whose elements have type "'a". 90 | \end{ocamldocdescription} 91 | 92 | \begin{ocamldoccode} 93 | type 'a option = None | Some of 'a 94 | \end{ocamldoccode} 95 | \index{option@\verb`option`} 96 | \begin{ocamldocdescription} 97 | The type of optional values of type "'a". 98 | \end{ocamldocdescription} 99 | 100 | \begin{ocamldoccode} 101 | type int32 102 | \end{ocamldoccode} 103 | \index{int32@\verb`int32`} 104 | \begin{ocamldocdescription} 105 | The type of signed 32-bit integers. 106 | Literals for 32-bit integers are suffixed by l. 107 | See the "Int32"[\moduleref{Int32}] module. 108 | \end{ocamldocdescription} 109 | 110 | \begin{ocamldoccode} 111 | type int64 112 | \end{ocamldoccode} 113 | \index{int64@\verb`int64`} 114 | \begin{ocamldocdescription} 115 | The type of signed 64-bit integers. 116 | Literals for 64-bit integers are suffixed by L. 117 | See the "Int64"[\moduleref{Int64}] module. 118 | \end{ocamldocdescription} 119 | 120 | \begin{ocamldoccode} 121 | type nativeint 122 | \end{ocamldoccode} 123 | \index{nativeint@\verb`nativeint`} 124 | \begin{ocamldocdescription} 125 | The type of signed, platform-native integers (32 bits on 32-bit 126 | processors, 64 bits on 64-bit processors). 127 | Literals for native integers are suffixed by n. 128 | See the "Nativeint"[\moduleref{Nativeint}] module. 129 | \end{ocamldocdescription} 130 | 131 | \begin{ocamldoccode} 132 | type ('a, 'b, 'c, 'd, 'e, 'f) format6 133 | \end{ocamldoccode} 134 | \index{format4@\verb`format4`} 135 | \begin{ocamldocdescription} 136 | The type of format strings. "'a" is the type of the parameters of 137 | the format, "'f" is the result type for the "printf"-style 138 | functions, "'b" is the type of the first argument given to "%a" and 139 | "%t" printing functions (see module "Printf"[\moduleref{Printf}]), 140 | "'c" is the result type of these functions, and also the type of the 141 | argument transmitted to the first argument of "kprintf"-style 142 | functions, "'d" is the result type for the "scanf"-style functions 143 | (see module "Scanf"[\moduleref{Scanf}]), 144 | and "'e" is the type of the receiver function for the "scanf"-style 145 | functions. 146 | \end{ocamldocdescription} 147 | 148 | \begin{ocamldoccode} 149 | type 'a lazy_t 150 | \end{ocamldoccode} 151 | \index{lazyt@\verb`lazy_t`} 152 | \begin{ocamldocdescription} 153 | This type is used to implement the "Lazy"[\moduleref{Lazy}] module. 154 | It should not be used directly. 155 | \end{ocamldocdescription} 156 | 157 | %\vspace{0.1cm} 158 | \subsection*{Predefined exceptions} 159 | %\vspace{0.1cm} 160 | 161 | \begin{ocamldoccode} 162 | exception Match_failure of (string * int * int) 163 | \end{ocamldoccode} 164 | \index{Matchfailure@\verb`Match_failure`} 165 | \begin{ocamldocdescription} 166 | Exception raised when none of the cases of a pattern-matching 167 | apply. The arguments are the location of the "match" keyword 168 | in the source code (file name, line number, column number). 169 | \end{ocamldocdescription} 170 | 171 | \begin{ocamldoccode} 172 | exception Assert_failure of (string * int * int) 173 | \end{ocamldoccode} 174 | \index{Assertfailure@\verb`Assert_failure`} 175 | \begin{ocamldocdescription} 176 | Exception raised when an assertion fails. The arguments are 177 | the location of the "assert" keyword in the source code 178 | (file name, line number, column number). 179 | \end{ocamldocdescription} 180 | 181 | \begin{ocamldoccode} 182 | exception Invalid_argument of string 183 | \end{ocamldoccode} 184 | \index{Invalidargument@\verb`Invalid_argument`} 185 | \begin{ocamldocdescription} 186 | Exception raised by library functions to signal that the given 187 | arguments do not make sense. The string gives some information 188 | to the programmer. As a general rule, this exception should not 189 | be caught, it denotes a programming error and the code should be 190 | modified not to trigger it. 191 | \end{ocamldocdescription} 192 | 193 | \begin{ocamldoccode} 194 | exception Failure of string 195 | \end{ocamldoccode} 196 | \index{Failure@\verb`Failure`} 197 | \begin{ocamldocdescription} 198 | Exception raised by library functions to signal that they are 199 | undefined on the given arguments. The string is meant to give some 200 | information to the programmer; you must \emph{not} pattern match on 201 | the string literal because it may change in future versions (use 202 | \verb`Failure _` instead). 203 | \end{ocamldocdescription} 204 | 205 | \begin{ocamldoccode} 206 | exception Not_found 207 | \end{ocamldoccode} 208 | \index{Notfound@\verb`Not_found`} 209 | \begin{ocamldocdescription} 210 | Exception raised by search functions when the desired object 211 | could not be found. 212 | \end{ocamldocdescription} 213 | 214 | \begin{ocamldoccode} 215 | exception Out_of_memory 216 | \end{ocamldoccode} 217 | \index{Outofmemory@\verb`Out_of_memory`} 218 | \begin{ocamldocdescription} 219 | Exception raised by the garbage collector 220 | when there is insufficient memory to complete the computation. 221 | \end{ocamldocdescription} 222 | 223 | \begin{ocamldoccode} 224 | exception Stack_overflow 225 | \end{ocamldoccode} 226 | \index{Stackoverflow@\verb`Stack_overflow`} 227 | \begin{ocamldocdescription} 228 | Exception raised by the bytecode interpreter when the evaluation 229 | stack reaches its maximal size. This often indicates infinite 230 | or excessively deep recursion in the user's program. 231 | (Not fully implemented by the native-code compiler; 232 | see section~\ref{s:compat-native-bytecode}.) 233 | \end{ocamldocdescription} 234 | 235 | \begin{ocamldoccode} 236 | exception Sys_error of string 237 | \end{ocamldoccode} 238 | \index{Syserror@\verb`Sys_error`} 239 | \begin{ocamldocdescription} 240 | Exception raised by the input/output functions to report an 241 | operating system error. The string is meant to give some 242 | information to the programmer; you must \emph{not} pattern match on 243 | the string literal because it may change in future versions (use 244 | \verb`Sys_error _` instead). 245 | \end{ocamldocdescription} 246 | 247 | \begin{ocamldoccode} 248 | exception End_of_file 249 | \end{ocamldoccode} 250 | \index{Endoffile@\verb`End_of_file`} 251 | \begin{ocamldocdescription} 252 | Exception raised by input functions to signal that the 253 | end of file has been reached. 254 | \end{ocamldocdescription} 255 | 256 | \begin{ocamldoccode} 257 | exception Division_by_zero 258 | \end{ocamldoccode} 259 | \index{Divisionbyzero@\verb`Division_by_zero`} 260 | \begin{ocamldocdescription} 261 | Exception raised by integer division and remainder operations 262 | when their second argument is zero. 263 | \end{ocamldocdescription} 264 | 265 | \begin{ocamldoccode} 266 | exception Sys_blocked_io 267 | \end{ocamldoccode} 268 | \index{Sysblockedio@\verb`Sys_blocked_io`} 269 | \begin{ocamldocdescription} 270 | A special case of "Sys_error" raised when no I/O is possible 271 | on a non-blocking I/O channel. 272 | \end{ocamldocdescription} 273 | 274 | \begin{ocamldoccode} 275 | exception Undefined_recursive_module of (string * int * int) 276 | \end{ocamldoccode} 277 | \index{Undefinedrecursivemodule@\verb`Undefined_recursive_module`} 278 | \begin{ocamldocdescription} 279 | Exception raised when an ill-founded recursive module definition 280 | is evaluated. (See section~\ref{s-recursive-modules}.) 281 | The arguments are the location of the definition in the source code 282 | (file name, line number, column number). 283 | \end{ocamldocdescription} 284 | 285 | -------------------------------------------------------------------------------- /manual/refman/types.etex: -------------------------------------------------------------------------------- 1 | \section{Type expressions} 2 | %HEVEA\cutname{types.html} 3 | \ikwd{as\@\texttt{as}} 4 | 5 | \begin{syntax} 6 | typexpr: 7 | "'" ident 8 | | "_" 9 | | '(' typexpr ')' 10 | | [['?']label-name':'] typexpr '->' typexpr 11 | | typexpr {{ '*' typexpr }} 12 | | typeconstr 13 | | typexpr typeconstr 14 | | '(' typexpr { ',' typexpr } ')' typeconstr 15 | | typexpr 'as' "'" ident 16 | | polymorphic-variant-type 17 | | '<' ['..'] '>' 18 | | '<' method-type { ';' method-type } [';' || ';' '..'] '>' 19 | | '#' class-path 20 | | typexpr '#' class-path 21 | | '(' typexpr { ',' typexpr } ')' '#' class-path 22 | ; 23 | poly-typexpr: 24 | typexpr 25 | | {{ "'" ident }} '.' typexpr 26 | ; 27 | method-type: 28 | method-name ':' poly-typexpr 29 | \end{syntax} 30 | See also the following language extensions: 31 | \hyperref[s-first-class-modules]{first-class modules}, 32 | \hyperref[s:attributes]{attributes} and 33 | \hyperref[s:extension-nodes]{extension nodes}. 34 | 35 | The table below shows the relative precedences and associativity of 36 | operators and non-closed type constructions. The constructions with 37 | higher precedences come first. 38 | \ikwd{as\@\texttt{as}} 39 | \begin{tableau}{|l|l|}{Operator}{Associativity} 40 | \entree{Type constructor application}{--} 41 | \entree{"#"}{--} 42 | \entree{"*"}{--} 43 | \entree{"->"}{right} 44 | \entree{"as"}{--} 45 | \end{tableau} 46 | 47 | Type expressions denote types in definitions of data types as well as 48 | in type constraints over patterns and expressions. 49 | 50 | \subsubsection*{Type variables} 51 | 52 | The type expression @"'" ident@ stands for the type variable named 53 | @ident@. The type expression @"_"@ stands for either an anonymous type 54 | variable or anonymous type parameters. In data type definitions, type 55 | variables are names for the data type parameters. In type constraints, 56 | they represent unspecified types that can be instantiated by any type 57 | to satisfy the type constraint. In general the scope of a named type 58 | variable is the whole top-level phrase where it appears, and it can 59 | only be generalized when leaving this scope. Anonymous variables have 60 | no such restriction. In the following cases, the scope of named type 61 | variables is restricted to the type expression where they appear: 62 | 1) for universal (explicitly polymorphic) type variables; 63 | 2) for type variables that only appear in public method specifications 64 | (as those variables will be made universal, as described in 65 | section~\ref{sec-methspec}); 66 | 3) for variables used as aliases, when the type they are aliased to 67 | would be invalid in the scope of the enclosing definition ({\it i.e.} 68 | when it contains free universal type variables, or locally 69 | defined types.) 70 | 71 | \subsubsection*{Parenthesized types} 72 | 73 | The type expression @"(" typexpr ")"@ denotes the same type as 74 | @typexpr@. 75 | 76 | \subsubsection*{Function types} 77 | 78 | The type expression @typexpr_1 '->' typexpr_2@ denotes the type of 79 | functions mapping arguments of type @typexpr_1@ to results of type 80 | @typexpr_2@. 81 | 82 | @label-name ':' typexpr_1 '->' typexpr_2@ denotes the same function type, but 83 | the argument is labeled @label@. 84 | 85 | @'?' label-name ':' typexpr_1 '->' typexpr_2@ denotes the type of functions 86 | mapping an optional labeled argument of type @typexpr_1@ to results of 87 | type @typexpr_2@. That is, the physical type of the function will be 88 | @typexpr_1 "option" '->' typexpr_2@. 89 | 90 | \subsubsection*{Tuple types} 91 | 92 | The type expression @typexpr_1 '*' \ldots '*' typexpr_n@ 93 | denotes the type of tuples whose elements belong to types @typexpr_1, 94 | \ldots typexpr_n@ respectively. 95 | 96 | \subsubsection*{Constructed types} 97 | 98 | Type constructors with no parameter, as in @typeconstr@, are type 99 | expressions. 100 | 101 | The type expression @typexpr typeconstr@, where @typeconstr@ is a type 102 | constructor with one parameter, denotes the application of the unary type 103 | constructor @typeconstr@ to the type @typexpr@. 104 | 105 | The type expression @(typexpr_1,\ldots,typexpr_n) typeconstr@, where 106 | @typeconstr@ is a type constructor with $n$ parameters, denotes the 107 | application of the $n$-ary type constructor @typeconstr@ to the types 108 | @typexpr_1@ through @typexpr_n@. 109 | 110 | In the type expression @ "_" typeconstr @, the anonymous type expression 111 | @ "_" @ stands in for anonymous type parameters and is equivalent to 112 | @ ("_", \ldots,"_") @ with as many repetitions of "_" as the arity of 113 | @typeconstr@. 114 | 115 | \subsubsection*{Aliased and recursive types} 116 | 117 | \ikwd{as\@\texttt{as}} 118 | 119 | The type expression @typexpr 'as' "'" ident@ denotes the same type as 120 | @typexpr@, and also binds the type variable @ident@ to type @typexpr@ both 121 | in @typexpr@ and in other types. In general the scope of an alias is 122 | the same as for a named type variable, and covers the whole enclosing 123 | definition. If the type variable 124 | @ident@ actually occurs in @typexpr@, a recursive type is created. Recursive 125 | types for which there exists a recursive path that does not contain 126 | an object or polymorphic variant type constructor are rejected, except 127 | when the "-rectypes" mode is selected. 128 | 129 | If @"'" ident@ denotes an explicit polymorphic variable, and @typexpr@ 130 | denotes either an object or polymorphic variant type, the row variable 131 | of @typexpr@ is captured by @"'" ident@, and quantified upon. 132 | 133 | \subsubsection*{Polymorphic variant types} 134 | \ikwd{of\@\texttt{of}} 135 | 136 | \begin{syntax} 137 | polymorphic-variant-type: 138 | '[' tag-spec-first { '|' tag-spec } ']' 139 | | '[>' [ tag-spec ] { '|' tag-spec } ']' 140 | | '[<' ['|'] tag-spec-full { '|' tag-spec-full } 141 | [ '>' {{ '`'tag-name }} ] ']' 142 | ; 143 | %\end{syntax} \begin{syntax} 144 | tag-spec-first: 145 | '`'tag-name [ 'of' typexpr ] 146 | | [ typexpr ] '|' tag-spec 147 | ; 148 | tag-spec: 149 | '`'tag-name [ 'of' typexpr ] 150 | | typexpr 151 | ; 152 | tag-spec-full: 153 | '`'tag-name [ 'of' ['&'] typexpr { '&' typexpr } ] 154 | | typexpr 155 | \end{syntax} 156 | 157 | Polymorphic variant types describe the values a polymorphic variant 158 | may take. 159 | 160 | The first case is an exact variant type: all possible tags are 161 | known, with their associated types, and they can all be present. 162 | Its structure is fully known. 163 | 164 | The second case is an open variant type, describing a polymorphic 165 | variant value: it gives the list of all tags the value could take, 166 | with their associated types. This type is still compatible with a 167 | variant type containing more tags. A special case is the unknown 168 | type, which does not define any tag, and is compatible with any 169 | variant type. 170 | 171 | The third case is a closed variant type. It gives information about 172 | all the possible tags and their associated types, and which tags are 173 | known to potentially appear in values. The exact variant type (first 174 | case) is 175 | just an abbreviation for a closed variant type where all possible tags 176 | are also potentially present. 177 | 178 | In all three cases, tags may be either specified directly in the 179 | @'`'tag-name ["of" typexpr]@ form, or indirectly through a type 180 | expression, which must expand to an 181 | exact variant type, whose tag specifications are inserted in its 182 | place. 183 | 184 | Full specifications of variant tags are only used for non-exact closed 185 | types. They can be understood as a conjunctive type for the argument: 186 | it is intended to have all the types enumerated in the 187 | specification. 188 | 189 | Such conjunctive constraints may be unsatisfiable. In such a case the 190 | corresponding tag may not be used in a value of this type. This 191 | does not mean that the whole type is not valid: one can still use 192 | other available tags. 193 | Conjunctive constraints are mainly intended as output from the type 194 | checker. When they are used in source programs, unsolvable constraints 195 | may cause early failures. 196 | 197 | \subsubsection*{Object types} 198 | 199 | An object type 200 | @'<' [method-type { ';' method-type }] '>'@ 201 | is a record of method types. 202 | 203 | Each method may have an explicit polymorphic type: @{{ "'" ident }} 204 | '.' typexpr@. Explicit polymorphic variables have a local scope, and 205 | an explicit polymorphic type can only be unified to an 206 | equivalent one, where only the order and names of polymorphic 207 | variables may change. 208 | 209 | The type @'<' {method-type ';'} '..' '>'@ is the 210 | type of an object whose method names and types are described by 211 | @method-type_1, \ldots, method-type_n@, and possibly some other 212 | methods represented by the ellipsis. This ellipsis actually is 213 | a special kind of type variable (called {\em row variable} in the 214 | literature) that stands for any number of extra method types. 215 | 216 | \subsubsection*{\#-types} 217 | \label{s:sharp-types} 218 | 219 | The type @'#' class-path@ is a special kind of abbreviation. This 220 | abbreviation unifies with the type of any object belonging to a subclass 221 | of class @class-path@. 222 | % 223 | It is handled in a special way as it usually hides a type variable (an 224 | ellipsis, representing the methods that may be added in a subclass). 225 | In particular, it vanishes when the ellipsis gets instantiated. 226 | % 227 | Each type expression @'#' class-path@ defines a new type variable, so 228 | type @'#' class-path '->' '#' class-path@ is usually not the same as 229 | type @('#' class-path 'as' "'" ident) '->' "'" ident@. 230 | % 231 | 232 | Use of \#-types to abbreviate polymorphic variant types is deprecated. 233 | If @@t@@ is an exact variant type then @"#"@t@@ translates to @"[<" @t@"]"@, 234 | and @"#"@t@"[>" "`"tag_1 \dots"`"tag_k"]"@ translates to 235 | @"[<" @t@ ">" "`"tag_1 \dots"`"tag_k"]"@ 236 | 237 | \subsubsection*{Variant and record types} 238 | 239 | There are no type expressions describing (defined) variant types nor 240 | record types, since those are always named, i.e. defined before use 241 | and referred to by name. Type definitions are described in 242 | section~\ref{s:type-defs}. 243 | -------------------------------------------------------------------------------- /manual/biblio.etex: -------------------------------------------------------------------------------- 1 | \chapter{Further reading} 2 | 3 | For the interested reader, we list below some references to books and 4 | reports related (sometimes loosely) to Caml Light. 5 | 6 | \section{Programming in ML} 7 | 8 | The books below are programming courses taught in ML. Their main goal 9 | is to teach programming, not to describe ML in full details --- though 10 | most contain fairly good introductions to the ML language. Some of 11 | those books use the Standard ML dialect instead of the Caml dialect, 12 | so you will have to keep in mind the differences in syntax and in 13 | semantics. 14 | 15 | \begin{itemize} 16 | 17 | \item Pierre Weis and Xavier Leroy. {\it Le langage Caml.} 18 | InterÉditions, 1993. 19 | 20 | The natural companion to this manual, provided you read French. This 21 | book is a step-by-step introduction to programming in Caml, and 22 | presents many realistic examples of Caml programs. 23 | 24 | \item Guy Cousineau and Michel Mauny. {\it Approche fonctionnelle de 25 | la programmation}. Ediscience, 1995. 26 | 27 | Another Caml programming course written in French, with many original 28 | examples. 29 | 30 | \item Lawrence C.\ Paulson. {\it ML for the working programmer.} 31 | Cambridge University Press, 1991. 32 | 33 | A good introduction to programming in Standard ML. Develops a 34 | theorem prover as a complete example. Contains a presentation of 35 | the module system of Standard ML. 36 | 37 | \item Jeffrey D.\ Ullman. {\it Elements of ML programming.} 38 | Prentice Hall, 1993. 39 | 40 | Another good introduction to programming in Standard ML. No realistic 41 | examples, but a very detailed presentation of the language constructs. 42 | 43 | \item Ryan Stansifer. {\em ML primer.} Prentice-Hall, 1992. 44 | 45 | A short, but nice introduction to programming in Standard ML. 46 | 47 | \item Thérèse Accart Hardin and Véronique Donzeau-Gouge Viguié. {\em 48 | Concepts et outils de la programmation. Du fonctionnel à 49 | l'impératif avec Caml et Ada.} InterÉditions, 1992. 50 | 51 | A first course in programming, that first introduces the main programming 52 | notions in Caml, then shows them underlying Ada. Intended for 53 | beginners; slow-paced for the others. 54 | 55 | \item Rachel Harrison. {\em Abstract Data Types in Standard ML}. 56 | John Wiley \& Sons, 1993. 57 | 58 | A presentation of Standard ML from the standpoint of abstract data 59 | types. Uses intensively the Standard ML module system. 60 | 61 | \item Harold Abelson and Gerald Jay Sussman. 62 | {\em Structure and Interpretation of Computer Programs.} The MIT 63 | press, 1985. (French translation: {\em Structure et interprétation 64 | des programmes informatiques}, InterÉditions, 1989.) 65 | 66 | An outstanding course on programming, taught in Scheme, the modern 67 | dialect of Lisp. Well worth reading, even if you are more interested 68 | in ML than in Lisp. 69 | 70 | \end{itemize} 71 | 72 | \section{Descriptions of ML dialects} 73 | 74 | The books and reports below are descriptions of various programming 75 | languages from the ML family. They assume some familiarity with ML. 76 | 77 | \begin{itemize} 78 | 79 | \item Xavier Leroy and Pierre Weis. {\em Manuel de référence du 80 | langage Caml.} InterÉditions, 1993. 81 | 82 | The French edition of the present reference manual and user's manual. 83 | 84 | \item Robert Harper. {\em Introduction to Standard ML.} Technical 85 | report ECS-LFCS-86-14, University of Edinburgh, 1986. 86 | 87 | An overview of Standard ML, including the module system. Terse, but 88 | still readable. 89 | 90 | \item Robin Milner, Mads Tofte and Robert Harper. {\em The definition 91 | of Standard ML.} The MIT press, 1990. 92 | 93 | A complete formal definition of Standard ML, in the framework of 94 | structured operational semantics. This book is probably the most 95 | mathematically precise definition of a programming language ever 96 | written. It is heavy on formalism and extremely terse, so 97 | even readers who are thoroughly familiar with ML will have 98 | major difficulties with it. 99 | 100 | \item Robin Milner and Mads Tofte. {\em Commentary on Standard ML.} 101 | The MIT Press, 1991. 102 | 103 | A commentary on the book above, that attempts to explain the most 104 | delicate parts and motivate the design choices. Easier to read than the 105 | Definition, but still rather involving. 106 | 107 | \item Guy Cousineau and Gérard Huet. {\em The CAML primer.} Technical 108 | report~122, INRIA, 1990. 109 | 110 | A short description of the original Caml system, from which Caml Light 111 | has evolved. Some familiarity with Lisp is assumed. 112 | 113 | \item Pierre Weis et al. {\em The CAML reference manual, version 114 | 2.6.1.} Technical report~121, INRIA, 1990. 115 | 116 | The manual for the original Caml system, from which Caml Light 117 | has evolved. 118 | 119 | \item Michael J.\ Gordon, Arthur J.\ Milner and Christopher P.\ Wadsworth. 120 | {\em Edinburgh LCF.} Lecture Notes in Computer Science 121 | volume~78, Springer-Verlag, 1979. 122 | 123 | This is the first published description of the ML language, at the 124 | time when it was nothing more than the control language for the LCF 125 | system, a theorem prover. This book is now obsolete, since the ML 126 | language has much evolved since then; but it is still of historical 127 | interest. 128 | 129 | \item Paul Hudak, Simon Peyton-Jones and Philip Wadler. {\em 130 | Report on the programming language Haskell, version 1.1.} Technical 131 | report, Yale University, 1991. 132 | 133 | Haskell is a purely functional language with lazy semantics that 134 | shares many important points with ML (full functionality, polymorphic 135 | typing), but has interesting features of its own (dynamic overloading, 136 | also called type classes). 137 | 138 | \end{itemize} 139 | 140 | \section{Implementing functional programming languages} 141 | 142 | The references below are intended for those who are curious to learn 143 | how a language like Caml Light is compiled and implemented. 144 | 145 | \begin{itemize} 146 | 147 | \item Xavier Leroy. {\em The ZINC experiment: an economical 148 | implementation of the ML language.} Technical report~117, INRIA, 1990. 149 | (Available by anonymous FTP on "ftp.inria.fr".) 150 | 151 | A description of the ZINC implementation, the prototype ML 152 | implementation that has evolved into Caml Light. Large parts of this 153 | report still apply to the current Caml Light system, in particular the 154 | description of the execution model and abstract machine. Other parts 155 | are now obsolete. Yet this report still gives a complete overview of the 156 | implementation techniques used in Caml Light. 157 | 158 | \item Simon Peyton-Jones. {\em The implementation of functional 159 | programming languages.} Prentice-Hall, 1987. (French translation: 160 | {\em Mise en \oe uvre des langages fonctionnels de programmation}, 161 | Masson, 1990.) 162 | 163 | An excellent description of the implementation of purely functional 164 | languages with lazy semantics, using the technique known as graph 165 | reduction. The part of the book that deals with the transformation 166 | from ML to enriched lambda-calculus directly applies to Caml Light. 167 | You will find a good description of how pattern-matching is compiled 168 | and how types are inferred. The remainder of the book does not apply 169 | directly to Caml Light, since Caml Light is not purely functional (it 170 | has side-effects), has strict semantics, and does not use graph 171 | reduction at all. 172 | 173 | \item Andrew W.\ Appel. {\em Compiling with continuations.} Cambridge 174 | University Press, 1992. 175 | 176 | A complete description of an optimizing compiler for Standard ML, 177 | based on an intermediate representation called continuation-passing 178 | style. Shows how many advanced program optimizations can be applied to 179 | ML. Not directly relevant to the Caml Light system, since Caml Light 180 | does not use continuation-passing style at all, and makes little 181 | attempts at optimizing programs. 182 | 183 | \end{itemize} 184 | 185 | \section{Applications of ML} 186 | 187 | The following reports show ML at work in various, sometimes 188 | unexpected, areas. 189 | 190 | \begin{itemize} 191 | 192 | \item Emmanuel Chailloux and Guy Cousineau. {\em The MLgraph primer.} 193 | Technical report 92-15, École Normale Supérieure, 1992. (Available by 194 | anonymous FTP on "ftp.ens.fr".) 195 | %, répertoire "biblio", fichier 196 | % "liens-92-15.A4.300dpi.ps.Z".) 197 | 198 | Describes a Caml Light library that produces Postscript pictures 199 | through high-level drawing functions. 200 | 201 | \item Xavier Leroy. {\em Programmation du système Unix en Caml Light.} 202 | Technical report~147, INRIA, 1992. (Available by anonymous FTP on 203 | "ftp.inria.fr".) 204 | %, répertoire "INRIA/publication", fichier "RT-0147.ps.Z".) 205 | 206 | A Unix systems programming course, demonstrating the use of the Caml 207 | Light library that gives access to Unix system calls. 208 | 209 | \item John H.\ Reppy. {\em Concurrent programming with events --- The 210 | concurrent ML manual.} Cornell University, 1990. 211 | (Available by anonymous FTP on "research.att.com".) 212 | %, répertoire "dist/ml", fichier "CML-0.9.8.tar.Z".) 213 | 214 | Concurrent ML extends Standard ML of New Jersey with concurrent 215 | processes that communicate through channels and events. 216 | 217 | \item Jeannette M. Wing, Manuel Faehndrich, J.\ Gregory Morrisett and 218 | Scottt Nettles. {\em Extensions to Standard ML to support 219 | transactions.} Technical report CMU-CS-92-132, Carnegie-Mellon 220 | University, 1992. (Available by anonymous FTP on 221 | "reports.adm.cs.cmu.edu".) 222 | % , répertoire "1992", fichier "CMU-CS-92-132.ps".) 223 | 224 | How to integrate the basic database operations to Standard ML. 225 | 226 | \item Emden R.\ Gansner and John H.\ Reppy. {\em eXene.} Bell Labs, 227 | 1991. (Available by anonymous FTP on "research.att.com".) 228 | %, répertoire "dist/ml", fichier "eXene-0.4.tar.Z".) 229 | 230 | An interface between Standard ML of New Jersey and the X Windows 231 | windowing system. 232 | 233 | %% \item Daniel de Rauglaudre. {\em X toolkit in Caml Light.} INRIA, 234 | %% 1992. (Included in the Caml Light distribution.) 235 | %% % Disponible par FTP anonyme sur 236 | %% % "ftp.inria.fr", répertoire "lang/caml-light", fichier "rt5.tar.Z".) 237 | %% 238 | %% An interface between Caml Light and the X Windows windowing system. 239 | 240 | \end{itemize} 241 | --------------------------------------------------------------------------------