docs/wiki/geda-hse_howto.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <h1 class="sectionedit1" id="hooks_scheme_extension_howto">Hooks/Scheme Extension HOWTO</h1>
  14 <div class="level1">
  15 <pre class="code">gEDA - GPL Electronic Design Automation
  16
  17 HOOKS AND SCHEME EXTENSION IN GSCHEM
  18 ====================================
  19
  20 Copyright (C) 2000 Stefan Petersen
  21
  22 This program is free software; you can redistribute it and/or modify
  23 it under the terms of the GNU General Public License as published by
  24 the Free Software Foundation; either version 2 of the License, or
  25 (at your option) any later version.
  26
  27 This program is distributed in the hope that it will be useful,
  28 but WITHOUT ANY WARRANTY; without even the implied warranty of
  29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  30 GNU General Public License for more details.
  31
  32 You should have received a copy of the GNU General Public License
  33 along with this program; if not, write to the Free Software
  34 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  35
  36
  37 Introduction
  38 ------------
  39 gschem has a scheme interpreter (called Guile) built in. Though not
  40 complete, there are extensions to this interpreter to get access to
  41 different parts of the schematic.
  42
  43 There are a couple of other scheme extensions available that will not be
  44 described here. They belong mainly to rc-files (resource files in
  45 gEDA programs are really scheme scripts) and to the keymapping system
  46 (described in separate keymapping documentation).
  47
  48 The rest I will try to describe here.
  49
  50
  51 Scheme functions
  52 ----------------
  53 There are two function available for handling attributes in the schematic.
  54
  55 * get-attribute-name-value
  56 Inparameter  : an attribute
  57 Outparameter : a pair with the name of the attribute as string in the
  58                car element and the value of the attribute in the cdr
  59                element.
  60 Description  : Simply an accessor to the information hidden in the type
  61                attribute. The functionality of this is placed in libgeda
  62                since the C-type ATTRIBUTE is defined there.
  63
  64 * set-attribute-value!
  65 Inparameter  : an attribute and a string.
  66 Outparameter : undefined.
  67 Description  : Sets a new value to an attribute. The attribute must
  68                be defined, the function can&#039;t create a new attribute.
  69                Defined both in gschem and libgeda, mainly because
  70                where different variables and information are available.
  71
  72
  73 Hooks
  74 -----
  75 Hooks are a way to define functions that will be called during different
  76 part of a programs execution. In gschem there are (currently) three
  77 different hooks available:
  78 * add-component-hook
  79 * copy-component-hook
  80 * move-component-hook
  81
  82 As their name indicate, they are called at different occasions. When
  83 you add a component add-component-hook is called, etc.
  84
  85 To add a function to be called you simply use the Guile funtion add-hook!.
  86 An example; to run the function auto-uref when you add a component you
  87 simply add the following line, preferrably in ${HOME}/.gEDA/gschemrc:
  88 (add-hook! add-component-hook auto-uref)
  89
  90 The function to be called from a hook (for example auto-uref above) has
  91 to accept one parameter, a list of attributes.
  92
  93 A small example that prints all attributes on a component to be placed:
  94
  95 (define (print-all-attributes attribute-list)
  96   (foreach (lambda (attribute) (display attribute)) attribute-list))
  97
  98
  99 How to use this
 100 ---------------
 101 The most complete example utilizing all of the above functions are in fact
 102 the auto-uref scheme script that currently is part of the gschem distribution.
 103 You can find it &lt;where gschem is installed&gt;/share/gEDA/scheme/auto-uref.scm.
 104 Uninstalled it&#039;s available at gschem/scheme/auto-uref.scm
 105
 106 All components have a reference designator that must be unique so
 107 gnetlist can handle it properly. By automatically assigning a number
 108 to each instance of a component when you place and copy it, you can
 109 simplify the naming operation.
 110
 111 All components has, per default, an uref attribute, for example uref=R?.
 112 The letter varies with component type. The auto-uref script enumerates
 113 uref based on what prefix the component has and assigns a number.
 114
 115 For example, the first component you place has per default uref=U? gets
 116 the attribute uref=U1. Next component with uref=U? gets uref=U2 and so on.
 117
 118 To be able to use the auto-uref script you simply add two lines in
 119 ${HOME}/.gEDA/gschemrc. They are:
 120 (load &quot;&lt;where gschem is installed&gt;/share/gEDA/scheme/auto-uref.scm&quot;)
 121 (add-hook! add-component-hook auto-uref)
 122
 123 If you want auto enumeration to work when you copy the component too, you
 124 simply add the following line:
 125 (add-hook! copy-component-hook auto-uref)
 126
 127 Good luck!
 128 </pre>
 129
 130 </div>
 131 </body>
 132 </html>