16.8.3 The GPS Shell

The GPS shell is a very simple-minded, line-oriented language. It is accessible through the Shell window at the bottom of the GPS window. It is similar to a Unix shell, or a command window on Windows systems.

Type help at the prompt to get the list of available commands, or help followed by the name of a command to get more information on that specific command.

The following example shows how to get some information on a source entity, and find all references to this entity in the application. It searches for the entity "entity_name", which has at least one reference anywhere in the file "file_name.adb". After the first command, GPS returns an identifier for this entity, which can be used for all commands that need an entity as a parameter, as is the case for the second command. When run, the second command will automatically display all matching references in the location window.

     GPS> Entity my_entity file_name.adb
     <Entity_0x09055790>
     GPS> Entity.find_all_refs <Entity_0x09055790>

Since the GPS shell is very simple, it doesn't provide any reference counting for the result types. As a result, all the values returned by a command, such as <Entity_0x09055790> in the example above, are kept in memory.

The GPS shell provides the command clear_cache which removes all such values from the memory. After this command is run, you can no longer use references obtained from previous commands, although of course you can run these commands again to get a new reference.

The return value of the 9 previous commands can easily be recalled by passing %1, %2, ... on the command line. For instance, the previous example could be rewritten as

     GPS> Entity my_entity file_name.adb
     <Entity_0x09055790>
     GPS> Entity.find_all_refs %1

These return values will be modified also for internal commands sent by GPS, so you should really only use this when you emit multiple commands at the same time, and don't do any other action in GPS. This is mostly useful when used for command-line scripts (see --eval and --load), or for custom files, See Customizing through XML and Python files.

Arguments to commands can, but need not, be quoted. If they don't contain any space, double-quote ('"') or newline characters, you do not need to quote them. Otherwise, you should surround them with double-quotes, and protect any double-quote part of the argument by preceding it with a backslash.

There is another way to quote a command: use three double-quotes characters in a row. Any character loses its special meaning until the next three double-quotes characters set. This is useful if you do not know in advance the contents of the string you are quoting.

     Locations.parse """%1 """ category_name