Dear all,
After almost 18 months of design, preliminary work, and research, I am
pleased present my latest gEDA Big Project.
### A COMPREHENSIVE SCHEME API FOR gEDA ###
One of the most common problems encountered by gschem users is the
difficulty of adding new tools and commands for altering the schematic
or symbol being edited.
Now, thanks to being able to rely on the advanced features of Guile 1.8,
and with the aid of lots of excellent work done by Peter Clifton, this
problem has been solved.
Since my last gEDA upgrade project -- the integrated build system
released in gEDA 1.6.0, which I know many found to be a step improvement
over what came before -- I have been working on a new Scheme API for
libgeda, that allows for arbitrary inspection and manipulation of the
schematic document model, while maintaining clean separation between the
libgeda and the code that interfaces with Guile.
And it's now ready to try out!
### HOWTO: INSTALL & USE THE SCHEME API BRANCH ###
You will need to obtain my `guile-scheme-api' branch from my public git
repository. The following commands should get you a copy of the source
code:
# Clone the repository
git clone git://repo.or.cz/geda-gaf/peter-b.git
cd peter-b
# Checkout the branch
git checkout -t origin/guile-scheme-api
# Configure & compile
./autogen.sh
./configure <your-configure-arguments>
make
make install
You can run the test suite for the Scheme API:
# (cd libgeda && make check)
As an example of how gschem plugins can be written using this API, the
attached `hide-pinseq.scm' file is a plugin for hiding all "pinseq"
attributes on the current page. To use it, place it in the same
directory as the symbol you want to edit, and create a gschemrc in that
directory with the following contents:
;; Load `hide-pinseq' plugin
(load "hide-pinseq.scm")
Run gschem, and open the symbol. Press `:' to bring up the Scheme
prompt, and type:
(hide-pinseq)
This will set all "pinseq=" attributes of all pin objects in the symbol
to be invisible. If you want to make them visible again, you can run:
(hide-pinseq #t)
### THE DETAILS ###
The majority of the new code is located in libgeda.
The C language binding is implemented in libgeda/src, in the new
`scheme_*.c' files. As far as possible, it uses the libgeda public C
API, and it is written in idiomatic Guile C -- i.e. it uses Scheme
exceptions for reporting errors, it is designed to be tolerant of
non-local exits, and it uses the `guile-snarf' tool to generate the
Guile boilerplate. It relies heavily on the new weak reference
mechanism added to the unstable branch of gEDA since the 1.6.0 release
to allow the C code to destroy heap-allocated structures safely. Most
of the functions defined in the C language binding are inaccessible from
programs which use libgeda; the public API can be found in
`libgeda/libgedaguile.h'.
At the moment, the language binding is as minimal as possible. The
emphasis has been on correctness rather than high performance or broad
functionality. The low-level modules that are available are as follows:
(geda core smob)
(geda core toplevel)
(geda core page)
(geda core object)
(geda core complex)
(geda core attrib)
This API (and any function or variable beginning with a `%' is
considered an implementation detail, and may be subject to change.
Normally, you should use the functions in the following modules, written
in Scheme and found in the `libgeda/scheme/geda' directory. At the
moment, the documentation is limited to the comments in those Scheme
files.
(geda page)
(geda object)
(geda attrib)
(gschem window)
All of the functions in these files are unit tested. The unit tests can
be found in the `libgeda/scheme/unit-tests' directory.
### CONTRIBUTING ###
Even though it's already obviously useful as it currently is, there's
still a lot that can be done to flesh out and otherwise improve the API
before it will be ready to merge into the main gEDA unstable branch.
Please help out! I've tried to document all of the relevant code as
fully as possible, and I recommend the excellent Guile reference manual.
Please also test the code to destruction! Any bug reports will be very
gratefully accepted!
From now on my `guile-scheme-api' branch will not be rebased, so it
should be a safe base for developing your own code. I accept `git
format-patch' patches by e-mail -- please e-mail with [PATCH] in the
subject line. I also will accept merge requests -- please e-mail me
with [MERGE] in the subject line. Patches should be fully
documented/commented and must include unit tests where possible.
Obviously, since this is an unofficial branch, please don't submit
patches or bugs to the official gEDA trackers. ;-)
Happy hacking!
Peter
--
Peter Brett <peter@xxxxxxxxxxxxx>
Remote Sensing Research Group
Surrey Space Centre
;; gschem plugin for hiding "pinseq=" attributes
;; Copyright (C) 2010 Peter Brett
;;
;; 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., 59 Temple Place, Suite 330, Boston, MA 02111 USA
;;
(use-modules (geda object))
(use-modules (geda attrib))
(use-modules (geda page))
(use-modules (gschem window))
(use-modules (ice-9 optargs))
(define* (hide-pinseq #:optional (visibility #f))
(for-each
;; This function sets a text object's visibility.
(lambda (x)
(let ((params (text-info x)))
(list-set! params 5 visibility)
(apply set-text! x params)))
(filter!
(lambda (x) ; Select object for modification if...
(and (text? x) ; ...it is a text object...
(pin? (attrib-attachment x)) ; ...and it is attached to a pin...
(equal? "pinseq" (attrib-name x)))) ; ...and it is a "pinseq" attrib.
(page-contents (active-page)))))
Attachment:
pgpp1M7YPCf1l.pgp
Description: PGP signature
_______________________________________________ geda-user mailing list geda-user@xxxxxxxxxxxxxx http://www.seul.org/cgi-bin/mailman/listinfo/geda-user