A Full-Featured Open-Source Framework for Image Processing

check (+)

Curtis L. Brown Jr., STS-95 commander, checks over notes with Houston ground controllers. October 31, 1998           NASA

check throws exceptions if the given math expression argument resolves to False, otherwise it takes no action. It is the tool of choice for checking command arguments, taking math expressions that resolve to True with arguments that possess must-have features. If any calling scope encompasses a local … done block with an onfail section, the exception is caught and further processing resumes in the -onfail section. Otherwise -check uses its argument for the exception message and exits G'MIC. Since 2.6, -check no longer directly tests for file system objects; use math expressions isfile() or isdir() instead. Consider using error if a custom message is desired. Since -error unconditionally throws exceptions, combine it with conditional commands to emulate -check, but in (probably) a less compact way.

Examples

-check throws an exception immediately if its argument reduces to False; G'MIC does not operate on the remainder of a pipeline. Instead, it commences to exit all the scopes encompassing the offending pipeline. Should any of those scopes reside in an onfail section of a local … done block, then G'MIC resumes processing at that specific -onfail section — the exception being caught. Otherwise, upon the exit from all scopes, -check echoes its argument in the shell log and G'MIC quits. -check performs no operation if its argument is True.
Very frequently, -check constitutes the first line in custom command definitions, its argument a sanity-checking math expression. These test for properties among arguments upon which the custom command depends. In these examples, -check takes one argument, a string, which G'MIC processes as a math expression, substituting the results of the math expression for the string. -check interprets non-zero results as True, allowing G'MIC to proceed with the rest of the pipeline. Zero-results are interpreted as False; -check throws an exception, using its argument string as the exception message.
Combine skip with check to set custom command arguments to default values, but exclude such from -check processing. Effectively, this creates an optional argument that has a default value.
Wrapping -check within an onfail section of a local … done block may lead to a more adroit handling of thrown exceptions, not the least of which being posting purpose-specific error messages or saving of already-generated images from the effects of an inopportune exception. This approach is not peculiar to -check but to any circumstance where an exception is possible.

Command reference

Updated: 07-March-2023 13:47 UTC Commit: 220bd6b91cf3556158551b6ca6d8f6e242b72850