The store tutorial glides over this bit, to wit: image storage variables have the same visibility as any other command line variable. This can lead to retrieval —um— ‘surprises’ when storing images in different scopes (need to mention this in Tutorial Land. Noting it here for now). This cautionary primarily concerns -store
; +store
duplicates images before storage.
If they are to be manipulated cooperatively by some number of custom commands, then it is probably safest to store images using globally visible variables (those prepended with _
).
Locally defined storage variable gotcha: Images, selected by some custom command and stored by such commands through locally defined variables — ones that are visible in just those custom commands — cannot be subsequently retrieved in the parent context. That is because locally defined variables of custom commands are deleted upon scope return, leaving no keys behind in the parent context to retrieve the images.
Such images, selected by custom commands and stored through them, are effectively deleted by the custom command, insofar as the parent context is concerned.
TL;DR:
Test (1–9) results - see ‘Gory Details’ for gory details. Summaries here:
- Can create an image, name it ‘CarmenSanDiego’ and confirm that it is on the image list.
- Can store ‘CarmenSanDiego’ (using
-
prefix) harnessing a local variable, sandiego
.
2a. The image ‘CarmenSanDiego’ disappears from the image list, as expected.
2b. The image data for ‘CarmenSanDiego’ is available in the math environment via get()
, using the key sandiego
.
- Cannot retrieve the image ‘CarmenSanDiego’ through a custom command (which operates in a child scope), using the key
sandiego
defined in the parent scope. The custom command just creates a different variable in its child scope. That different variable bears no relationship to any similarly named local variable in the parent scope.
- So long as there is no scope change, the local variable
sandiego
can be used to restore image ‘CarmenSanDiego’ by way of the -input
command, (as advertised).
4a. The retrieval also restores the image’s collection membership, if any.
- Deleting (re-referencing) the key
sandiego
throws away the reference to the stored image — effectively deleting it, as @Reptorian observed — even in math environments. Already retrieved images, now safe on the image list, are unaffected.
- Custom commands may store their selected images using local storage variables, then retrieve and otherwise manipulate them in the child context, but:
6a. The parent scope can’t retrieve images that (1) have been cited in custom command selections, and (2) stored in local storage variables: the local storage variables go out of scope on the custom command’s exit; they cannot then be used as retrieval keys in the parent context.
6b. Such custom commands, effectively, delete their selections.
6c. Such deleted images are also not available in the math environment.
- Can store CarmenSanDiego (using
-
prefix) harnessing a global variable, _sandiego
.
7a. The image ‘CarmenSanDiego’ disappears from the image list, as expected.
- A custom command (creating a child context) can restore the image ‘CarmenSanDiego’ harnessing the global variable
_sandiego
.
Gory Details
witwicsd.gmic:
whereintheworldiscarmensandiego :
# Carmen San Diego:
-input 1
-name. CarmenSanDiego
carmensz:=whds
-named "CarmenSanDiego"
-echo "\nCarmenSanDiego has one pixel…"
-echo "$0: (1.) Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: (1.) Image list length, pre-CarmenSanDiego storage: "$!"."
-echo "\nStoring CarmenSanDiego in a local storage variable named 'sandiego'."
-store[CarmenSanDiego] sandiego
-named "CarmenSanDiego"
-echo "$0: (2.) Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: (2.) Image list length following-CarmenSanDiego storage: "$!"."
# Something like CarmenSanDiego in a mathematical expression environment?
-echo "\n(2 Looking in math.) Something like CarmenSanDiego in a mathematical expression environment?"
-eval ">
V=get('sandiego',"$carmensz");
print(V)
"
# Go to another scope (custom command 'showcarmen'). That scope tries to get CarmenSanDiego via $sandiego.
-echo "\nCustom command 'showcarmen' attempts to fetch CarmenSanDiego via 'sandiego' (It should throw an exception)."
-showcarmen
-named "CarmenSanDiego"
-echo "$0: (3.) Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: (3.) Image list length, following showcarmen fetch: "$!"."
# Try to retrieve CarmenSanDiego in the current scope.
-echo "\nRetrieving CarmenSanDiego from the local storage variable named 'sandiego'\nExpect collection affiliations to be restored as well."
-input $sandiego
-named "CarmenSanDiego"
-echo "$0: (4.) Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: (4.) Image list length, following sandiego fetch in same scope: "$!"."
-echo "$0: (4.) The command interpreter local variable key 'sandiego' references: "$sandiego"."
# Delete key. referenced value gone?
-echo "\nDelete key sandiego. Referenced value now gone? Collection 'CarmenSanDiego' gone too?"
-echo "$0: (5.) Dereferencing key 'sandiego'."
sandiego=
-echo "$0: After dereferencing 'sandiego', can a mathematical expression environment still fetch 'sandiego' as a vector?"
-eval ">
V=get('sandiego',"$carmensz");
print(V)
"
-echo "$0: (5.) After dereferencing, the command interpreter local variable key 'sandiego' references: "$sandiego"."
-named "CarmenSanDiego"
-echo "$0: (5.) After dereferencing, the image list still has an image named 'CarmenSanDiego' at index (not count!): "${}"."
# Can a child scope store CarmenSanDiego on our behalf?
-echo "\nCustom command 'hideme' stores CarmenSanDiego on our behalf in its own local storage variable named 'carmen'."
-hideme[CarmenSanDiego]
-named "CarmenSanDiego"
-echo "$0: (6.) Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: (6.) Image list length, following CarmenSanDiego stored in a child custom command (hideme): "$!"."
# Try to restore CarmenSanDiego from child-declared storage location 'carmen'…
-echo "\nTrying to restore CarmenSanDiego from the child-declared storage location 'carmen'…\nExpect an exception to be thrown."
-local
-input $carmen
-onfail
-echo "$0: (6 local.) Cannot re-input that which was stored in a child scope."
-done
-if !$!
-echo "$0: (6 Empty Image List.) The CarmenSanDiego image seems to have escaped!\nMight anything be found in a mathematical expression environment?"
-eval ">
V=get('carmen',"$carmensz");
print(V)
"
-echo "$0: Making a new one…"
-input 1
-name. CarmenSanDiego
-fi
# Where is Carmen SanDiego now?
-echo "\nPossibly through restoration or other means, maybe CarmenSanDiego is on the image list."
-named "CarmenSanDiego"
-echo "$0: Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: Image list length: "$!"."
# Use global store
-echo "\nPutting CarmenSanDiego in global storage '_sandiego'."
-store[CarmenSanDiego] _sandiego
-named "CarmenSanDiego"
-echo "$0: (7.) Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: (7.) Image list length, following attempting to store CarmenSanDiego in global storage: "$!"."
# Can a custom command restore CarmenSanDiego to the parent context from global storage? (Expect it to succeed).
-echo "\nCan the custom command, 'showglobalcarmen', restore CarmenSanDiego using global storage '_sandiego' (Expect it to succeed)?"
-showglobalcarmen
-named "CarmenSanDiego"
-echo "$0: (8.) Indices (not counts!) of images in CarmenSanDiego collection: "${}
-echo "$0: (8.) Image list length, following showglobalcarmen fetch from global storage '_sandiego': "$!".\n"
# -----------------------------------------------------------------------------------------
hideme:
nm={n}
-echo "$0: Storing some selected image named: "$nm" in a local storage variable named 'carmen'"
-store. carmen
-echo "$0: Image "$nm" is gone. Image list length in "$0": "$!"."
-echo "Restoring "$nm":"
-input $carmen
-echo "$0: (6.) Indices (not counts!) of images in CarmenSanDiego collection: "${}"."
-echo "$0: (6.) Image list length, following attempt to restore "$nm" from local storage 'carmen': "$!"."
-echo "$0: (6.) Storing "$nm" again to 'carmen', removing it from image list."
-store. carmen
# -----------------------------------------------------------------------------------------
showcarmen:
-local
-echo "$0: Attempting to fetch an image from a local storage variable named sandiego\n(as it was declared in the parent scope)."
-input $sandiego
-onfail
echo "$0: Cannot retrieve that which was stored in a parent scope."
-done
# -----------------------------------------------------------------------------------------
showglobalcarmen:
-local
-echo "$0: Attempting to fetch an image from global storage named _sandiego\n(as it was declared in the parent scope)."
-input $_sandiego
-echo "$0: Global variable key '_sandiego' references: "$_sandiego
-onfail
echo "$0: Cannot retrieve that what was stored globally in a parent scope."
-done
Shell log:
gosgood@bertha ~/gmicscripts $ gmic -m witwicsd.gmic v 3 whereintheworldiscarmensandiego v -3
[gmic]./ Start G'MIC interpreter (v.3.3.6).
[gmic]./ Import commands from file 'witwicsd.gmic', with debug info (4 new, total: 4789).
[gmic]./ Set verbosity level to 3.
[gmic]./whereintheworldiscarmensandiego/ Input black image at position 0 (1 image 1x1x1x1).
[gmic]./whereintheworldiscarmensandiego/ Set name of image [0] to 'CarmenSanDiego'.
[gmic]./whereintheworldiscarmensandiego/ Set local variable 'carmensz:=whds'->'1'.
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [0] (case-sensitive).
CarmenSanDiego has one pixel…
whereintheworldiscarmensandiego: (1.) Indices (not counts!) of images in CarmenSanDiego collection: 0.
whereintheworldiscarmensandiego: (1.) Image list length, pre-CarmenSanDiego storage: 1.
Storing CarmenSanDiego in a local storage variable named 'sandiego'.
[gmic]./whereintheworldiscarmensandiego/ Store image [0] as variable 'sandiego'
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [] (case-sensitive).
whereintheworldiscarmensandiego: (2.) Indices (not counts!) of images in CarmenSanDiego collection: .
whereintheworldiscarmensandiego: (2.) Image list length following-CarmenSanDiego storage: 0.
(2 Looking in math.) Something like CarmenSanDiego in a mathematical expression environment?
[gmic]./whereintheworldiscarmensandiego/ Evaluate expression '> V=get('sandiego',1); print(V) ' and assign it to status.
[gmic_math_parser] V = (uninitialized) (mem[44]: vector1)
[gmic_math_parser] V = [ 0 ] (size: 1)
Custom command 'showcarmen' attempts to fetch CarmenSanDiego via 'sandiego' (It should throw an exception).
showcarmen: Attempting to fetch an image from a local storage variable named sandiego
(as it was declared in the parent scope).
[gmic]./whereintheworldiscarmensandiego/showcarmen/ local#112/ Input file '' at position 0
[gmic]./whereintheworldiscarmensandiego/showcarmen/ local#112/ *** Error (file 'witwicsd.gmic', line #114) *** Command 'input': Unknown filename ''.
showcarmen: Cannot retrieve that which was stored in a parent scope.
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [] (case-sensitive).
whereintheworldiscarmensandiego: (3.) Indices (not counts!) of images in CarmenSanDiego collection: .
whereintheworldiscarmensandiego: (3.) Image list length, following showcarmen fetch: 0.
Retrieving CarmenSanDiego from the local storage variable named 'sandiego'
Expect collection affiliations to be restored as well.
[gmic]./whereintheworldiscarmensandiego/ Input image from variable 'sandiego', at position 0 (1 image 1x1x1x1).
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [0] (case-sensitive).
whereintheworldiscarmensandiego: (4.) Indices (not counts!) of images in CarmenSanDiego collection: 0.
whereintheworldiscarmensandiego: (4.) Image list length, following sandiego fetch in same scope: 1.
whereintheworldiscarmensandiego: (4.) The command interpreter local variable key 'sandiego' references: *store/sandiego.
Delete key sandiego. Referenced value now gone? Collection 'CarmenSanDiego' gone too?
whereintheworldiscarmensandiego: (5.) Dereferencing key 'sandiego'.
[gmic]./whereintheworldiscarmensandiego/ Set local variable 'sandiego='.
whereintheworldiscarmensandiego: After dereferencing 'sandiego', can a mathematical expression environment still fetch 'sandiego' as a vector?
[gmic]./whereintheworldiscarmensandiego/ Evaluate expression '> V=get('sandiego',1); print(V) ' and assign it to status.
[gmic_math_parser] V = (uninitialized) (mem[44]: vector1)
[gmic_math_parser] V = [ 0 ] (size: 1)
whereintheworldiscarmensandiego: (5.) After dereferencing, the command interpreter local variable key 'sandiego' references: .
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [0] (case-sensitive).
whereintheworldiscarmensandiego: (5.) After dereferencing, the image list still has an image named 'CarmenSanDiego' at index (not count!): 0.
Custom command 'hideme' stores CarmenSanDiego on our behalf in its own local storage variable named 'carmen'.
[gmic]./whereintheworldiscarmensandiego/hideme/ Set local variable 'nm=CarmenSanDiego'.
hideme: Storing some selected image named: CarmenSanDiego in a local storage variable named 'carmen'
[gmic]./whereintheworldiscarmensandiego/hideme/ Store image [0] as variable 'carmen'
hideme: Image CarmenSanDiego is gone. Image list length in hideme: 0.
Restoring CarmenSanDiego:
[gmic]./whereintheworldiscarmensandiego/hideme/ Input image from variable 'carmen', at position 0 (1 image 1x1x1x1).
hideme: (6.) Indices (not counts!) of images in CarmenSanDiego collection: 0.
hideme: (6.) Image list length, following attempt to restore CarmenSanDiego from local storage 'carmen': 1.
hideme: (6.) Storing CarmenSanDiego again to 'carmen', removing it from image list.
[gmic]./whereintheworldiscarmensandiego/hideme/ Store image [0] as variable 'carmen'
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [] (case-sensitive).
whereintheworldiscarmensandiego: (6.) Indices (not counts!) of images in CarmenSanDiego collection: .
whereintheworldiscarmensandiego: (6.) Image list length, following CarmenSanDiego stored in a child custom command (hideme): 0.
Trying to restore CarmenSanDiego from the child-declared storage location 'carmen'…
Expect an exception to be thrown.
[gmic]./whereintheworldiscarmensandiego/ local#61/ Start 'local...done' block, with image [].
[gmic]./whereintheworldiscarmensandiego/ local#61/ Input file '' at position 0
[gmic]./whereintheworldiscarmensandiego/ local#61/ *** Error (file 'witwicsd.gmic', line #62) *** Command 'input': Unknown filename ''.
[gmic]./whereintheworldiscarmensandiego/ local#61/ Reach 'onfail' block.
whereintheworldiscarmensandiego: (6 local.) Cannot re-input that which was stored in a child scope.
[gmic]./whereintheworldiscarmensandiego/ local#61/ End 'local...done' block.
[gmic]./whereintheworldiscarmensandiego/ if#63/ Start 'if...endif' block -> condition '!0' holds.
whereintheworldiscarmensandiego: (6 Empty Image List.) The CarmenSanDiego image seems to have escaped!
Might anything be found in a mathematical expression environment?
[gmic]./whereintheworldiscarmensandiego/ if#63/ Evaluate expression '> V=get('carmen',1); print(V) ' and assign it to status.
[gmic_math_parser] V = (uninitialized) (mem[42]: vector1)
[gmic_math_parser] V = [ nan ] (size: 1)
whereintheworldiscarmensandiego: Making a new one…
[gmic]./whereintheworldiscarmensandiego/ if#63/ Input black image at position 0 (1 image 1x1x1x1).
[gmic]./whereintheworldiscarmensandiego/ if#63/ Set name of image [0] to 'CarmenSanDiego'.
[gmic]./whereintheworldiscarmensandiego/ if#63/ End 'if...endif' block.
Possibly through restoration or other means, maybe CarmenSanDiego is on the image list.
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [0] (case-sensitive).
whereintheworldiscarmensandiego: Indices (not counts!) of images in CarmenSanDiego collection: 0.
whereintheworldiscarmensandiego: Image list length: 1.
Putting CarmenSanDiego in global storage '_sandiego'.
[gmic]./whereintheworldiscarmensandiego/ Store image [0] as variable '_sandiego'
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [] (case-sensitive).
whereintheworldiscarmensandiego: (7.) Indices (not counts!) of images in CarmenSanDiego collection: .
whereintheworldiscarmensandiego: (7.) Image list length, following attempting to store CarmenSanDiego in global storage: 0.
Can the custom command, 'showglobalcarmen', restore CarmenSanDiego using global storage '_sandiego' (Expect it to succeed)?
showglobalcarmen: Attempting to fetch an image from global storage named _sandiego
(as it was declared in the parent scope).
[gmic]./whereintheworldiscarmensandiego/showglobalcarmen/ local#121/ Input image from variable '_sandiego', at position 0 (1 image 1x1x1x1).
showglobalcarmen: Global variable key '_sandiego' references: *store/_sandiego
[gmic]./whereintheworldiscarmensandiego/ Get all image indices with name 'CarmenSanDiego' for image [0] (case-sensitive).
whereintheworldiscarmensandiego: (8.) Indices (not counts!) of images in CarmenSanDiego collection: 0
whereintheworldiscarmensandiego: (8.) Image list length, following showglobalcarmen fetch from global storage '_sandiego': 1.