ComponentLibraries (issie) | issie

ComponentLibraries Module

Namespace: global
Assembly: Renderer.dll

Types and nested modules

Type/Module	Description
Constants
ComponentLibrary	A library as offered in the catalogue: a name and a directory. Its components are read when the user opens it, never at startup.
ComponentShape	What a library component becomes on the canvas, without materialising it: the ports its symbol will have, and whether that symbol is drawn as clocked. This is what the catalogue needs to draw a component being carried to the sheet. It is read from the sheet rather than declared in the header for the reason the header gives: nothing derived is stored, so nothing can be out of date with the sheet it describes.
LibraryFile	A component file: its header, and its sheet as the exact text of a .dgm. The body is a string, not a parsed canvas, so that reading a header never builds one and materialising is a file write followed by the ordinary loader.
LibraryHeader	What the catalogue needs to know about a component without reading its sheet. Deliberately does NOT carry the component's parameters, ports, or anything else derived from the sheet. All of that is read from the body, once, just before it is needed - which is why this cannot drift from the sheet it describes.
LibraryListing	One component of an opened library, as listed.
OpenedLibrary	What opening a library found: the components it can offer, and anything that would not read. A file that will not read costs that component, never the library.

Functions and values

Function or value	Description
`componentPath libPath name` Full Usage: `componentPath libPath name` Parameters: libPath : `string` name : `string` Returns: `string`	libPath : `string` name : `string` Returns: `string`
`customSheetsUsedBy ldc` Full Usage: `customSheetsUsedBy ldc` Parameters: ldc : `LoadedComponent` Returns: `string list`	The sheets a sheet instantiates, by name and without duplicates. Used to fill in a header's Requires when a component is saved, and to find everything that must be saved with it. ldc : `LoadedComponent` Returns: `string list`
`findLibraries ()` Full Usage: `findLibraries ()` Parameters: () : `unit` Returns: `ComponentLibrary list`	The libraries available: those shipped with Issie, and those the user has made or imported. Directory names only - no file is opened - so this is cheap enough for startup, which it has to be: the catalogue is a pure render function and cannot read the disk itself. Everything about a component is read later, when its library is opened. A user library with the same name as a shipped one wins, so a library can be overridden. () : `unit` Returns: `ComponentLibrary list`
`isLibrarySheet ldc` Full Usage: `isLibrarySheet ldc` Parameters: ldc : `LoadedComponent` Returns: `bool`	True when a sheet came from a library. ldc : `LoadedComponent` Returns: `bool`
`libraryIndexFor ldcs libraryName` Full Usage: `libraryIndexFor ldcs libraryName` Parameters: ldcs : `LoadedComponent list` libraryName : `string` Returns: `int`	The index to use for a library in this project: the one it already has if any of its sheets are present, otherwise the lowest free index. An index is free when no other library holds it and NO existing sheet begins with its prefix - not merely none of the names this library would produce. User sheet names may themselves contain underscores, so a project can already hold a sheet called L1_Anything, and letting a library share a prefix with an unrelated sheet would be confusing even where nothing actually collides. A prefix in use is skipped rather than anything being renamed or refused. ldcs : `LoadedComponent list` libraryName : `string` Returns: `int`
`libraryOfSheet ldc` Full Usage: `libraryOfSheet ldc` Parameters: ldc : `LoadedComponent` Returns: `(string * int) option`	The library and index a sheet belongs to, if it is a library sheet. ldc : `LoadedComponent` Returns: `(string * int) option`
`openLibrary library` Full Usage: `openLibrary library` Parameters: library : `ComponentLibrary` Returns: `OpenedLibrary`	Read the headers of a library's components. Done when the user opens the library, and not kept: it is one small read per component, on an action the user took, and keeping it would mean deciding when it had gone wrong. library : `ComponentLibrary` Returns: `OpenedLibrary`
`prefixFor libraryIndex` Full Usage: `prefixFor libraryIndex` Parameters: libraryIndex : `int` Returns: `string`	The prefix owned by a library index. libraryIndex : `int` Returns: `string`
`readComponentAndDependencies libPath name` Full Usage: `readComponentAndDependencies libPath name` Parameters: libPath : `string` name : `string` Returns: `Result<LibraryFile list, string>`	A component and everything it needs, dependencies first - the order they must be written in. Dependencies are named rather than embedded, so they are read from the same library here. A name that is not there is an error rather than a silent omission: the component would otherwise be placed holding a custom component that refers to a sheet which does not exist. libPath : `string` name : `string` Returns: `Result<LibraryFile list, string>`
`reservedPrefixOf ldcs sheetName` Full Usage: `reservedPrefixOf ldcs sheetName` Parameters: ldcs : `LoadedComponent list` sheetName : `string` Returns: `string option`	The reserved prefix a proposed sheet name would intrude on, if any. Used to refuse the name when a sheet is created or renamed. ldcs : `LoadedComponent list` sheetName : `string` Returns: `string option`
`reservedPrefixes ldcs` Full Usage: `reservedPrefixes ldcs` Parameters: ldcs : `LoadedComponent list` Returns: `string list`	The prefixes the libraries used by this project own. Once a library holds a prefix no sheet may be named into it, or a component of that library added later would have nowhere to go. ldcs : `LoadedComponent list` Returns: `string list`
`sheetNameFor libraryIndex compName` Full Usage: `sheetNameFor libraryIndex compName` Parameters: libraryIndex : `int` compName : `string` Returns: `string`	The name a library component takes as a sheet of a project. libraryIndex : `int` compName : `string` Returns: `string`
`tryReadComponentFile path` Full Usage: `tryReadComponentFile path` Parameters: path : `string` Returns: `Result<LibraryFile, string>`	Read one .ldgm. The body comes back as text: there is little to gain from decoding less, since it is a single JSON string token either way. path : `string` Returns: `Result<LibraryFile, string>`
`tryReadComponentShape libPath name` Full Usage: `tryReadComponentShape libPath name` Parameters: libPath : `string` name : `string` Returns: `Result<ComponentShape, string>`	The shape of one component of a library, read from the same files placing it will read. Every sheet is decoded, not just the component's own: whether it is clocked can depend on a sheet it uses, and its ports come from the last one, which is the component itself. libPath : `string` name : `string` Returns: `Result<ComponentShape, string>`
`tryReadHeader path` Full Usage: `tryReadHeader path` Parameters: path : `string` Returns: `Result<LibraryHeader, string>`	The header of one component. path : `string` Returns: `Result<LibraryHeader, string>`
`tryUserLibrariesDirectory ()` Full Usage: `tryUserLibrariesDirectory ()` Parameters: () : `unit` Returns: `Result<string, string>`	Where libraries the user makes or imports are kept. Those shipped with Issie stay read-only under the installation; this is the writable side. Error when the directory cannot be made - see FilesIO.tryUserDataDirectory for why that is a real possibility and not a theoretical one. () : `unit` Returns: `Result<string, string>`
`unusedLibrarySheets ldcs` Full Usage: `unusedLibrarySheets ldcs` Parameters: ldcs : `LoadedComponent list` Returns: `LoadedComponent list`	Library sheets no sheet instantiates any more, and so which should be dropped from the project. A library sheet used only by another library sheet of the same component is kept, since that one is reachable; the calculation is repeated until it settles so that a multi-sheet component goes in one piece. Deliberately NOT run when the instance is deleted: undo restores model snapshots, so deleting the sheet there would leave undo unable to bring it back. Sweeping when the project is saved or closed keeps deletion undoable. ldcs : `LoadedComponent list` Returns: `LoadedComponent list`
`writeComponentFile libPath header body` Full Usage: `writeComponentFile libPath header body` Parameters: libPath : `string` header : `LibraryHeader` body : `string` Returns: `Result<unit, string>`	Write a component file. Used by "save as library component". `body` must be the text of a .dgm exactly as the sheet was saved, since that is what is written back out when it is used. libPath : `string` header : `LibraryHeader` body : `string` Returns: `Result<unit, string>`