====== gnetlist Scheme primitives ======

Originally written by //John Doty//

^ **Procedure**        | **gnetlist:get-packages** //level// |
| Yields a list of refdes values for the set of schematics. Duplicated values are only listed once. The string //level// must be present, but is unused.\\ **Usage:** ''%%(gnelist:get-packages "")%%'' ||
^ **Procedure**        | **gnetlist:get-non-unique-packages** //level// |
| The same as **gnetlist:get-packages**, but duplicated values are listed as many times as they appear. \\ **Usage:** ''%%(gnetlist:get-non-unique-packages "")%%'' ||
^ **Procedure**        | **gnetlist:get-pins** //refdes// |
| Yields a list of pin numbers for the specified //refdes// value, which must be a string. \\ **Usage:**  ''%%(gnetlist:get-pins "R1")%%'' ||
^ **Procedure**        | **gnetlist:get-all-nets** //level// |
| Yields a list of net names of nets connected to pins of all components for the set of schematics. Duplicated values are listed as many times as they appear once per pin. The string //level// must be present, but is unused. \\ **Usage:**  ''%%(gnetlist:get-all-nets "")%%'' ||
^ **Procedure**        | **gnetlist:get-all-unique-nets** //level// |
| The same as **gnetlist:get-all-nets**, but duplicated values are only listed once. \\ **Usage:**  ''%%(gnetlist:get-all-unique-nets "")%%'' ||
^ **Procedure**        | **gnetlist:get-all-connections** //net// |
| Yields a list of all connections to the named //net//, which must be a string. Each element of the list is itself a two element list of the form ''(refdes pinnumber)''. \\ **Usage:**  ''%%(gnetlist:get-all-connections "3")%%'' ||
^ **Procedure**        | **gnetlist:get-nets** //refdes pin// |
| Yields a list of the form ''(netname connection1 connection2 ...)'' where the //netname// is a name of the net connected to the //pin// of the component with the given //refdes//, and each connection is itself a two element list of the form ''(refdes pinnumber)'' representing the pin with the //pinnumber// of the component with the //refdes//.  All arguments must be strings.  \\ **Usage:**  ''%%(gnetlist:get-nets "R1" "1")%%'' \\ //BUG:// This function does not reliably list all of the connections, if a [[geda:na_howto|net=]] connection is specified. All existing back ends that use this (excluding the **cascade** back end) use only the netname. ||
^ **Procedure**        | **gnetlist:get-pins-nets** //refdes// |
| Yields a list of ''(pinnumber . netname)'' pairs detailing all pin connections for the given refdes. \\ **Usage:**  ''%%(gnetlist:get-pins-nets "R1")%%'' ||
^ **Procedure**        | **gnetlist:get-all-package-attributes** //refdes attribute// |
| Yields the list of values of the first found named //attribute// attached to all symbol instances with the given //refdes//. If an instance has no such attribute, ''#f'' is added to the list. All arguments must be strings. \\ **Usage:**  ''%%(gnetlist:get-all-package-attributes "D1" "slot")%%'' ||
^ **Procedure**        | **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. All arguments must be strings.  \\ **Usage:**  ''%%(gnetlist:get-package-attribute "R1" "device")%%'' \\ //BUG:// 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. ||
^ **Procedure**        | **gnetlist:get-toplevel-attribute** //attribute// |
| Yields the value of the named //attribute//, which must be a string, 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. \\ **Usage:**  ''%%(gnetlist:get-toplevel-attribute "schematic-name")%%'' ||
^ **Procedure**        | **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 string //level// argument must be present, but is unused. \\ **Usage:**  ''%%(gnetlist:get-renamed-nets "")%%'' ||
^ **Procedure**        | **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. All arguments must be strings. \\ **Usage:**  ''%%(gnetlist:get-attribute-by-pinseq "R1" "1" "pinlabel")%%'' ||
^ **Procedure**        | **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.  All arguments must be strings. \\ **Usage:**  ''%%(gnetlist:get-attribute-by-pinnumber "R1" "1" "pinlabel")%%'' ||
^ **Procedure**        | **gnetlist:vams-get-package-attributes** //refdes// |
| Yields a list of the names of attributes attached to the package with the named //refdes//, which must be a string. \\ **Usage:**  ''%%(gnetlist:vams-get-package-attributes "R1")%%'' \\ //BUG:// If there is more than one instance only the first instance encountered is inspected. ||
^ **Procedure**        | **gnetlist:get-slots** //refdes// |
| Yields a list of integers representing all slot attributes associated with a given //refdes//, which must be a string. Duplicated values are listed as many times as they appear. \\ **Usage:**  ''%%(gnetlist:get-slots "D3")%%'' ||
^ **Procedure**        | **gnetlist:get-unique-slots** //refdes// |
| The same as **gnetlist:get-slots**, but duplicated values are listed only once. \\ **Usage:**  ''%%(gnetlist:get-unique-slots "D3")%%'' ||
^ **Procedure**        | **gnetlist:graphical-objs-in-net-with-attrib-get-attrib** //netname attribute-string attribute-name// |
| This searches for a [[geda:master_attributes_list#graphical|graphical symbol]] attached to a net with the given //netname//. The symbol must have //attribute-string// (of the form ''name=value'') attached. It yields the value of the specified attribute named //attribute-name//. All arguments must be strings. \\ **Usage:**  ''%%(gnetlist:graphical-objs-in-net-with-attrib-get-attrib "undriven_net" "device=DRC_Directive" "value")%%'' ||
^ **Procedure**        | **gnetlist:get-backend-arguments** |
| Yields a list of arguments passed to the gnetlist backend via the ''-O'' command-line option. \\ **Usage:**  ''%%(gnetlist:get-backend-arguments)%%'' ||
^ **Procedure**        | **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 ''%%-O nomunge_mode%%'' option will yield ''%%("nomunge_mode" #t)%%''. \\ **Usage:**  ''%%(gnetlist:get-calling-flags)%%'' \\ //NOTE:// This function is deprecated and should not be used in new code.  New code should use **gnetlist:get-backend-arguments** directly. ||
^ **Procedure**        | **gnetlist:get-input-files** |
| Yields a list of the files named on the command line.  \\ **Usage:**  ''%%(gnetlist:get-input-files)%%'' ||
^ **Procedure**        | **gnetlist:get-command-line** |
| Yields the command line used to invoke the program. \\ **Usage:**  ''%%(gnetlist:get-command-line)%%'' \\ //BUG:// As of **''gnetlist''** version 1.9.1 it is broken and outputs command line arguments passed to **''guile''** instead of those of **''gnetlist''**. ||
| Yields a number corresponding to the verbosity mode specified on the command-line: ''1'' for verbose mode, ''-1'' for quiet mode, and ''0'' otherwise. \\ **Usage:**  ''%%(gnetlist:get-verbosity)%%'' ||
^ **Procedure**        | **gnetlist-version** |
| Yields ''#t'' if the version numbers of the **''gnetlist''** rc files and that of gEDA/gaf do not differ, otherwise yields ''#f'' and outputs warning. \\ **Usage:**  ''%%(gnetlist-version)%%'' ||

See the [[geda:hierarchy]] page for information about **''gnetlist''** rc settings.