guile-tutorial/tutorial.skb

;;; Having fun with Guile: a tutorial
;;; Copyright (C) 2015 Christopher Allan Webber <cwebber@dustycloud.org>
;;;
;;; This program is free software: you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation, either version 3 of
;;; the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;; GNU Lesser General Public License for more details.
;;; 
;;; You should have received a copy of the GNU Lesser General Public License
;;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
;;;
;;; ... This tutorial is also optionally licensed, at your option,
;;; under the GNU Free Documentation License, Version 1.3
;;; or any later version published by the Free Software Foundation;
;;; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

(use-modules (skribilo source lisp))

(define doc-title [Having fun with Guile: a tutorial])
(define repo-url [https://notabug.org/cwebber/guile-tutorial])

(document
 :title doc-title
 :html-title doc-title

 ;;; Intro
 ;;; =====
 (chapter
  :title [Introductions]
  ;; TODO: Hello world image here

  (p [Hello!
      Welcome to
        ,(ref :url [https://www.gnu.org/software/guile/] :text [Guile]),
        and this little Guile tutorial!
      If you've been interested in learning Guile, but don't know how
        to dive in, this is the tutorial for you.
      We don't assume any prior programming experience in this tutorial,
        but if you do have prior experience, you'll find that will
        make things much easier.])

  (p [Guile is a couple of things: it's a language in the family of Scheme and
        Lisp, and it's also a language virtual machine on which many languages
        can run.
      The goal of this tutorial is to introduce you to the Scheme style
        language that Guile provides (or in other words, "Guile Scheme").])

  (p [There are many languages to choose from these days, but we hope you'll
        find that Guile has some special things to offer.
      Guile is "multi-paradigm", this means that if you can choose between
        imperative object-oriented style or pure functional programming style,
        or a variety of other techniques.
      (And if you don't know what that means, playing with Guile is a great
        way to learn!)
      Guile comes with many useful features built-in, and has a variety
        of libraries you can use to build anything from games to
        interactive websites.
      And if you've ever wanted to learn how programming languages work
        or ever wanted to tune them to your purposes, Guile is a great fit;
        you can easily peek inside to see what's going on and even easily
        add new language features.
      We think that's pretty neat!])

  (p [At its best, Guile is a playground full of wonderful things to explore.
      As such, many of the metaphors we use in this tutorial are based
        around playing with toys.
      We hope you learn a lot, and most importantly, have fun doing so.]))

 ;;; - Getting up and running
 ;;;   (picture of one of those robots with a wind-up-toy-key on its back?)
 (chapter
  :title [Getting up and running]
  (include "up-and-running.skb"))

 ;;;   Much like The Little Schemer uses food as variable names, I think
 ;;;   it's a good idea to stick with abstract fun concepts.  Here, I think
 ;;;   it would be great to continue along with the "Guile is a playground,
 ;;;   come play!" idea by using toys as variable names, and defining
 ;;;   procedures that evoke nostalgia for older programmers and sound
 ;;;   playful for younger ones.
 ;;;
 ;;;   Some ideas:
 ;;;     + could use building lists as putting toys in and out of a toy
 ;;;       chest
 ;;;
 ;;;       (define toy-chest '(robot teddy-bear doll-with-comb toy-soldier))
 ;;;
 ;;;     + could have a simple-bake-oven set of procedures that takes
 ;;;       arguments like flavor and dessert-type:
 ;;;
 ;;;         #> (define (simple-bake-oven flavor dessert-type)
 ;;;              (format #f "Yum!  You made a tasty ~a flavored ~a!"
 ;;;                      flavor dessert-type))
 ;;;         #> (simple-bake-oven "banana" "cake")
 ;;;         $20 = "Yum!  You made a tasty banana flavored cake!"
 ;;;
 ;;;       and then we can increase the advanced features a bit:
 ;;;
 ;;;         #> (define* (fancy-bake-oven flavor dessert-type
 ;;;                                     #:optional topping)
 ;;;              (if topping
 ;;;                  (format #f "Yum!  You made a tasty ~a flavored ~a covered in ~a!"
 ;;;                          flavor dessert-type topping)
 ;;;                  (format #f "Yum!  You made a tasty ~a flavored ~a!"
 ;;;                          flavor dessert-type)))
 ;;;         #> (fancy-bake-oven "mint" "ice cream" "chocolate fudge")
 ;;;         $21 = "Yum!  You made a tasty mint flavored ice cream covered in chocolate fudge!"
 ;;;
 ;;;       Yes... the fancy bake oven version is so fancy it can even bake
 ;;;       ice cream! ;)
 ;;;
 ;;;     + Introduce modules as extensions for our robots.
 ;; - Acclimating ourselves with Scheme's syntax
 ;; - Understanding some basic types
 (chapter
  :title [Simple toys]
  (include "simple-toys.skb"))

 ;; - Simple function definition with (define)
 ;; - Advanced function definition with (define*)
 ;; - More advanced function definition
 ;; - Introduce lambda
 ;; - Let
 ;; - Introduce lexical scope
 ;; - Introduce modules
 ;; - Some complex types (hash tables, vhashes?, vectors)
 ;; - IO
 ;; - Exploring the manual
 (chapter
  :title [Building blocks]
  ;; 
  )

 ;; - Match
 ;; - A little web application
 (chapter
  :title [Putting on a play]
  )

 ;; - Why all the parentheses?
 ;; - Apply
 ;; - Eval
 ;; - Macros
 (chapter
  :title [Toys that make toys]
  ;; macros!
  )

 ;; - GOOPS
 ;; - Building our own object oriented system
 ;; - Functional vs imperative programming
 ;; - Where to go from here?
 (chapter
  :title [The grand finale])

 (chapter
  :title [About this tutorial]

  (p [This tutorial is released under the
        ,(ref :url [https://www.gnu.org/licenses/lgpl.html]
              :text [GNU LGPL]),
        version 3 or later,
        as published by the
        ,(ref :url [http://www.fsf.org/]
              :text [Free Software Foundation]).
      You can get a complete copy of its source from
        ,(ref :url repo-url
              :text [its git repository]).
      If you have suggestions or improvements, you are welcome to make them to
        the ,(ref :url [https://lists.gnu.org/mailman/listinfo/guile-user/]
                  :text [guile-user mailing list])
      Patches welcome!])))