Re: gEDA-user: Reinventing the wheel

[John Doty <jpd@xxxxxxxxx>]

On May 19, 2011, at 4:26 AM, Stephan Boettcher wrote:

>> I referred to the lack of documentation, rather than lack of comments.
>> The particular case I had in mind, is the interaction of gnetlist's 
>> C front-end with the scheme back-ends. There seems to be no documentation 
>> whatsoever, what data structure the front-end should use to communicate 
>> with the back-end.
> 
> Ok, yes, that is a valid point...  the lack of documented APIs.

Here's a start, posted once before.

gnetlist:get-packages level

Yields a list of refdes values for the set of schematics. Duplicated values are only listed once. The "level" argument must be present, but is unused.

gnetlist:get-non-unique-packages level

Yields a list of refdes values for the set of schematics. Duplicated values are listed as many times as they appear. The "level" argument must be present, but is unused.

gnetlist:get-pins refdes

Yields a list of pin numbers for the specified refdes value.

gnetlist:get-all-nets level

Yields a list of net names for the set of schematics. Duplicated values are listed as many times as they appear (once per segment?). The "level" argument must be present, but is unused.

gnetlist:get-all-unique-nets level

Yields a list of net names for the set of schematics. Duplicated values are only listed once. The "level" argument must be present, but is unused.

gnetlist:get-all-connections net

Yields a list of all connections to the named net. Each element of the list is itself a two element list of the form (refdes pinnumber).

gnetlist:get-nets refdes pin

This is apparently intended to yield the netname connected to the given pin along with all pins connected to that net, including the pin in the initial query. A little experimentation, however, shows that it does not reliably list all of the connections, possibly due to a problem with net= connections. Most (all?) existing back ends that use this appear to use only the netname.

gnetlist:get-pins-nets refdes

Yields a list of (pinnumber . netname) pairs detailing all connections for the given refdes.

gnetlist:get-package-attribute refdes attribute

Yields the value of the named attribute attached to a symbol instance with the given refdes. Yields "unknown" if the attribute is absent. It only yields one value, regardless of how many matching attributes exist in the set of schematics. If there is more than one instance only the first instance encountered is inspected, so it may yield "unknown, even if a matching attribute is present.

gnetlist:get-toplevel-attribute attribute

Yields the value of the named attribute at top level, that is, an attribute present in one of the schematics unattached to any object. Yields "not found" if no matching attribute is present.

gnetlist:get-renamed-nets level

When gnetlist expands a hierarchical subcircuit, it first assigns every net within the subcircuit a unique name based on the refdes of the subcircuit instance and, if present, the netname within the subcircuit. If a net is attached to the higher level circuit, gnetlist then changes the name of the subcircuit net to the name of the higher level net to which it is attached. "gnetlist:get-renamed-nets" returns a list of lists of pairs of names. The first name in a pair is the initial unique netname within the subcircuit, the second is the higher level netname it has acquired. The "level" argument must be present, but is unused.

gnetlist:get-attribute-by-pinseq refdes pinseq attribute

Yields the value of the named attribute attached to the pin with the named pinseq attribute to the package with the named refdes attribute.

gnetlist:get-attribute-by-pinnumber refdes pinnumber attribute

Yields the value of the named attribute attached to the pin with the named pinnumber attribute to the package with the named refdes attribute.

gnetlist:vams-get-package-attributes refdes

Yields a list of the names of attributes attached to the symbol at schematic level?

gnetlist:get-slots refdes

Yields a list of all slot attributes associated with a given refdes. Duplicated values are listed as many times as they appear.

gnetlist:get-unique-slots refdes

Yields a list of all slot attributes associated with a given refdes. Duplicated values are listed only once.

gnetlist:graphical-objs-in-net-with-attrib-get-attrib netname attrstring attribute

This searches for a graphical symbol attached to a net with the given netname. The symbol must have attrstring (of the form name=value) attached. It yields the value of the specified attribute,

gnetlist:get-calling-flags

Yields a list of lists of command line flags and values. Each flag must be known to the gnetlist front end. For example, the "--nomunge" flag will yield ("nomunge_mode" #t).

gnetlist:get-command-line

Broken or unimplemented? Yields #f.


Higher level functions built atop these are in:

wherever/share/gEDA/scheme/gnetlist.scm
wherever/share/gEDA/scheme/gnetlist-post.scm

These are fairly comprehensible, and somewhat commented, although I know of at least one developer who is deeply offended by the silliness of some of the comments.

And the wiki contains more tutorial-style stuff. So, is it really that bad?

John Doty              Noqsi Aerospace, Ltd.
http://www.noqsi.com/
jpd@xxxxxxxxx



_______________________________________________
geda-user mailing list
geda-user@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user