Short document / tutorial on Core

[Nobuyuki Tomizawa]

Hi, all.

Are there any short (getting-started like) documents / tutorials on Core to grasp how to use each module in it?

I missed tutorial at CUFP Tokyo...

Thanks,

-- nobuyuki

[Yaron Minsky]

Not really. I'm working on a side project to do a general
introduction to OCaml based on Core, but that's a good way out. We do
have a style guide that we use internally, but I don't think that
would be of much use.

Can you give me a sense of what kinds of things you'd like help on?
There are some basic things that are both important and non-obvious,
like, you should start every project based on Core by doing:

open Core.Std

Do you have any thoughts on what kind of guidance would be helpful?

y

--
Yaron Minsky

[bob zhang]

于 11-10-7 下午2:24, Yaron Minsky 写道:

Hi, Yaron,

I checked the source code of core for fun. It would be very useful if
you could explain all the
module type signatures and the philosophy under it.

for example, what's the real world use of ('a,'b) type_class .. and like
functor Check_S0, Check_S1
...
Thanks, bob

[Yaron Minsky]

On Friday, October 7, 2011 2:44:50 PM UTC-4, bob wrote:

I checked the source code of core for fun. It would be very useful if
you could explain all the
module type signatures and the philosophy under it.

for example, what's the real world use of ('a,'b) type_class .. and like
functor Check_S0, Check_S1

I'm not sure which type_class you're talking about (and really, those should probably be referred to as type-indexed-values, rather than typeclasses.).  But the Check_s0, Check_S1 have an easy-to-explain purpose.  It's for interfaces like Map and Hashtbl that have both monomorphic (S0) and polymorphic (S1) interfaces.  These Check functors are there to check that the polymorphic and monomorphic signatures are the same except for the polymorphism difference.

[Kakadu]

Also it is interesting to me where do you use sexplib ? As a analogue
of Marshal module or something more interesting?
I think that sexplib is a most visible difference between ocaml-core
and caml-batteries.

[Yaron Minsky]

Core uses the s-expression syntax extension pretty pervasively.
S-expressions have a very different use-case from Marshal. Marshal is
very fast, unsafe (if you're not careful, unmarshal can lead to a
segfault), and produces human unreadable output.

S-expressions are much slower, but generate human readable and
tweakable output. That makes it suitable for config files and error
messages.

We also have another syntax extension that shows up throughout Core
called bin-prot. Bin-prot is a binary protocol, which is, like
marshal, fast and unreadable, but it's also safe.

Another nice fact about all of these syntax extensions is that, unlike
marshal or compare or other generic algorithms built into OCaml, you
can override them at the type level. If you don't like the
s-expression auto-generated for maps, you can create your own, which
enforces invariants of your choosing and has whatever syntax you want.
This turns out to be quite important...

y

[Nobuyuki Tomizawa]

Thank you for your reply.

I had no specific idea on what kind of documents the Core missed, but, summary of the difference from standard library will help for non-Core-user ocaml programmer like me. For example, I heard that Core prefers "option" rather than 'Not_found' exception (is this true?). So, basic usage of the library (with short description of design philosophy of the library) seems to be help.

Anyway, I'll start to read reference manual of Core to grasp it.

Thank you.

-- nobuyuki

[Yaron Minsky]

On 10/10/11 09:46, Nobuyuki Tomizawa wrote:
> Thank you for your reply.
>
> I had no specific idea on what kind of documents the Core missed,
> but, summary of the difference from standard library will help for
> non-Core-user ocaml programmer like me. For example, I heard that
> Core prefers "option" rather than 'Not_found' exception (is this
> true?).

This is absolutely true!

> So, basic usage of the library (with short description of design
> philosophy of the library) seems to be help.

Yeah, I think we should try to put together a design document for
Core. I've done some thinking about this, but we should do some more,
since it will be useful internally as well. Maybe the first form this
should take is a set of blog posts. Come to think of it, there is an
old post on our blog on this topic:

http://ocaml.janestreet.com/?q=node/28

It covers some of the issues you mention.

y

> Anyway, I'll start to read reference manual of Core to grasp it.
>
> Thank you.
>
> -- nobuyuki
>

--
Yaron Minsky

[Kakadu]

Also I'll be glad if you clarify your politics concerning using
labeled arguments. Sometimes you add labeled arguments, but sometimes
not.
For example

Core_set.subset: 'a Core_set.t -> 'a Core_set.t -> bool

I absolutely have no idea (without looking to sources) are you
checking that first arguments is subset of second or vise versa?

--
Kakadu

[Yaron Minsky]

I think that's a case where we should improve the interface! For all
our talk of consistency, we haven't gotten all of the libraries right,
and we're most likely to be inconsistent on modules that are
descended from modules in Inria's standard library.

y

--
Yaron Minsky

[Lin]

Hello Yaron,

   I'd also suggest that there should be a wiki page to explain some differences between the conventions used in core and in std-lib, or else many guys would complain about this, like what I did toay.

   Today I decided to use core for a previously std-lib based program. While core does give me quite a lot of convenience, such as `Time.format' to get handy timestamp string in my log module, I was really frustrated by the convention of returning am Option value rather than raise exception in `List.tl', `String.index`, etc.

  Also in the std-lib, the first param to functions like `List.iter'  is the func, but in core the first param is the list being operated on. -_-!!   If there could be such a wiki page as I mentioned, I'd feel much more comfortable with core.

Lin

[Yaron Minsky]

That's totally fair.  Here's a link to a blog post that covers some of these issues:

   https://ocaml.janestreet.com/?q=node/28

I'll put this on the wiki as well.

y

[David House]

On 7 January 2012 12:28, Lin <mysn...@163.com> wrote:
>   Also in the std-lib, the first param to functions like `List.iter'  is the
> func, but in core the first param is the list being operated on. -_-!!

To be precise, in Core, you can do it either way around, because the
function argument is labelled. The following are both valid:

List.iter my_list ~f:(fun x -> ...)
List.iter ~f:(fun x -> ...) my_list

[Ashish Agarwal]

In general you should not assume Core is a drop-in replacement for the std-lib. It was deliberately designed with different conventions that were felt to be better. Of course, documentation explaining common design decisions and how they differ from the std-lib wouldn't hurt.

On Sat, Jan 7, 2012 at 7:28 AM, Lin <mysn...@163.com> wrote:

[Lin]

Yeah, the specs on this page is quite clear and well reasoned. I think it should be a must-read for every newcomers to core.

[Lin]

Sure, but everything that I've googled told me core is JSC's alternative implentation of the std-lib, so it's quite natural for me as well as anybody else to assume core is  a drop-in replacement for std-lib.

[Yaron Minsky]

There is now a "resources" list at the bottom of the main page on the wiki, and it leads to a short summary of Core's coding standards, and a link to the blog post.