The Shapes language compiler

Name

Synopsis

Command line options

Files

• source
  
  When the source is specified as the last command line argument, it may have either of the forms indir/basename, indir/basename., or indir/basename.shape (or indir/basename.blank for blank mode); they all mean the same (here indir/ just indicates that the file may be located in another directory). This also specifies a filename base (excluding indir/ and the .shape or .blank suffix), which in turn provides names for all other files involved.
• --outdir dir
  
  Specify directory for products. Defaults to current working directory. Not used in blank mode.
• --split=no/flat/dir
  
  Determines how to store the pages of the produced document catalog.
  When no: One file with many pages is created.
  When flat: One output file per page in the catalog is created. The file names are deduced from the output file name (see --out) which should not have any suffix, by adding the suffix -n.pdf, where n is the physical page number. All files that have names similar to the ones created will be deleted to avoid confusion!
  When dir: The output filename will denote a directory where each page in the catalog is stored as a separate file. The name of each file will be n.pdf where n is the physical page number. All files that have names similar to the ones created will be deleted to avoid confusion! It is an error if the output filename references an existing file.
  Defaults to no.
  Splitting and file naming based on page labels is not supported at the moment, but please make a request for implementation if you would need it.
• --tmpdir dir
  
  Specify directory for temporary files. See also --tmp*= and the environment variable SHAPESTMPDIR.
• --tmp*=bool
  
  Permission to create directory for temporary files if it does not exist. Defaults to no. See also --tmpdir.
• --needpath dir
  -Ndir
  
  Add dir to the end of the search path for language extension sources. See also the environment variable SHAPESINPUTS.
• --base filenamebase
  
  Specify the filename base to derive other filenames from.
• --in file
  
  Specify the input source. Defaults to the basename with the suffix .shape or .blank in the current directory. Higher priority is given to the suffix .shape.
• --prepend str
  
  Prepend the given string to the input source.
• --out file
  
  Specify the destination file. If the document is not split, this defaults to the basename with the suffix .pdf in the output directory. If the document is split, this defaults to only the basename, as the suffix must be deduced automatically. Not used in blank mode.
• --labeldb file
  
  Specify the file where to store labels between iterations. Defaults to the basename with the suffix .labels.pdf in the output directory. Used in both shape and blank mode.
  See also --iteration.
• --afmout file
  
  Specify the file where to store generated font metrics, would there be any. Defaults to the basename with the suffix .afm in the output directory.
• --fontmetricspath dir
  -Mdir
  
  Add dir to the end of the search path for font metrics.
• --resources=bool
  
  Control access to files installed with the Shapes program. This applies both to language extensions and font metric files. Defaults to true.
• --iteration=bool
  
  If true, a file with cached labels will be created in the output directory, to be reused if the file is compiled again. If false, no such file will be created, and no such file will be used. Defaults to true unless the label database filename is undefined.
  See also --labeldb.
• <stdin>
  
  The special file stdin is used when the input source is not determined in any other way. This means that the filename base must not be defined, so sometimes #shapes has to be used instead.
• <stdout>
  
  Since the user may write charater data on the special file stdout, stdout cannot be used for the produced pdf file. This should not be a major inconvenience since the pdf format is not suited for stream editing anyway. Consider using the --out option when the input is taken from stdin.
• --debuglog file
  --debuglog-stderr
  --debuglog-stdout
  
  Specify file for the user's debug log messages.
• --blank
  --shape
  
  Select blank or shape mode (do not select mode based on the input filename suffix).
  Blank mode is the default for input filenames with the .blank suffix, while shape mode is the default for input filenames with the .shape suffix. Shape mode has precedence over blank mode when the mode cannot be determined from input filename suffix (including when input is read from a stream).
  In blank mode, the program is not required to produce any graphics, and no result will be written to the output file or directory. Any input filename must have the .blank suffix.
  In shape mode, the program is required to produce graphics, which will be written to the output file or directory upon successful compilation. Any input filename must have the .shape suffix.

Tolerances and other parameters

• --seed=s
  
  Initializes the global random number generator by calling the srand function..
• --arcdelta=length
  
  Maximum integration step length to use when integrating along paths. See also dtmin.
  Default value: 0.1 bp
• --dtmin=low
  
  Minimum integration step to use when integrating along paths. See also arcdelta.
  Default value: 1e-4
• --dtminerror=bool
  
  Control whether bumping up too short steplengths in integration along paths shall be considered an error. See also --dtmin.
  Rationale: By default, it is considered an error if a length-measuring loop over one simple cubic spline requires too small steps. The number of steps required depends on the arc-delta setting. However, if changing arc-delta is not what one wants, and one cannot create the spline using more points, then a last resort is to inhibit the error using this option. Note, however, that evaluating a program this way may be a process that does not terminate, practically speaking.
• --disttol=length
  
  Tolerance for distance computations.
  Default value: 1e-3 bp
• --splicingtol=length
  
  Tolerance used when a 3^d scene is viewed in 2^d.
  Default value: 1e-5 bp
• --overlaptol=length
  
  Tolerance used when a 3^d scene is viewed in 2^d.
  Default value: 1e-3 bp
• --fmguesserror=bool
  
  Control whether guessing font metrics for (more or less) strange characters shall be considered an error.

Verbosity

• --bytecolumn=bool
  
  When true, report source file columns in bytes rather than complete utf-8 characters. Defaults to false.
• --unit=unit-name
  
  Set the unit to use for textual representation of lengths. Defaults to cm.
• --showfiles=bool
  
  Print the chain of used sources.
• --stats=bool
  
  Control printing of execution statistics, such as memory and time usage.
• --help
  
  Print a short help message and exit. Note that this command line option cannot be combined with other usages of the compiler.
• --i-format-prompt=format
  -?Pformat
  --i-format-show=format
  -?Sformat
  --i-format-file=format
  -?Fformat
  --i-format-eof=format
  -?Eformat
  
  Set format strings for the interaction in interactive mode. Each format string is used to format a sequence number of the user input.
  In the format string, the escape character \\ followed by any of [ant%\\] is used to produce some special characters (when followed by other characters, the escape character is not given special meaning). To format the sequence number a sequence starting with % and ending with [LR] is used. Here, the final letter indicates left or right flush. After the initial %, a prefix and a suffix string shall be specified. The first character after the initial % specifies a string delimiter, and should appear two more times, thereby delimiting the prefix and suffix, respectively. The final letter may be proceeded by a small, non-negative, number giving the width of the formatted number (including prefix and suffix).
  The prompt string refers to the string printed when asking for user input (default: “[%!#!!3R] ”). The show string refers to the string printed before a computed value is shown (default: “%!#!!3R ⇒ ”). The file string refers to the string printed before names of files written to (default: “#File: ”). The bye string refers to the string printed when reaching the end of the input stream, and the interactive mode is terminated (default: “<<EOF>>\n”).

Versions

• --pdf-version=mode-ver
  -vmode-ver
  
  Set the highest pdf version to use in output. The mode-ver parameter shall begin with either of the letters “e” (error), “w” (warning), or “s” (silent). The letter tells how the compiler shall react when it is not allowed to use a requested feature in the output, and must consider using a simpler replacement. After the letter, a pdf version, such as “1.3” shall follow. Hence, for instance, “w1.3” is a valid mode-ver value.
  Note that this setting affects the highest version to be used; Shapes will mark the produced file with the lowest version number providing the features used. Also note that the most common need for version 1.4 stems from the transparency groups used to merge a stroke with its arrowhead.
  By default, the pdf version is limited to 1.4, but this is likely to change in the future.
  See also --tp.
• --tp=bool
  
  Whether to allow the Kernel to use the transparent imaging model (requires pdf version 1.4). At the moment, this only affects whether to use a transparency group to merge an arrowhead with its stroke. In many cases, disallowing this will effektively reduce the pdf version of the output to 1.3 or below. However, the main reason for this option to exist is that the pdf viewer Adobe Reader prior to version 8 had a bug that caused a failure when printing. Defaults to true.
  See also --pdf-version.
• --spot-pair=bool
  
  Not really being a version-related option, this at least affects the compatibility with some PDF-interpreting applications. Determines whether the function should generate closed singleton paths (more efficient) or paths between a pair of points at the same location (more compatible). Defaults to false (that is, singleton).
• --version
  
  Print version information about the compiler, and exit. The version information consists of a version string, a corresponding date, and a list of activated build options. The meanings of the names identifying build options are explained in the installation instructions.

Preview

shapes --viewer 'open -a TeXShop %' myfile.shape

• --open
  
  Use the open program to open the result using a system default viewer for pdf files.
• --open-a program
  
  Like --open, but here the application to use is specified by the user.
• --xpdf
  
  Use the xpdf program to preview the result. The program is run in remote server mode.
  In interactive mode with --split=no, the behavior is changed to that of --xpdf-reload after the first invocation.
• --xpdf-remote name
  
  Set the name to use when running the xpdf program in remote mode. Defaults to the output filename.
• --xpdf-no-server
  
  Inhibit use of the remote server mode. A new xpdf window will appear each time.
• --xpdf-reload
  
  Make the xpdf server reload rather than raise.
• --xpdf-quit
  
  Make the xpdf server quit rather than show your graphics.

User level debugging

• --warn=action
  -Waction
  
  Specify action to take on warnings. Valid actions are “display” (alias “d”), “error” (alias “e”), and “ignore” (alias “i”). Defaults to “display”.
• --interactive
  -i
  
  Not primarily for debugging, but may be useful for learning the language, this make the compiler run in interactive mode.
  In this mode, the output directory defaults to the directory for temporary files, and the output name defaults to #shapes.pdf.
  The language semantics differs a bit from when the compiler operates in non-interactive mode. Please refer to the language documentation for details.
  Input is normally taken from stdin, and an external viewer is used to show drawable values, for instance:

    shapes -i --xpdf
  

  However, the mode is most useful in conjunction with a supporting editing environment that can provide fancy command line editing, input history, and inline display of graphics, &c.
  With --split=no, the same file is replaced each time a drawable result is produced. The other split modes will create separate files, numbered according to the input number (instead of the page number in the document catalog).
  To change the format of prompts , see the options starting with --i-format-.
• --backtrace=bool
  
  Whether to print a backtrace when the program reports a runtime error.
• --evaltrace
  
  Print information about each expression about to be evaluated.
• --evalbacktrace
  
  As --evaltrace, but with a backtrace printed along with each expression.

Compiler developer debugging

• --shapes-debug
  
  Turn on debug prints in the Shapes lexer.
• --yydebug
  
  Same as --shapes-debug.
• --system-debug
  
  Turn on system debug messages. The messages are written to stderr.
• --afm-debug
  
  Turn on debug prints in the font metrics scanner. Primarily for development use. See also --afmmessages.
• --afm-messages
  
  Turn on font metrics debug messages. The messages are written to stderr.
• --tex-debug
  
  Redirect the interaction output from pdfL^aT_eX to stderr instead of a file with suffix .stdout.
• --log-globals
  
  List content of the global environment (variable bindings, dynamic variables, and states) in the debug log file. Every item in this list should be explained in the documentation.
• --debugstep=step
  
  Set the debug step counter. For compiler development only.

Garbage collection

• --memclean=bool
  
  Attempt to clean up memory before terminating the compilation process? Defaults to true.
  Rationale: If the program seems to do stupid things after completing evaluation, it is possible that the cleaning-up process has caused a double free or access to freed memory. While waiting for a fix, the problem can be handled by specifying this option, and thereby omitting the clean-up process entirely.

File requests

• --which-in
  
  Request the input source.
• --which-out
  
  Request the name of the output file.
• --which-tmp
  
  Request the name of the directory for temporary files.
• --which-texjob
  
  Request the T_eX job basename.
• --which-labeldb
  
  Request the label database to keep generated labels between iterations.
• --which-afmout
  
  Request the file where generated font metrics will be stored.
• --which-TEXINPUTS
  
  Request the environment variable TEXINPUTS after any modifications made by Shapes.
• --which-doc
  
  Request the top index file of the locally installed html documentation.
• --which-share
  
  Request the directory where support files are installed.
• --which source
  
  Request a particular file.

Environment variables

• SHAPESINPUTS
  contains a search path used for requested source files. It usually consists of directories with language extension files (with the .shext suffix). On typical installations, the extension files shipped with the compiler are found using another mechanism.
• SHAPESTMPDIR
  tells, when present, where to create temporary files. In particular this concerns files related to label creation. Note, however, that the label database file (with the .labels.pdf suffix) is put in the output directory since it is not considered a temporary file. The environment variable is overridden by the --tmpdir command line option. When undefined, it defaults to the current directory.
• SHAPESFONTMETRICS
  tells where to search for font metrics files. Font metrics for the standard fonts in pdf are distributed with the compiler, and on typical installations these are found using another mechanism.
• TEXINPUTS
  is manipulated locally to enable T_eX to find files located relative to the Shapes source, although the L^aT_eX source used for label creation may be placed in a different directory.

Exit codes

• 0 — Success
  
  The program finished without errors.
• 1 — Generic error
  
  An error situation which has not been classified.
• 2 — User error
  
  The user caused the error by providing error in the input.
• 3 — pdfL^aT_eX error
  
  An error occurred when pdfL^aT_eX was typesetting labels.
• 4 — External error
  
  An error outside the compiler was detected.
• 5 — Invocation error
  
  The command line arguments were not properly specified.
• 6 — Tolerance error
  
  The program could not be compiled with the current tolerance settings. Sometimes, the solution to this is to run the program with other settings for the tolerances. Sometimes, this is an indication of ill-conditioned computations that must be resolved in source — like any other user error.
• 10 — Internal error
  
  There was an error in the compiler.
• 11 — Not implemented
  
  The actual implementation of some feature has not been written yet. For the user this is similar to an internal error, but for developers it is very different since no debugging is required.
• 20 — File error
  
  Generic error related to file I/O.
• 21 — Error opening file for input
  
  A file could not be opened for input.
• 22 — Error opening file for output
  
  A file could not be opened for output, or an attempt to create a directory failed. For instance, this could be because a file is locked by another process, or because of permissions.
• 23 — File permission error
  
  File permissions were insufficient.
• 24 — Missing directory
  
  A directory to be used did not exist, and was not created.
• 30 — User-detected error
  
  The error was detected and reported by the user.

Examples

Basic use

  shapes hi.shape

  shapes hi.

  shapes hi

Use with xpdf

  shapes --xpdf hi.shape

Use with stdin

echo '[TeX `$x^{2}$´]' | shapes --tmpdir /tmp --out label.pdf

The test suite

shapes --resources=no --needpath ../../resources/extensions/ --fontmetricspath ../../resources/fontmetrics/ \
       --tmpdir tmp/ --outdir out/ hello.shape

Author

See also