Re: [Factor-talk] Factor tutorial
Thank you for the suggestions! I have started incorporating some, more to come in the next days :-) 2014-11-22 16:58 GMT+01:00 John Benediktsson mrj...@gmail.com: 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): : movie ( title director actors -- movie ) movie boa ; C: movie 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 ferrettiand...@gmail.com 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
[Factor-talk] Factor tutorial
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 is welcome - or even better, you can file pull requests! Best, Andrea -- Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server from Actuate! Instantly Supercharge Your Business Reports and Dashboards with Interactivity, Sharing, Native Excel Exports, App Integration more Get technology previously reserved for billion-dollar corporations, FREE http://pubads.g.doubleclick.net/gampad/clk?id=157005751iu=/4140/ostg.clktrk ___ Factor-talk mailing list Factor-talk@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/factor-talk
Re: [Factor-talk] Factor tutorial
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): : movie ( title director actors -- movie ) movie boa ; C: movie 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 ferrettiand...@gmail.com 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 is welcome -