# Hooks/Scheme Extension HOWTO

    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!