====== 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 /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 "/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!