File: hooks_and_scheme.txt

package info (click to toggle)
geda-doc 20020209-1
  • links: PTS
  • area: main
  • in suites: woody
  • size: 112 kB
  • ctags: 12
  • sloc: makefile: 27
file content (114 lines) | stat: -rw-r--r-- 4,421 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
gEDA - GNU 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!