Hi Andrea,
Wow, great contribution!!
Some comments:
You might avoid naming your factorial word "!" or at least make a small
comment to your readers that it shadows the "!" token that is used for
comments in the code (preventing its use as comments).
IN: scratchpad ! a comment
IN: scratchpad : ! ( n -- n ) ;
IN: scratchpad ! not a comment!
One could argue that we should use a more standard "//" or "#" like other
languages, but such is some legacy decision somewhere along the way. Might
be worth changing at some point.
Also in that section, you might mention the breadth of the standard
library, your ``prod`` word is defined in the ``sequences`` vocabulary as
``product``. And is possibly more efficient because it uses a binary
reduce that for large numbers keeps more of them smaller for longer,
resulting in less bignum multiplication.
On the syntax section, it might be fun to give an example of using
SYNTAX:. I have a few on my blog to help give you some ideas:
http://re-factor.blogspot.com/2010/08/fat-arrows.html
http://re-factor.blogspot.com/2014/06/swift-ranges.html
http://re-factor.blogspot.com/2010/07/rolling-dice.html
It's a useful beginner lesson to teach that Factor is "tokens that parse"
and that "{" isn't just some list literal embedded in the language, but
that you can see how it works, change it, or replace it, or build it
yourself as an addon. A small exception to that might be number and string
literals which right now are built directly into the parser.
On the github.tutorial section, I would also suggest mentioning our editor
support works for vocabularies, so for example after doing
``scaffold-work``, you might just type:
IN: scratchpad "github.tutorial" edit
For new users, this will prompt with a list of editors to choose from
(rather than needing to explicitly USE: it like you do in the tutorial).
After that point, it will open the file directly in the editor. For words,
it opens the file they are defined in (``\ foo where`` if you're curious
how that works) and tries in most editors to bring the cursor to the proper
line number.
You can also use ``"vocab" edit-tests`` to get to the tests file, ``"vocab"
edit-docs`` to open the documentation file, etc.
When you mention ``boa`` constructors, you might also demonstrate that
these are equivalent (allowing easy generation of constructor words for the
common case):
: ( title director actors -- movie ) movie boa ;
C: movie
Since Factor parses tokens between one or more whitespace characters, these
are equivalent if you prefer the second for readability:
TUPLE: band { keyboards string read-only } { guitar string read-only }
{ bass string read-only } { drums string read-only } ;
TUPLE: band
{ keyboards string read-only }
{ guitar string read-only }
{ bass string read-only }
{ drums string read-only } ;
For your later prime example with fry quotations, I'd also provide this
example which uses ``with`` to capture the notion of currying something
under the stack in this use case:
: prime? ( n -- ? ) 2 over sqrt [a,b] [ divisor? ] with any? not ;
Your ``safe-head`` word can be captured instead of using exceptions and
recover, by just doing ``short head`` which mins with length of sequence
(avoiding the exception, unless ``n`` is negative).
Good http examples, I'd also point you to this post which shows some use of
forms and validation:
http://re-factor.blogspot.com/2010/08/hello-web.html
Looks like you've put a lot of effort into this and I love it, great job!
I'm going to make a post linking to this on my blog!
Best,
John.
On Sat, Nov 22, 2014 at 6:36 AM, Andrea Ferretti
wrote:
> Hello,
>
> I have written a Factor tutorial, which you can find at
>
> http://andreaferretti.github.io/factor-tutorial/
>
> (source https://github.com/andreaferretti/factor-tutorial )
>
> Factor has a lot of documentation in the listener, but I have tried to
> cover some topics that are present in the official docs, but scattered
> throughout it, so that they were not clear to me at the beginning.
> These include for instance:
>
> - the central concept is function composition, the stack is more of a
> detail
> - how simple is to deploy program and scripts
> - what tools are there: linter, inspector, unit testing support,
> reverse lookup of function uses...
> - what model of multithreading and async I/O are used
> - how to make use of multiple cores
> - in what sense Factor has an object system
> and more
>
> I was able to answer some of those - especially multithreading -
> thanks to the help I got on this list.
>
> I am sure there are many mistakes - after all, I am still a beginner
> with Factor - and many things that can be improved, both in the
> exposition and in the choice of examples. But I wanted to get it out
> eventually, even with something to be retouched later.
>
> I intend to improve it in the future, and any suggestion
