gEDA - GPL Electronic Design Automation

HOOKS AND SCHEME EXTENSION IN GSCHEM
==================================== 

Copyright (C) 2000 Stefan Petersen

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 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 General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Introduction
------------
gschem has a scheme interpreter (called Guile) built in. Though not 
complete, there are extensions to this interpreter to get access to 
different parts of the schematic.

There are a couple of other scheme extensions available that will not be 
described here. They belong mainly to rc-files (resource files in 
gEDA programs are really scheme scripts) and to the keymapping system 
(described in separate keymapping documentation).

The rest I will try to describe here. 


Scheme functions
----------------
There are two function available for handling attributes in the schematic.

* get-attribute-name-value
Inparameter  : an attribute
Outparameter : a pair with the name of the attribute as string in the 
	       car element and the value of the attribute in the cdr 
	       element.
Description  : Simply an accessor to the information hidden in the type
	       attribute. The functionality of this is placed in libgeda
	       since the C-type ATTRIBUTE is defined there.

* set-attribute-value!
Inparameter  : an attribute and a string.
Outparameter : undefined.
Description  : Sets a new value to an attribute. The attribute must 
               be defined, the function can't create a new attribute. 
	       Defined both in gschem and libgeda, mainly because 
	       where different variables and information are available.


Hooks
-----
Hooks are a way to define functions that will be called during different
part of a programs execution. In gschem there are (currently) three 
different hooks available:
* add-component-hook
* copy-component-hook
* move-component-hook

As their name indicate, they are called at different occasions. When 
you add a component add-component-hook is called, etc.

To add a function to be called you simply use the Guile funtion add-hook!.
An example; to run the function auto-uref when you add a component you
simply add the following line, preferrably in ${HOME}/.gEDA/gschemrc:
(add-hook! add-component-hook auto-uref)

The function to be called from a hook (for example auto-uref above) has 
to accept one parameter, a list of attributes.

A small example that prints all attributes on a component to be placed:

(define (print-all-attributes attribute-list)
  (foreach (lambda (attribute) (display attribute)) attribute-list))


How to use this
---------------
The most complete example utilizing all of the above functions are in fact
the auto-uref scheme script that currently is part of the gschem distribution.
You can find it <where gschem is installed>/share/gEDA/scheme/auto-uref.scm.
Uninstalled it's available at gschem/scheme/auto-uref.scm

All components have a reference designator that must be unique so 
gnetlist can handle it properly. By automatically assigning a number
to each instance of a component when you place and copy it, you can 
simplify the naming operation.

All components has, per default, an uref attribute, for example uref=R?. 
The letter varies with component type. The auto-uref script enumerates 
uref based on what prefix the component has and assigns a number. 

For example, the first component you place has per default uref=U? gets 
the attribute uref=U1. Next component with uref=U? gets uref=U2 and so on.

To be able to use the auto-uref script you simply add two lines in
${HOME}/.gEDA/gschemrc. They are:
(load "<where gschem is installed>/share/gEDA/scheme/auto-uref.scm")
(add-hook! add-component-hook auto-uref)

If you want auto enumeration to work when you copy the component too, you 
simply add the following line:
(add-hook! copy-component-hook auto-uref)

Good luck!