Grip Edition 0.2.0, revision 1, for use with Grip 0.2.0 The Grip Developpers This manual documents Grip version 0.2.0. Copyright (C) 2011 - 2018 David Pirotte <david at altosw dot be> Permission is granted to copy, distribute and/or modify this document under the terms of 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. A copy of the license is included in the section entitled \GNU Free Documentation License." i Table of Contents Preface ::::::::::::::::::::::::::::::::::::::::::::::: 1 Contributors to this Manual ::::::::::::::::::::::::::::::::::::::::: 1 The Grip License :::::::::::::::::::::::::::::::::::::::::::::::::::: 1 1 Introduction ::::::::::::::::::::::::::::::::::::: 1 1.1 About Grip::::::::::::::::::::::::::::::::::::::::::::::::::::: 1 1.2 Objective::::::::::::::::::::::::::::::::::::::::::::::::::::::: 2 1.3 The name :::::::::::::::::::::::::::::::::::::::::::::::::::::: 2 1.4 Savannah::::::::::::::::::::::::::::::::::::::::::::::::::::::: 2 1.5 Obtaining and Installing Grip::::::::::::::::::::::::::::::::::: 2 1.5.1 Dependencies :::::::::::::::::::::::::::::::::::::::::::::: 3 1.5.2 Quickstart ::::::::::::::::::::::::::::::::::::::::::::::::: 3 1.6 Contact :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 4 1.7 Reporting Bugs::::::::::::::::::::::::::::::::::::::::::::::::: 4 2 Using Grip ::::::::::::::::::::::::::::::::::::::: 5 2.1 Grip:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 5 2.2 Grip-SQLite :::::::::::::::::::::::::::::::::::::::::::::::::::: 5 2.3 Grip-Gnome :::::::::::::::::::::::::::::::::::::::::::::::::::: 5 2.4 Grip-Clutter:::::::::::::::::::::::::::::::::::::::::::::::::::: 5 3 API Reference ::::::::::::::::::::::::::::::::::: 5 3.1 Modules :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 5 3.2 Goops :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 6 3.3 Optional Arguments :::::::::::::::::::::::::::::::::::::::::::: 7 3.4 Lists ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 7 3.5 Strings ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 8 3.6 Queues :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 10 3.7 Stores ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 10 3.8 Iterations ::::::::::::::::::::::::::::::::::::::::::::::::::::: 13 3.9 Angles :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 14 3.10 Floats :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 14 3.11 REPL Servers :::::::::::::::::::::::::::::::::::::::::::::::: 15 3.12 Xft::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 15 3.13 Utilities :::::::::::::::::::::::::::::::::::::::::::::::::::::: 16 Appendix A GNU Free Documentation License :: 17 Concept Index ::::::::::::::::::::::::::::::::::::: 25 Procedure Index ::::::::::::::::::::::::::::::::::: 26 ii Variable Index:::::::::::::::::::::::::::::::::::::: 27 Type Index ::::::::::::::::::::::::::::::::::::::::: 28 1 Preface This manual describes how to use Grip. It relates particularly to Grip version 0.2.0. Contributors to this Manual Like Grip itself, the Grip user manual is a living entity. Right now, the contributors to this manual are: • David Pirotte David is also the author and maintainer of Grip. You are most welcome to join and help. Visit Grip's web site (http://www.nongnu.org/grip/index.html) to find out how to get involved. The Grip License Grip is Free Software. Grip is copyrighted, not public domain, and there are restrictions on its distribution or redistribution: • Grip and supporting files are published under the terms of the GNU General Public License version 3 or later. See the file LICENSE. • This manual is published under the terms of the GNU Free Documentation License (see Appendix A [GNU Free Documentation License], page 17). You must be aware there is no warranty whatsoever for Grip. This is described in full in the license. 1 Introduction 1.1 About Grip Grip (http://www.nongnu.org/grip/index.html), a Grip of Really Important Proce- dures, is a Guile (http://www.gnu.org/software/guile) Scheme toolbox currently com- posed of Grip itself, Grip-SQLite, Grip-Gnome and Grip-Clutter. Notes: Grip (core), Grip-SQLite and Grip-Gnome are being rewritten and documented, you will spot that by yourself in the code if you visit it, and read the documentation. Until this process is complete, the modules you can safely use and rely on are the Grip (core) modules that are documented, as well as all Grip-Clutter modules and examples. You are welcome to try and use Grip (http://www.nongnu.org/grip/index.html), and, keeping the above in mind, help us to get it better - reviewing its interface design, the source code, its tests and documentation. New features are also welcome! Though in order to acheive stability, to the best we can, we should, with all due respect and kindness, be 'nit-picky' with each other, and only Chapter 1: Introduction 2 include those that reach a consensus, first with respect to their inclusion per se, thenin terms of interface design, implementation, tests and documentation. 1.2 Objective Grip (http://www.nongnu.org/grip/index.html) started as a personnal toolbox, ag- gregating modules I wrote to support other projects and clearly hosting 'reusable' func- tionalities. Now that I started to revisit Grip's core modules [May 2018], restructuring and rewritting them, with a proper interface design, implementation, documentation and test-suite, now is a good time to share this work and invite other guilers to either use Grip, or even beter contribute to it. The idea is similar to the one expressed in Guile-Lib (http://www.nongnu.org/guile-lib), that is, a place for people to collaborate to the development of a common library, though less intimidating maybe and, unlike Guile-Lib, Grip will tolerate, under strict conditions, some C code: this is notably to support and boost Guile-CV (http://www.nongnu.org/guile-lib) floating point operations, at least till Guile (http://www.gnu.org/software/guile) has an AOT compiler, able to offer similar performance results for fixed size floating points and integer operations. I should mention that I started Grip far before I became one of the Guile-Lib co- maintainer, and that the intention is not to compete with it, but rather, to offer sort of a code staging for it, where people can experiment new functionalities with a bit more flexi- bility. With time, the well designed, stable, documented and tested pure scheme interfaces could be moved to Guile-Lib. 1.3 The name The term Grip is from the early era of the circus. See the following Wikipedia (https://en.wikipedia.org/wiki/Grip_(job)), page for a full description, where you'll read the following extract: ... From there it was used in vaudeville and then in today's film sound stages and sets. Some have suggested the name comes from the 1930s{40s slang term for a Tool Bag or Grip that these technicians use to carry their tools... 1.4 Savannah Grip (http://www.nongnu.org/grip/index.html) also has a Savannah (http://savannah.nongnu.org/projects/grip) (non GNU) project page. 1.5 Obtaining and Installing Grip Grip can be obtained from the following archive (http://download.savannah.gnu.org/releases/grip) site. The file will be named grip-version.tar.gz. The current version is 0.2.0, so the file you should grab is: grip-0.2.0.tar.gz (http://download.savannah.gnu.org/releases/grip/grip-0.2.0.tar.gz) Chapter 1: Introduction 3 1.5.1 Dependencies Grip will look for the following dependencies and will try to install all its components, but will only do so if it can effectively install Grip core and statisfy the component specific requirement(s). Grip • Autoconf >= 2.69 • Automake >= 1.14 • Guile-2.0 (http://www.gnu.org/software/guile) >= 2.0.14 or Guile-2.2 Grip-SQLite • SQLite (http://www.sqlite.org) >= 3.7 Grip-Gnome • Guile-Gnome (http://www.gnu.org/software/guile-gnome) >= 2.16.5, the following wrappers: Glib, Gobject, Gtk, libglade Grip-Clutter • Guile-Clutter (http://www.gnu.org/software/guile-gnome/clutter) >= 1.12.2.1 1.5.2 Quickstart Assuming you have satisfied the dependencies, open a terminal and proceed withthe following steps: cd <download-path> tar zxf grip-0.2.0.tar.gz cd grip-0.2.0 ./configure [--prefix=/your/prefix] [--with-guile-site=yes] make make install Grip comes with a tests suite, which you may run (recommended) using: make check Happy Grip! Notes: 1. The default and --prefix installation locations for source modules and compiled files (in the absence of --with-guile-site=yes, otherwise see below) are: $(datadir)/grip $(libdir)/grip/guile/$(GUILE EFFECTIVE VERSION)/site-ccache In the above, $(datadir) is substituted to the default /usr/local/share or /your/prefix/share and $(libdir) is substituted to /usr/local/lib or /your/prefix/lib, when/if --prefix was passed. $(GUILE EFFECTIVE VERSION) is substituted to the stable version number with which Grip is being compile, for example, 2.2 Chapter 1: Introduction 4 Unless you passed --with-guile-site=yes, you must augment Guile's %load-path and %load-compiled-path, respectively, with the two (substituted) paths described above, so that Guile finds Grip's installed source modules and compiled files. To do this, you either (a) create/update your personnal ~/.guile file, (b) update Guile's global site init.scm file or (c) define/update both GUILE LOAD PATH and GUILE LOAD COMPILED PATH (Make sure you read Guile's manual `Environment Variables' and `Load Paths' subsections