OCaml — now with on-line help
November 6, 2008 § 5 Comments
I’m happy to tell you that the on-line help system for the OCaml toplevel has just been committed to our new git repository.
So what does this mean?
Let’s take a look at a sample session:
$ rlwrap ocamlfind batteries/ocaml Objective Caml version 3.10.2 ---------------------------------------------- | | | This is OCaml, Batteries Included. | | | | | | If you need help, type '#help;;' | | | ---------------------------------------------- Camlp4 Parsing version 3.10.2
We can type “
#help“? Well, that’s new. Let’s type “
# #help;; Welcome to OCaml, Batteries Included. You are currently using the Toplevel of OCaml. You can think of it as a powerful graphics calculator, or as a command-line comparable to that of your operating system. It is also a nice way of learning OCaml and of testing your algorithms and programs. Notice character '#', at the start of some lines? That's called the "prompt", it means that the Toplevel is waiting for your orders. Orders can take the form of value definitions, type definitions, evaluations or directives. Value definitions let you teach OCaml new tricks. Type definitions let you teach OCaml how to understand new kinds of values informations and how to check that you're not making mistakes when using your definitions. Evaluations let you actually do something with your definitions, such as computing the result of your algorithm, but also doing more complex things such as opening applications, modifying files, or even creating websites. Any program is composed of value definitions, type definitions and evaluations. Finally, directives are not part of any program. They just let you interact with the Toplevel, for instance by loading other programs, reading the documentation, asking the Toplevel for information on existing programs, etc. Directives are easy to spot, they also start with character '#'. So, when you wrote "#help;;", that was a directive. At this point, you may be interested in the following directives: #quit;; (*Use this to quit OCaml. *) #use "some_file.ml";; (*Use this to load another program. *) #require "some_package";; (*Use this to load a library installed on your computer. *) #help;; (*Well, you just used that one. *) #man "some subject";; (*Read the manual on some subject. *) Oh, don't forget: each order you give to the Toplevel should end with ";;". That's how the Toplevel understands that you're done writing. Otherwise, no matter how much you write, the Toplevel assumes that you still intend to write more. If you are new to programming, now is time to write #man "the tutorial";; If you already know some other programming language, you should probably write #man "for programmers";;
Let’s take a look at this tutorial.
# #man "the tutorial";; Opening help on language construction "the tutorial" (OCaml Batteries Included)
My web browser opens the tutorial at
# #man "print_endline";; Opening help on value "print_endline" (OCaml Batteries Included)
My web browser now displays the ocamldoc-generated help of
# #man "input";; Several definitions exist for "input". This item exists as a method. For more information on "input" as a method, you may use #man_method "input";; Item "input" also exists as a type. For more information on "input" as a type, you may use #man_type "input";; Item "input" also exists as a value, with several possibilities. For more information on "input" as a value, you may use #man_value "Util.Digest.input";; #man_value "System.IO.input";; #man_value "Standard.input";; #man_value "Meta.Marshal.input";;
Nice, isn’t it?
We hope that this feature, together with the extended documentation provided with OCaml Batteries Included will prove useful for beginners and veterans alike.