~peter-pearse/ubuntu/natty/guile-1.8/prop001

File: guile-tut.info, Node: History of Guile and its motivations, Next: How to characterize Guile, Prev: What are scripting and extension languages, Up: Introduction

233

234

2.2 History of Guile and its motivations

235

========================================

236

237

A few separate threads of events led to the development of Guile.

238

239

In the fall of 1994, Richard Stallman, director of the GNU project,

240

posted an article with the subject "Why you should not use Tcl", in

241

which he argued that Tcl is inadequate as an extension language. This

242

generated a flurry of flames (available in the hypermail archive

243

(`http://www.vanderburg.org/Tcl/war/') *The Tcl War*).

244

245

The result was that Stallman then proposed his design for the GNU

246

Extension Language, first called GEL and then renamed Guile. The

247

discussion triggered by that article is also available in a hypermail

248

archive, `http://www.vanderburg.org/Tcl/war2/'.

249

250

One interesting feature of this GNU Extension Language plan was that

251

users should have a _choice_ of languages to use in extending their

252

program. The basic language would be a slightly modified Scheme, and

253

translators would be written to convert other languages (like Tcl,

254

Python, Perl, C-like languages ...) into Scheme.

255

256

Tom Lord started working on this project immediately, taking Aubrey

257

Jaffer's small and portable implementation of Scheme, SCM, and making it

258

into an embeddable interpreter: callable from C and allowing new Scheme

259

procedures to be written in C.

260

261

In the spring of 1995, the guile-ii snapshot was released. This made

262

it possible to start writing code in C and Scheme using the guile

263

facilities.

264

265

The guile-iii snapshot was released the summer of 1995, and it had

266

fixed enough problems so that the access to Scheme data structures from

267

C was almost complete.

268

269

After this, Cygnus Support added many features to Guile and finished

270

implementing others, so that Guile acquired thread support, a regular

271

expression matcher, a Tk interface, an interface to the SGI OpenGL

272

graphics system, an _applet_ formalism, and some other packages. This

273

was all in the Cygnus Guile r0.3 and r0.4 releases.

274

275

Meanwhile, Tom Lord left the project after having produced a divergent

276

version of Guile: 1.0b2. The Free Software Foundation hired Jim Blandy

277

to coordinate Guile development. The FSF released its first version of

278

Guile in January 1997. In the future, many of the Cygnus packages will

279

be re-integrated into Guile.

280

281

282

File: guile-tut.info, Node: How to characterize Guile, Prev: History of Guile and its motivations, Up: Introduction

283

284

2.3 How to characterize Guile

285

=============================

286

287

I have already mentioned that Guile has become a kitchen sink package;

288

here you can see how Guile freely takes new commands and constructs from

289

the portable Scheme library _slib_, the _Tk_ widget set, a posix

290

library (useful for UNIX systems programming), the regular expression

291

library _rx_, and many more ...

292

293

So Guile has many more primitive procedures available to it than those

294

specified in *Note Revised(5) Report on the Algorithmic Language

295

Scheme: (r5rs)Standard Procedures. On top of that, Guile will interpret

296

almost all standard Scheme programs. The only incompatible difference

297

between the basic Guile language and R5RS Scheme is that Guile is case

298

sensitive, whereas R5RS is case insensitive. We hope that few people

299

have written Scheme programs that depend on case insensitivity.

300

301

Here is a possible view of the _sum of the parts_ in Guile:

302

guile = standard Scheme (R5RS)

303

PLUS extensions to R5RS offered by SCM

304

PLUS some extra primitives offered by Guile (catch/throw)

305

PLUS portable Scheme library (SLIB)

306

PLUS embeddable Scheme interpreter library (libguile)

307

PLUS Tk toolkit

308

PLUS threads

309

PLUS Posix library

310

PLUS Regular expression library (rx)

311

PLUS Tcl library

312

313

314

File: guile-tut.info, Node: Using Guile to program in Scheme, Next: Guile in a Library, Prev: Introduction, Up: Top

315

316

3 Using Guile to program in Scheme

317

**********************************

318

319

In this section I give a tutorial introduction to programming in Scheme,

320

with a slant toward the interesting things that can be done in Guile.

321

322

This section will try to touch on many of the interesting and cool

323

aspects of Guile, showing you how new types of problems can be solved

324

with Guile. Note that using Guile as a library with `libguile.a' is

325

described in its own chapter (*note Guile in a Library::). Also note

326

that some small examples are given in *Note Jump Start::.

327

328

To get started you need to know how to program in "Scheme" (a dialect

329

of LISP). Fortunately Scheme is a small, clean language and is not

330

hard to learn. It is also used in many undergraduate courses to

331

introduce computer programming.

332

333

I will not try to teach you Scheme here (although you might end up

334

learning by example), since there are many good books on the subject,

335

listed in *Note Where to find more Guile/Scheme resources::. (1)

336

337

3.0.1 Hello World

338

-----------------

339

340

Our first program is the typical Scheme "hello world" program. Put the

341

following code in a file called `hello.scm' (this can be find in

342

`examples/scheme/hello.scm').

343

344

#!/usr/local/bin/guile -s

345

346

347

(display "hello world")

348

(newline)

349

350

Then run guile on it. One way to do so is to start up guile and load

351

this file:

352

353

<shell-prompt> guile

354

guile> (load "hello")

355

356

Another way is to make the file executable and execute it directly.

357

Notice how Guile recognizes a `-s' option which tells it to run a

358

script and then exit. Guile also has a new type of block comment

359

enclosed by `#!' and `!#', so that you can make executable Scheme

360

scripts with the standard UNIX `#!' mechanism.

361

362

In the given example, the first line is used to invoke the Guile

363

interpreter (make sure you correct the path if you installed Guile in

364

something other than /usr/local/bin). Once Guile is invoked on this

365

file, it will understand that the first line is a comment. The comment

366

is then terminated with `!#' on the second line so as to not interfere

367

with the execution mechanism.

368

369

3.0.2 A bunch of operations in Scheme

370

-------------------------------------

371

372

Here is some code you can type at the `guile>' prompt to see some of

373

the Scheme data types at work (mostly lists and vectors). I have

374

inserted brief comments _before_ each line of code explaining what

375

happens.

376

377

;; make a list and bind it to the symbol `ls'

378

guile> (define ls (list 1 2 3 4 5 6 7))

379

380

;; display the list

381

guile> ls

382

=> (1 2 3 4 5 6 7)

383

;; ask if `ls' is a vector; `#f' means it is not

384

guile> (vector? ls)

385

=> #f

386

;; ask if `ls' is a list; `#t' means it is

387

guile> (list? ls)

388

=> #t

389

;; ask for the length of `ls'

390

guile> (length ls)

391

=> 7

392

;; pick out the first element of the list

393

guile> (car ls)

394

=> 1

395

;; pick the rest of the list without the first element

396

guile> (cdr ls)

397

=> (2 3 4 5 6 7)

398

;; this should pick out the 3rd element of the list

399

guile> (car (cdr (cdr ls)))

400

=> 3

401

;; a shorthand for doing the same thing

402

guile> (caddr ls)

403

=> 3

404

;; append the given list onto `ls', print the result

405

;; *NOTE_* the original list `ls' is _not_ modified

406

guile> (append ls (list 8 9 10))

407

=> (1 2 3 4 5 6 7 8 9 10)

408

guile> (reverse ls)

409

=> (7 6 5 4 3 2 1)

410

;; ask if 12 is in the list -- it obviously is not

411

guile> (memq 12 ls)

412

=> #f

413

;; ask if 4 is in the list -- returns the list from 4 on.

414

;; Notice that the result will behave as true in conditionals

415

guile> (memq 4 ls)

416

=> (4 5 6 7)

417

;; an `if' statement using the aforementioned result

418

guile> (if (memq 4 ls)

419

(display "hey, it's true!\n")

420

(display "dude, it's false\n"))

421

hey, it's true!-|

422

423

guile> (if (memq 12 ls)

424

(display "hey, it's true!\n")

425

(display "dude, it's false\n"))

426

dude, it's false-|

427

428

guile> (memq 4 (reverse ls))

429

=> (4 3 2 1)

430

;; make a smaller list `ls2' to work with

431

guile> (define ls2 (list 2 3 4))

432

;; make a list in which the function `sin' has been

433

;; applied to all elements of `ls2'

434

guile> (map sin ls2)

435

=> (0.909297426825682 0.141120008059867 -0.756802495307928)

436

;; make a list in which the squaring function has been

437

;; applied to all elements of `ls'

438

guile> (map (lambda (n) (* n n)) ls)

439

=> (1 4 9 16 25 36 49)

440

441

;; make a vector and bind it to the symbol `v'

442

guile> (define v '#(1 2 3 4 5 6 7))

443

guile> v

444

=> #(1 2 3 4 5 6 7)

445

guile> (vector? v)

446

=> #t

447

guile> (list? v)

448

=> #f

449

guile> (vector-length v)

450

=> 7

451

;; vector-ref allows you to pick out elements by index

452

guile> (vector-ref v 2)

453

=> 3

454

;; play around with the vector: make it into a list, reverse

455

;; the list, go back to a vector and take the second element

456

guile> (vector-ref (list->vector (reverse (vector->list v))) 2)

457

=> 5

458

;; this demonstrates that the entries in a vector do not have

459

;; to be of uniform type

460

guile> (vector-set! v 4 "hi there")

461

=> "hi there"

462

guile> v

463

=> #(1 2 3 4 "hi there" 6 7)

464

465

3.0.3 Using recursion to process lists

466

--------------------------------------

467

468

Here are some typical examples of using recursion to process a list.

469

470

;; this is a rather trivial way of reversing a list

471

(define (my-reverse l)

472

(if (null? l)

473

474

(append (my-reverse (cdr l)) (list (car l)))))

475

(my-reverse '(27 32 33 40))

476

=> (40 33 32 27)

477

478

3.0.4 Processing matrices

479

-------------------------

480

481

Suppose you have a matrix represented as a list of lists:

482

483

(define m

484

(list

485

(list 7 2 1 3 2 8 5 3 6)

486

(list 4 1 1 1 3 8 9 8 1)

487

(list 5 5 4 8 1 8 2 2 4)))

488

489

Then you could apply a certain function to each element of the matrix

490

in the following manner:

491

;; apply the function func to the matrix m element-by-element;

492

;; return a matrix with the result.

493

(define (process-matrix m func)

494

(map (lambda (l)

495

(map func l))

496

m))

497

Notice that I have used the Scheme `map' procedure because I am

498

interested in the matrix that results from the application of `func',

499

rather than in the side effects associated with applying `func'.

500

501

This could be invoked with `(process-matrix m sin)' or

502

`(process-matrix m (lambda (x) (* x x)))'; for example:

503

504

(process-matrix m (lambda (x) (* x x)))

505

=> ((49 4 1 9 4 64 25 9 36) (16 1 1 1 9 64 81 64 1) (25 25 16 64 1 64 4 4 16))

506

507

To print a representation of the matrix, we could define a generalized

508

routine:

509

;; proc is a procedure to represent the single element,

510

;; row-proc is a procedure that is invoked after each row.

511

;; Example: proc could be (lambda (x) (begin (display x) (display " ")))

512

;; and row-proc could be (lambda (l) (display "\n"))

513

(define (represent-matrix m proc row-proc)

514

(for-each (lambda (l)

515

(begin

516

(for-each proc l)

517

(row-proc l)))

518

m))

519

520

And then invoke it with

521

(represent-matrix m

522

(lambda (x) (begin (display x) (display " ")))

523

(lambda (l) (begin (display "\n"))))

524

7 2 1 3 2 8 5 3 6-|

525

4 1 1 1 3 8 9 8 1-|

526

5 5 4 8 1 8 2 2 4-|

527

528

Now we write a helper routine that uses Scheme "closures" to make

529

objects with state that then receive messages to draw little squares.

530

531

But let us take it one step at a time. I will start by showing you a

532

simple example of object in Scheme. The object I make here represents a

533

cell, which could be a cell in a matrix. The cell responds to commands

534

to draw itself, to return the next cell, and so forth. _Guile does not

535

currently have a Tk interface, so I will leave the hooks for graphical

536

rendering. In a future release of Guile I will add graphical rendering

537

messages to the cell object._

538

539

;; cell-object.scm: routines for creating and manipulating cell objects

540

541

;; (the-x, the-y) is the initial position of the cell.

542

;; the-color is a string representing a color; must be something Tk can grok.

543

;; square-size is the size of the square that gets drawn.

544

;; (sizex, sizey) is the size of the matrix.

545

(define (MAKE-CELL the-x the-y the-color square-size sizex sizey)

546

(define (get-x) the-x)

547

(define (get-y) the-y)

548

549

(define (set-x! new-x)

550

(set! the-x new-x)

551

the-x)

552

(define (set-y! new-y)

553

(set! the-y new-y)

554

the-y)

555

(define (get-color) the-color)

556

(define (set-color! new-color)

557

(set! the-color new-color)

558

the-color)

559

(define (next!)

560

(set! the-x (+ the-x 1))

561

(if (>= the-x sizex)

562

(begin

563

(set! the-x 0)

564

(set! the-y (+ the-y 1))))

565

(if (>= the-y sizey)

566

(begin

567

(display "CELL next!: value of y is too big; not changing it\n")

568

(set! the-y (- the-y 1))))

569

(cons the-x the-y))

570

(define (draw)

571

(let* ((x0 (* the-x square-size))

572

(y0 (* the-y square-size))

573

(x1 (+ x0 square-size))

574

(y1 (+ y0 square-size)))

575

(display "I should draw a ")

576

(display the-color)

577

(display " rectangle with corners at ")

578

(display x0) (display y0) (display x1) (display y1)

579

))

580

581

;; self is the dispatch procedure

582

(define (self message)

583

(case message

584

((x) get-x)

585

((y) get-y)

586

((set-x!) set-x!)

587

((set-y!) set-y!)

588

((color) get-color)

589

((set-color!) set-color!)

590

((next!) next!)

591

((draw) draw)

592

(else (error "CELL: Unknown message -> " message))))

593

;; and now return the dispatch procedure

594

self

595

)

596

597

What does this procedure do? It returns another procedure (`self')

598

which receives a message (x, y, set-x!, set-y!, ...) and takes an

599

action to return or modify its state. The state consists of the values

600

of variables `the-x', `the-y', `the-color' and so forth.

601

602

Here are some examples of how to use MAKE-CELL and the cell object it

603

creates:

604

(define c (MAKE-CELL 0 0 "red" 10 7 9))

605

606

;; retrieve the x and y coordinates

607

((c 'x))

608

=> 0

609

((c 'y))

610

=> 0

611

;; change the x coordinate

612

((c 'set-x!) 5)

613

=> 5

614

((c 'x))

615

=> 5

616

;; change the color

617

((c 'color))

618

=> "red"

619

((c 'set-color!) "green")

620

=> "green"

621

((c 'color))

622

=> "green"

623

;; now use the next! message to move to the next cell

624

((c 'next!))

625

=> (6 . 0)

626

((c 'x))

627

=> 6

628

((c 'y))

629

=> 0

630

;; now make things wrap around

631

((c 'next!))

632

=> (0 . 1)

633

((c 'next!))

634

=> (1 . 1)

635

((c 'next!))

636

=> (2 . 1)

637

((c 'x))

638

=> 2

639

((c 'y))

640

=> 1

641

642

You will notice that expressions like `(c 'next)' return procedures

643

that do the job, so we have to use extra parentheses to make the job

644

happen. This syntax is rather awkward; one way around it is to define a

645

`send' procedure:

646

647

;; send makes object syntax a bit easier; instead of saying

648

;; ((my-cell 'set-x!) 4)

649

;; you can say

650

;; (send my-cell 'set-x! 4)

651

(define (send obj . args)

652

(let ((first-eval (apply obj (list (car args)))))

653

(if (null? (cdr args))

654

(first-eval)

655

(apply first-eval (cdr args)))))

656

657

You can see that `send' passes the message to the object, making sure

658

that things are evaluated the proper number of times. You can now type:

659

660

(define c2 (MAKE-CELL 0 0 "red" 10 7 9))

661

(send c2 'x)

662

=> 0

663

(send c2 'set-x! 5)

664

=> 5

665

(send c2 'color)

666

=> "red"

667

(send c2 'set-color! "green")

668

=> "green"

669

(send c2 'next!)

670

=> (1 . 0)

671

(send c2 'x)

672

=> 1

673

(send c2 'y)

674

=> 0

675

676

This is the simplest way of implementing objects in Scheme, but it

677

does not really allow for full _object-oriented programming_ (for

678

example, there is no inheritance). But it is useful for _object-based

679

programming_.

680

681

Guile comes with a couple more complete object-oriented extensions to

682

Scheme: these are part of slib (*note Object: (slib)Object. and *note

683

Yasos: (slib)Yasos.).

684

685

---------- Footnotes ----------

686

687

(1) To get started, look at the books `Simply Scheme' and `The Little

688

Schemer' from that list.

689

690

691

File: guile-tut.info, Node: Guile in a Library, Next: Regular Expression Support, Prev: Using Guile to program in Scheme, Up: Top

692

693

4 Guile in a Library

694

********************

695

696

In the previous chapters Guile was used to write programs entirely in

697

Scheme, and no C code was seen; but I have been claiming _ad nauseam_

698

that Guile is an _extension_ language. Here we see how that is done,

699

and how that can be useful.

700

701

* Menu:

702

703

* Two world views::

704

* What is libguile::

705

* How to get started with libguile::

706

* More interesting programming with libguile::

707

* Further examples::

708

709

710

File: guile-tut.info, Node: Two world views, Next: What is libguile, Up: Guile in a Library

711

712

4.1 Two world views

713

===================

714

715

In this manual, I usually jump into examples and explain them as you

716

type in the code; here I will digress and ramble for a few paragraphs to

717

set some concepts straight, and then let you type (or paste) in fun

718

examples.

719

720

In 1995, I implemented a large program, "Gnudl", using Guile quite

721

extensively. In the design phase of Gnudl, I found I had to make a

722

choice: should the fundamental data structures be C or Scheme data

723

structures?

724

725

Guile allows C to see its data structures (scalar types, lists,

726

vectors, strings ...). C also allows Guile to see its data structures.

727

As a large program designer, you have to decide which of those

728

capabilities to use. You have two main choices:

729

730

1. You can write your software mostly in Scheme. In this case, your C

731

software will mostly parse the Scheme code with Guile calls, and

732

provide some new primitive procedures to be used by Scheme. This

733

is what Gnudl does.

734

735

2. You can write your software mostly in C, occasionally allowing

736

Scheme code to be parsed by Guile, either to allow the user to

737

modify data structures, or to parse a configuration file, ...

738

739

Mixing the two approaches seems unwise: the overall layout would be

740

confusing. But who knows? There might be problems that are best solved

741

by a hybrid approach. Please let me know if you think of such a

742

problem.

743

744

If you use the former approach, we will say that the "master world"

745

is Scheme, and the C routines serve Scheme and access Scheme data

746

structures. In the latter case, the master world is C, and Scheme

747

routines serve the C code and access C data structures.

748

749

In both approaches the `libguile.a' library is the same, but a

750

predominantly different set of routines will be used. When we go

751

through examples of libguile use, we will point out which is the master

752

world in order to clarify these two approaches.

753

754

755

File: guile-tut.info, Node: What is libguile, Next: How to get started with libguile, Prev: Two world views, Up: Guile in a Library

756

757

4.2 What is libguile

758

====================

759

760

"Libguile" is the library which allows C programs to start a Scheme

761

interpreter and execute Scheme code. There are also facilities in

762

libguile to make C data structures available to Scheme, and vice versa.

763

764

The interface provided by the libguile C library is somewhat specific

765

to the implementation of the Scheme interpreter. This low-level

766

libguile interface is usually referred to as the `scm_' interface,

767

since its public calls (API) all have the `scm_' prefix.

768

769

There is also a higher-level libguile interface, which is usually

770

referred to as the `gh_' interface (libGuile High). Its public calls

771

all have the `gh_' prefix. The `gh_' library interface is designed to

772

hide the implementation details, thus making it easier to assimilate

773

and portable to other underlying Scheme implementations.

774

775

People extending Guile by adding bindings to C libraries (like OpenGL

776

or Rx) are encouraged to use the `gh_' interface, so their work will be

777

portable to other Scheme systems. The `gh_' interface should be more

778

stable, because it is simpler.

779

780

The `scm_' interface is necessary if you want to poke into the

781

innards of Scheme data structures, or do anything else that is not

782

offered by the `gh_' interface. It is not covered in this tutorial,

783

but is covered extensively in *Note Data Representation in Guile:

784

(guile)Data representation.

785

786

This chapter gives a gentle introduction to the `gh_' interface,

787

presenting some _hello world_-style programs which I wrote while

788

teaching myself to use libguile.

789

790

The `Guile Programmer's Manual' gives more examples of programs

791

written using libguile, illustrating diverse applications. You can also

792

consult my _Gnudl_ documentation at

793

`http://nis-www.lanl.gov/~rosalia/mydocs/' to see a large scale project

794

that uses C and Scheme code together.

795

796

797

File: guile-tut.info, Node: How to get started with libguile, Next: More interesting programming with libguile, Prev: What is libguile, Up: Guile in a Library

798

799

4.3 How to get started with libguile

800

====================================

801

802

Here is an elementary first program, `learn0', to get going with

803

libguile. The program (which uses Scheme as a master world) is in a

804

single source file, `learn0.c':

805

806

/* test the new libgh.a (Guile High-level library) with a trivial

807

program */

808

809

#include <stdio.h>

810

811

#include <guile/gh.h>

812

813

void main_prog(int argc, char *argv[]);

814

815

main(int argc, char *argv[])

816

{

817

gh_enter(argc, argv, main_prog);

818

}

819

820

void main_prog(int argc, char *argv[])

821

{

822

int done;

823

char input_str[200];

824

825

gh_eval_str("(display \"hello Guile\")");

826

gh_eval_str("(newline)");

827

828

/* for fun, evaluate some simple Scheme expressions here */

829

gh_eval_str("(define (square x) (* x x))");

830

gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))");

831

gh_eval_str("(square 9)");

832

833

/* now sit in a Scheme eval loop: I input the expressions, have

834

Guile evaluate them, and then get another expression. */

835

done = 0;

836

fputs("learn0> ", stdout);

837

while (fgets(input_str, 199, stdin) != NULL) {

838

gh_eval_str(input_str);

839

fputs("\nlearn0> ", stdout);

840

}

841

842

exit(0);

843

}

844

845

If you name this program `learn0.c', it can now be compiled with:

846

gcc -g -c learn0.c -o learn0.o

847

gcc -o learn0 learn0.o -lguile -lm

848

849

The program is simple: it creates a Scheme interpreter, passes a

850

couple of strings to it that define new Scheme functions `square' and

851

`factorial', and then a couple of strings that invoke those functions.

852

853

It then goes into a read-eval-print-loop (REPL), so you could type

854

one-line Scheme expressions to it and have them evaluated. For example:

855

<shell-prompt> ./learn0

856

hello Guile

857

learn0> (display (sin 1.3))

858

963.558185417193e-3

859

learn0> (display (fact 10))

860

3628800

861

learn0> (quit)

862

<shell-prompt>

863

864

You should notice the key steps involved in this `learn0' program:

865

866

1. `#include <guile/gh.h>'

867

868

2. You need to invoke the initialization routine `gh_enter()'. This

869

starts up a Scheme interpreter, handling many

870

implementation-specific details.

871

872

3. Your main() function should be almost empty: the real main program

873

goes in a separate function main_prog() which is passed to

874

gh_enter(). This rather arcane convention is due to the way

875

Guile's garbage collector works: the whole program has to run in

876

the dynamic context of `gh_enter()'.

877

878

4. You pass strings to the Scheme interpreter with the `gh_eval_str()'

879

routine.

880

881

5. You link your program with `-lguile'.

882

883

884

File: guile-tut.info, Node: More interesting programming with libguile, Next: Further examples, Prev: How to get started with libguile, Up: Guile in a Library

885

886

4.4 More interesting programming with libguile

887

==============================================

888

889

The `learn0' program shows how you can invoke Scheme commands from a C

890

program. This is not such a great achievement: the same could have

891

been done by opening a pipe to SCM or any other Scheme interpreter.

892

893

A true extension language must allow "callbacks". Callbacks allow

894

you to write C routines that can be invoked as Scheme procedures, thus

895

adding new primitive procedures to Scheme. This also means that a

896

Scheme procedure can modify a C data structure.

897

898

Guile allows you to define new Scheme procedures in C, and provides a

899

mechanism to go back and forth between C and Scheme data types.

900

901

Here is a second program, `learn1', which demonstrates these

902

features. It is split into three source files: `learn1.c',

903

`c_builtins.h' and `c_builtins.c'. I am including the code here.

904

905

Notice that `learn1' uses a Scheme master world, and the C routines

906

in `c_builtins.c' are simply adding new primitives to Scheme.

907

908

* Menu:

909

910

* learn1.c::

911

* c_builtins.h::

912

* c_builtins.c::

913

* What learn1 is doing::

914

* Compiling and running learn1::

915

916

917

File: guile-tut.info, Node: learn1.c, Next: c_builtins.h, Up: More interesting programming with libguile

918

919

4.4.1 learn1.c

920

--------------

921

922

Here is `learn1.c':

923

#include <stdio.h>

924

925

#include <guile/gh.h>

926

927

#include "c_builtins.h"

928

929

void main_prog(int argc, char *argv[]);

930

931

main(int argc, char *argv[])

932

{

933

gh_enter(argc, argv, main_prog);

934

}

935

936

void main_prog(int argc, char *argv[])

937

{

938

char input_str[200]; /* ugly hack: assume strlen(line) < 200 */

939

int done;

940

941

/* for fun, evaluate some simple Scheme expressions here */

942

gh_eval_str("(define (square x) (* x x))");

943

gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))");

944

gh_eval_str("(square 9)");

945

gh_eval_str("(fact 100)");

946

947

/* now try to define some new builtins, coded in C, so that they are

948

available in Scheme. */

949

gh_new_procedure1_0("c-factorial", c_factorial);

950

gh_new_procedure1_0("c-sin", c_sin);

951

gh_new_procedure1_0("v-t", vector_test);

952

953

/* now sit in a Scheme eval loop: I input the expressions, have

954

Guile evaluate them, and then get another expression. */

955

done = 0;

956

fputs("learn1> ", stdout);

957

while (!done) {

958

if (gets(input_str) == NULL) {

959

done = 1;

960

} else {

961

gh_eval_str(input_str);

962

fputs("learn1> ", stdout);

963

}

964

}

965

966

exit(0);

967

}

968

969

970

File: guile-tut.info, Node: c_builtins.h, Next: c_builtins.c, Prev: learn1.c, Up: More interesting programming with libguile

971

972

4.4.2 c_builtins.h

973

------------------

974

975

Here is `c_builtins.h':

976

/* builtin function prototypes */

977

978

#include <guile/gh.h>

979

980

SCM c_factorial(SCM n);

981

SCM c_sin(SCM n);

982

SCM vector_test(SCM s_length);

983

984

985

File: guile-tut.info, Node: c_builtins.c, Next: What learn1 is doing, Prev: c_builtins.h, Up: More interesting programming with libguile

986

987

4.4.3 c_builtins.c

988

------------------

989

990

Here is `c_builtins.c':

991

#include <stdio.h>

992

#include <math.h>

993

994

#include <guile/gh.h>

995

996

#include "c_builtins.h"

997

998

/* this is a factorial routine in C, made to be callable by Scheme */

999

SCM c_factorial(SCM s_n)

1000

{

1001

int i;

1002

unsigned long result = 1, n;

1003

1004

n = gh_scm2ulong(s_n);

1005

1006

gh_defer_ints();

1007

for (i = 1; i <= n; ++i) {

1008

result = result*i;

1009

}

1010

gh_allow_ints();

1011

return gh_ulong2scm(result);

1012

}

1013

1014

/* a sin routine in C, callable from Scheme. it is named c_sin() to

1015

distinguish it from the default Scheme sin function */

1016

SCM c_sin(SCM s_x)

1017

{

1018

double x = gh_scm2double(s_x);

1019

1020

return gh_double2scm(sin(x));

1021

}

1022

1023

/* play around with vectors in Guile: this routine creates a vector of

1024

the given length, initializes it all to zero except element 2 which

1025

is set to 1.9. */

1026

SCM vector_test(SCM s_length)

1027

{

1028

SCM xvec;

1029

1030

c_length = gh_scm2ulong(s_length);

1031

printf("requested length for vector: %ld\n", gh_scm2ulong(s_length));

1032

1033

/* create a vector */

1034

xvec = gh_make_vector(s_length, gh_double2scm(0.0));

1035

/* set the second element in it */

1036

gh_vector_set_x(xvec, gh_int2scm(2), gh_double2scm(1.9));

1037

1038

return xvec;

1039

}

1040

1041

1042

File: guile-tut.info, Node: What learn1 is doing, Next: Compiling and running learn1, Prev: c_builtins.c, Up: More interesting programming with libguile

1043

1044

4.4.4 What learn1 is doing

1045

--------------------------

1046

1047

If you compare learn1 to learn0, you will find that learn1 uses a new

1048

Guile construct: the function `gh_new_procedure()', and its siblings:

1049

1050

/* now try to define some new builtins, coded in C, so that they are

1051

available in Scheme. */

1052

gh_new_procedure1_0("c-factorial", c_factorial);

1053

gh_new_procedure1_0("c-sin", c_sin);

1054

gh_new_procedure1_0("v-t", vector_test);

1055

1056

It is clear that `gh_new_procedure()' adds a new builtin routine

1057

written in C which can be invoked from Scheme. We can now revise our

1058

checklist for programming with libguile, so it includes adding

1059

callbacks.

1060

1061

1. `#include <guile/gh.h>'

1062

1063

2. You need to invoke the initialization routine `gh_enter()'. This

1064

starts up a Scheme interpreter, handling many details.

1065

1066

3. Your main() function should be almost empty: the real main program

1067

goes in a separate function main_prog() which is passed to

1068

gh_enter(). This rather arcane convention is due to the way

1069

Guile's garbage collector works: the whole program has to run in

1070

the dynamic context of `gh_enter()'.

1071

1072

4. You pass strings to the Scheme interpreter with the `gh_eval_str()'

1073

routine.

1074

1075

5. *[new]* You can now define new builtin Scheme functions; i.e.

1076

define new builtin Scheme functions, with the `gh_new_procedure()'

1077

routine.

1078

1079

6. You pass strings to the Scheme interpreter with the

1080

`gh_eval_str()' routine.

1081

1082

7. You link your program with `-lguile'.

1083

1084

I breezed by the issue of how to write your C routines that are

1085

registered to be called from Scheme. This is non-trivial, and is

1086

discussed at length in the `Guile Programmer's Manual'.

1087

1088

1089

File: guile-tut.info, Node: Compiling and running learn1, Prev: What learn1 is doing, Up: More interesting programming with libguile

1090

1091

4.4.5 Compiling and running learn1

1092

----------------------------------

1093

1094

gcc -g -c learn1.c -o learn1.o

1095

gcc -g -c c_builtins.c -o c_builtins.o

1096

gcc -o learn1 learn1.o c_builtins.o -lguile -lm

1097

1098

If you run `learn1', it will prompt you for a one-line Scheme

1099

expression, just as `learn0' did. The difference is that you can use

1100

the new C builtin procedures (`c-factorial', `c-sin', `v-t').

1101

1102

<shell-prompt> ./learn1

1103

welcome to Guile

1104

hello Guile

1105

learn1> (display (c-factorial 6))

1106

720

1107

learn1> (display (c-factorial 20))

1108

2192834560

1109

learn1> (display (c-factorial 100))

1110

1111

learn1> (display (c-sin 1.5))

1112

0.997494986604054

1113

learn1> (display (v-t 10))

1114

requested length for vector: 10

1115

#(0.0 0.0 1.9 0.0 0.0 0.0 0.0 0.0 0.0 0.0)

1116

learn1> (display (v-t 15))

1117

requested length for vector: 15

1118

#(0.0 0.0 1.9 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)

1119

learn1> (quit)

1120

<shell-prompt>

1121

1122

As you see, taking `(c-factorial 100)' does not use bignumbers and

1123

returns a bogus answer.

1124

1125

1126

File: guile-tut.info, Node: Further examples, Prev: More interesting programming with libguile, Up: Guile in a Library

1127

1128

4.5 Further examples

1129

====================

1130

1131

Further "idealized" examples are included in the `doc/examples/c'

1132

distribution. They include programs to:

1133

1134

* Parse a startup file (C is the master world).

1135

1136

* Set up initial conditions for an n-body simulation (C is the master

1137

world).

1138

1139

* Implement a Scheme interpreter with all of Guile's goodies, _plus_

1140

the readline library _and_ a fast Fourier transform routine

1141

provided in C (Scheme is the master world).

1142

1143

1144

File: guile-tut.info, Node: Regular Expression Support, Next: UNIX System Programming, Prev: Guile in a Library, Up: Top

1145

1146

5 Regular Expression Support

1147

****************************

1148

1149

1150

File: guile-tut.info, Node: UNIX System Programming, Next: Where to find more Guile/Scheme resources, Prev: Regular Expression Support, Up: Top

1151

1152

6 UNIX System Programming

1153

*************************

1154

1155

1156

File: guile-tut.info, Node: Where to find more Guile/Scheme resources, Next: Concept Index, Prev: UNIX System Programming, Up: Top

1157

1158

7 Where to find more Guile/Scheme resources

1159

*******************************************

1160

1161

1162

File: guile-tut.info, Node: Concept Index, Next: Procedure and Macro Index, Prev: Where to find more Guile/Scheme resources, Up: Top

1163

1164

Concept Index

1165

*************

1166

1167

[index]

1168

* Menu:

1169

1170

* Benson, Brent: What are scripting and extension languages.

1171

(line 57)

1172

* bignumbers: Jump Start. (line 30)

1173

* Blandy, Jim: History of Guile and its motivations.

1174

(line 48)

1175

* Bourne shell: What are scripting and extension languages.

1176

(line 20)

1177

* builtin functions: More interesting programming with libguile.

1178

(line 6)

1179

* callback: More interesting programming with libguile.

1180

(line 6)

1181

* case sensitivity: How to characterize Guile.

1182

(line 18)

1183

* cell-object: Using Guile to program in Scheme.

1184

(line 283)

1185

* closures: Using Guile to program in Scheme.

1186

(line 216)

1187

* Cygnus Support: History of Guile and its motivations.

1188

(line 42)

1189

* Dominion: What are scripting and extension languages.

1190

(line 49)

1191

* Emacs Lisp: What are scripting and extension languages.

1192

(line 38)

1193

* extending C programs: Guile in a Library. (line 9)

1194

* extension languages: What are scripting and extension languages.

1195

(line 6)

1196

* extension languages - examples: What are scripting and extension languages.

1197

(line 36)

1198

* extensions to R5RS: How to characterize Guile.

1199

(line 20)

1200

* extensions to standard Scheme: How to characterize Guile.

1201

(line 20)

1202

* Free Software Foundation: History of Guile and its motivations.

1203

(line 48)

1204

* Galassi, Mark: Two world views. (line 14)

1205

* gh interface: What is libguile. (line 6)

1206

* GNU Data Language: Two world views. (line 14)

1207

* GNU project: History of Guile and its motivations.

1208

(line 12)

1209

* gnudl: Two world views. (line 14)

1210

* hello world <1>: What is libguile. (line 34)

1211

* hello world: Using Guile to program in Scheme.

1212

(line 27)

1213

* Jaffer, Aubrey: History of Guile and its motivations.

1214

(line 28)

1215

* large programs: What are scripting and extension languages.

1216

(line 77)

1217

* learn0: How to get started with libguile.

1218

(line 6)

1219

* learn1: More interesting programming with libguile.

1220

(line 6)

1221

* libguile <1>: What is libguile. (line 6)

1222

* libguile: Guile in a Library. (line 9)

1223

* libguile - step by step: What learn1 is doing.

1224

(line 18)

1225

* libscheme: What are scripting and extension languages.

1226

(line 57)

1227

* lisp dialects: Using Guile to program in Scheme.

1228

(line 18)

1229

* list processing: Using Guile to program in Scheme.

1230

(line 155)

1231

* Lord, Tom: History of Guile and its motivations.

1232

(line 28)

1233

* Lotus 1-2-3: What are scripting and extension languages.

1234

(line 45)

1235

* master world: Two world views. (line 6)

1236

* object-based programming: Using Guile to program in Scheme.

1237

(line 363)

1238

* object-oriented programming: Using Guile to program in Scheme.

1239

(line 363)

1240

* objects: Using Guile to program in Scheme.

1241

(line 215)

1242

* POSIX: How to characterize Guile.

1243

(line 10)

1244

* primitive procedures: What learn1 is doing.

1245

(line 6)

1246

* recursion: Using Guile to program in Scheme.

1247

(line 155)

1248

* registering C functions: What learn1 is doing.

1249

(line 6)

1250

* registering callbacks: What learn1 is doing.

1251

(line 6)

1252

* report on Scheme: How to characterize Guile.

1253

(line 18)

1254

* Revised(5) Report on the Algorithmic Language Scheme: How to characterize Guile.

1255

(line 18)

1256

* rx: How to characterize Guile.

1257

(line 10)

1258

* Scheme extensions: How to characterize Guile.

1259

(line 20)

1260

* Scheme language - definition: How to characterize Guile.

1261

(line 18)

1262

* Scheme language - report: How to characterize Guile.

1263

(line 18)

1264

* Scheme programming tutorial: Using Guile to program in Scheme.

1265

(line 6)

1266

* scm interface: What is libguile. (line 6)

1267

* scripting languages: What are scripting and extension languages.

1268

(line 6)

1269

* scripting languages - examples: What are scripting and extension languages.

1270

(line 15)

1271

* slib: How to characterize Guile.

1272

(line 10)

1273

* Stallman, Richard: History of Guile and its motivations.

1274

(line 12)

1275

* syntactic closures: Using Guile to program in Scheme.

1276

(line 216)

1277

* Tcl <1>: History of Guile and its motivations.

1278

(line 12)

1279

* Tcl: What are scripting and extension languages.

1280

(line 41)

1281

* Tk: How to characterize Guile.

1282

(line 10)

1283

* tutorial on Scheme programming: Using Guile to program in Scheme.

1284

(line 6)

1285

1286

1287

File: guile-tut.info, Node: Procedure and Macro Index, Next: Variable Index, Prev: Concept Index, Up: Top

1288

1289

Procedure and Macro Index

1290

*************************

1291

1292

This is an alphabetical list of all the procedures and macros in

1293

Dominion.

1294

1295

[index]

1296

* Menu:

1297

1298

* MAKE-CELL: Using Guile to program in Scheme.

1299

(line 283)

1300

* represent-matrix: Using Guile to program in Scheme.

1301

(line 206)

1302

* send: Using Guile to program in Scheme.

1303

(line 343)

1304

1305

1306

File: guile-tut.info, Node: Variable Index, Next: Type Index, Prev: Procedure and Macro Index, Up: Top

1307

1308

Variable Index

1309

**************

1310

1311

This is an alphabetical list of the major global variables in Dominion.

1312

1313

[index]

1314

* Menu:

1315

1316

File: guile-tut.info, Node: Type Index, Prev: Variable Index, Up: Top

1317

1318

Type Index

1319

**********

1320

1321

This is an alphabetical list of the major data structures in Dominion.

1322

1323

[index]

1324

* Menu:

1325

1326

1327

Tag Table:

1328

Node: Top221

1329

Node: Jump Start1373

1330

Node: Introduction4984

1331

Node: What are scripting and extension languages5685

1332

Node: History of Guile and its motivations9222

1333

Node: How to characterize Guile11676

1334

Node: Using Guile to program in Scheme13204

1335

Ref: Using Guile to program in Scheme-Footnote-126036

1336

Node: Guile in a Library26134

1337

Node: Two world views26711

1338

Node: What is libguile28715

1339

Node: How to get started with libguile30699

1340

Node: More interesting programming with libguile33539

1341

Node: learn1.c34839

1342

Node: c_builtins.h36293

1343

Node: c_builtins.c36645

1344

Node: What learn1 is doing38151

1345

Node: Compiling and running learn140020

1346

Node: Further examples41228

1347

Node: Regular Expression Support41830

1348

Node: UNIX System Programming42017

1349

Node: Where to find more Guile/Scheme resources42221

1350

Node: Concept Index42448

1351

Node: Procedure and Macro Index51203

1352

Node: Variable Index51911

1353

Node: Type Index52145

1354

1355

End Tag Table

Older »