Add model edit tool (#258)

docs/Makefile.mk

@@ -2,6 +2,7 @@
 DOCS = 
 DOCS += docs/Utilities/Framework.md
 DOCS += docs/Utilities/Network.md
+DOCS += docs/Utilities/Model.md
 DOCS += docs/Utilities/Mapping.md
 DOCS += docs/Utilities/Unitcalc.md
 

docs/Utilities/Framework.md

@@ -3,11 +3,61 @@
 The `framework` module contains the infrastructure to support standardized
 implementation of tools in GridLAB-D.
 
+Example:
+
+~~~
+import framework as app
+
+def main(argv):
+
+    if len(argv) == 1:
+
+        print("
+".join([x for x in __doc__.split("
+") if x.startswith("Syntax: ")]))
+        return app.E_SYNTAX
+
+    args = read_stdargs(argv)
+
+    for key,value in args:
+
+        if key in ["-h","--help","help"]:
+            print(__doc__,file=sys.stdout)
+        else:
+            error(f"'{key}={value}' is invalid")
+            return app.E_INVALID
+
+    return app.E_OK
+
+if __name__ == "__main__":
+
+    try:
+
+        rc = main(sys.argv)
+        exit(rc)
+
+    except KeyboardInterrupt:
+
+        exit(app.E_INTERRUPT)
+
+    except Exception as exc:
+
+        if DEBUG:
+            raise exc
+
+        if not QUIET:
+            e_type,e_value,e_trace = sys.exc_info()
+            tb = traceback.TracebackException(e_type,e_value,e_trace).stack[1]
+            print(f"EXCEPTION [{app.EXEFILE}@{tb.lineno}]: ({e_type.__name__}) {e_value}",file=sys.stderr)
+
+        exit(app.E_EXCEPTION)
+~~~
+
 
 
 # Functions
 
-## `complex_unit(x:str, form:str, prec:str, unit:str) -> None`
+## `complex_unit() -> None`
 
 Convert complex value with unit
 
@@ -33,7 +83,7 @@ Returns:
 
 ---
 
-## `double_unit(x:str) -> float`
+## `double_unit() -> float`
 
 Convert a string with unit to a float
 
@@ -46,7 +96,7 @@ Returns:
 
 ---
 
-## `gridlabd(args:list) -> Optional`
+## `gridlabd() -> Optional`
 
 Simple gridlabd runner
 
@@ -69,7 +119,7 @@ See also:
 
 ---
 
-## `integer(x:str) -> int`
+## `integer() -> int`
 
 Convert a string to an integer
 
@@ -82,7 +132,7 @@ Returns:
 
 ---
 
-## `open_glm(file:str, tmp:str, init:bool) -> io.TextIOWrapper`
+## `open_glm() -> io.TextIOWrapper`
 
 Open GLM file as JSON
 
@@ -94,14 +144,18 @@ Arguments:
 
 * `init`: enable model initialization during conversion
 
+* `exception`: enable raising exception instead of returning (None,result)
+
+* `passthru`: enable passing stderr output through to app
+
 Return:
 
 * File handle to JSON file after conversion from GLM
 
 
 ---
 
-## `read_stdargs(argv:list) -> list`
+## `read_stdargs() -> list`
 
 Read framework options
 
@@ -116,7 +170,7 @@ Returns:
 
 ---
 
-## `version(terms:str) -> str`
+## `version() -> str`
 
 Get gridlabd version
 

docs/Utilities/Mapping.md

@@ -178,7 +178,7 @@ Mapping exception
 
 # Functions
 
-## `complex_unit(x:str, form:str, prec:str, unit:str) -> None`
+## `complex_unit() -> None`
 
 Convert complex value with unit
 
@@ -204,7 +204,7 @@ Returns:
 
 ---
 
-## `double_unit(x:str) -> float`
+## `double_unit() -> float`
 
 Convert a string with unit to a float
 
@@ -217,7 +217,7 @@ Returns:
 
 ---
 
-## `get_options(value:str, default:dict) -> dict`
+## `get_options() -> dict`
 
 Extract save/show options from argument value
 
@@ -234,7 +234,7 @@ Returns:
 
 ---
 
-## `gridlabd(args:list) -> Optional`
+## `gridlabd() -> Optional`
 
 Simple gridlabd runner
 
@@ -257,7 +257,7 @@ See also:
 
 ---
 
-## `integer(x:str) -> int`
+## `integer() -> int`
 
 Convert a string to an integer
 
@@ -270,7 +270,7 @@ Returns:
 
 ---
 
-## `main(argv:list) -> int`
+## `main() -> int`
 
 Command line processing
 
@@ -285,7 +285,7 @@ Returns:
 
 ---
 
-## `open_glm(file:str, tmp:str, init:bool) -> io.TextIOWrapper`
+## `open_glm() -> io.TextIOWrapper`
 
 Open GLM file as JSON
 
@@ -297,14 +297,18 @@ Arguments:
 
 * `init`: enable model initialization during conversion
 
+* `exception`: enable raising exception instead of returning (None,result)
+
+* `passthru`: enable passing stderr output through to app
+
 Return:
 
 * File handle to JSON file after conversion from GLM
 
 
 ---
 
-## `read_stdargs(argv:list) -> list`
+## `read_stdargs() -> list`
 
 Read framework options
 
@@ -319,7 +323,7 @@ Returns:
 
 ---
 
-## `version(terms:str) -> str`
+## `version() -> str`
 
 Get gridlabd version
 

docs/Utilities/Model.md

@@ -0,0 +1,158 @@
+[[/Utilities/Model]] -- Model editor tool
+
+Syntax: `gridlabd model FILENAME [COMMANDS ...] [OPTIONS ...]`
+
+Options:
+
+* `-s|--save=FILENAME`: save output to FILENAME
+
+Commands:
+
+* `add=NAME,PROPERTY:VALUE[,...]`: add an object
+
+* `delete=PATTERN[,PROPERTY:VALUE]`: delete objects
+
+* `get=PATTERN[,PROPERTY:VALUE`: get object data
+
+* `globals=[PATTERN|NAME][,PROPERTY:VALUE]: get/set globals
+
+* `copy=PATTERN[,PROPERTY:VALUE]: copy objects 
+
+* `list=PATTERN[,PROPERTY:VALUE]`: list objects
+
+* `modify=PATTERN,PROPERTY:VALUE[,...]`: modify object data
+
+* `move=PATTERN[,PROPERTY:VALUE]: move objects 
+
+Description:
+
+The model editor utility allows command-line and python-based editing of models.
+
+PATTERN is a regular expression used to match object or global names. PROPERTY
+and VALUE can be regular expressions or a property name and value tuple for
+get or set operations, respectively. When comma-separated patterns are
+allowed, they are interpreted as `and` operations. Note that the `add`
+command does not use regular expressions for NAME.
+
+Output is always generated as a CSV table with property names in the header row.
+
+Commands that modify or delete objects or data will output the old value(s).
+
+The output FILENAME format is limited to JSON.
+
+Caveat:
+
+The model editor does not check whether the action will result in a faulty
+model, e.g., deleting a node that is referened by a link, add a property that
+is not valie for the class, or changing an object property to something invalid.
+
+Examples:
+
+    gridlabd model ieee13.glm list='Node6[1-4],id:3[23]'
+    gridlabd model ieee13.glm get='Node6,GFA.*'
+    gridlabd model ieee13.glm get='Node633,class,id'
+    gridlabd model ieee13.glm delete=Node633 --save=ieee13.json
+    gridlabd model ieee13.glm delete=(from|to):Node633 --save=ieee13_out.json
+    gridlabd model ieee13.glm delete=XFMR,(from|to):Node633 --save=ieee13_out.json
+    gridlabd model ieee13.glm add=Node14,class:node,bustype:SWING --save=ieee13_out.json
+    gridlabd model ieee13.glm modify=Node633,class:substation --save=ieee13_out.json
+
+
+
+
+# Classes
+
+## Editor
+
+GLM Model Editor
+
+
+### `Editor.add() -> None`
+
+Add objects
+
+Arguments:
+
+* `args`: object name pattern followed by desired properties patterns (if any)
+
+* `kwargs`: key and value patterns to match properties
+
+Returns:
+
+`dict`: object properties added
+
+
+### `Editor.delete() -> None`
+
+Delete objects
+
+Arguments:
+
+* `args`: object name pattern followed by desired properties patterns (if any)
+
+* `kwargs`: key and value patterns to match properties
+
+Returns:
+
+`dict`: deleted object properties
+
+
+### `Editor.get() -> None`
+
+Get object properties
+
+Arguments:
+
+* `args`: object name pattern followed by desired properties patterns (if any)
+
+* `kwargs`: key and value patterns to match properties
+
+Returns:
+
+`dict`: object properties
+
+
+### `Editor.globals() -> None`
+
+Read/write globals
+
+Arguments:
+
+* `args`: globals name pattern followed by desired properties patterns (if any)
+
+* `kwargs`: key and value patterns to get/set globals
+
+Returns:
+
+`dict`: global properties added
+
+
+### `Editor.list() -> None`
+
+Generate a list of objects
+
+Arguments:
+
+* `args`: object name patterns (and'ed, default is ".*")
+
+* `kwargs`: property criteria patterns (and'ed, default is ".*")
+
+Returns:
+
+`list`: object names matching criteria
+
+
+### `Editor.modify() -> None`
+
+Modify object properties
+
+Arguments:
+
+* `args`: object name pattern followed by desired properties patterns (if any)
+
+* `kwargs`: key and value patterns to match properties
+
+Returns:
+
+`dict`: object properties prior to modification
+