source: project/wiki/friendly-chicken @ 30888

== Friendly CHICKEN

If you're a CHICKEN beginner, you come from another language or a different scheme implementation, there are a few things you might be wondering about, when you're first exposed to CHICKEN. This little tutorial shall help you to lower the barriers and highlight some little pitfalls so that your time with CHICKEN is more fun from the very beginning.

For a general introduction to CHICKEN, see [[man/4/Getting started|Getting started]].

=== The numeric tower

CHICKEN's core does not provide the full numeric tower. This might surprise you if you come from other scheme implementations, or
use CHICKEN to do your scheme homeworks. Don't worry, your homeworks are safe. It's easy to get the full tower through [[/egg/numbers|the numbers egg]].
Simply install the egg and load it via '''require-extension''' or '''use'''.

Installation:
<enscript highligh="scheme">
$ chicken-install numbers
</enscript>

Usage:
<enscript highlight="scheme">
(use numbers)

(complex? 1.0+2.0i)
</enscript>

The important thing is that you '''use''' numbers.

=== Where is my fold?

Since scheme is a lisp it offers quite a few useful procedures that operate on lists, such as '''fold''','''unfold''','''filter''' and many more.
You might have seen those in the examples of a tutorial, textbook or your scheme class. As the happy schemer, that you are, you instantly tried
them out in a fresh csi session, when you had to realize that CHICKEN doesn't seem to know them.

Again it's easy enough to get it. SRFI-1 comes as a core unit, which means that you don't need to install an egg.

<enscript highlight="scheme">
(use srfi-1)

(filter odd? (iota 10))
</enscript>

=== UTF-8

CHICKEN's string procedures generally operate on byte-strings. That means they are not aware of encodings such as UTF-8.
The following csi transcript shows this:

<enscript highlight="bash">
CHICKEN
(c) 2008-2014, The Chicken Team
(c) 2000-2007, Felix L. Winkelmann
Version 4.8.4 (rev 3d545a9)
linux-unix-gnu-x86-64 [ 64bit manyargs dload ptables ]
compiled 2014-02-06 on dantien (Linux)

#;1> (string-length "λ")
2
#;2>
</enscript>

As you see (string-length) on the string containing the unicode-character returns 2 rather than 1.
To fix this you need to install and use [[/egg/utf8|the utf8 egg]].

See the transcript with utf8 loaded:

<enscript highlight="bash">
CHICKEN
(c) 2008-2014, The Chicken Team
(c) 2000-2007, Felix L. Winkelmann
Version 4.8.4 (rev 3d545a9)
linux-unix-gnu-x86-64 [ 64bit manyargs dload ptables ]
compiled 2014-02-06 on dantien (Linux)

#;1> (use utf8)
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/utf8.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/chicken.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/data-structures.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/extras.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/regex.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/irregex.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/ports.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/utf8-lolevel.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/lolevel.import.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/utf8.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/regex.so ...
; loading /home/certainty/sys/opt/chickens/master/lib/chicken/7/utf8-lolevel.so ...
#;2> (string-length "λ")
1
#;3>
</enscript>

=== Load useful libraries and units in csi automatically

If you find yourself using these libraries alot you might want to have '''csi''' load them whenever you start it up.
This can easily be done by adding them to your '''$HOME/.csirc'''.

A sample csirc might look like this:

<enscript highlight="scheme">
(use numbers utf8 srfi-1 srfi-13)
</enscript>


=== Other useful eggs and units for real world tasks
There are some other units and eggs that you might find helpful to solve real world problems with CHICKEN.
The following lists a few of them:

==== Eggs
* [[/egg/numbers|numbers]] - Full numeric tower
* [[/egg/utf8|UTF8]]    - Make string procedures utf8 aware

==== Units
(You don't need to chicken-install these)
* [[/manual/Unit srfi-1|SRFI-1]]  - List procedures 
* [[/manual/Unit srfi-13|SRFI-13]] - String procedures
* [[/manual/Unit srfi-69|SRFI-69]] - Hashtables
* [[/manual/Unit irregex|irregex]] - Regular expressions

=== Happy Hacking

I hope this little guide helps you to start your CHICKEN journey without too many surprises.
Have fun hacking ....