UI Style Guide Shell - Revision history

Janne Peräaho: Corrected $VER string template

2023-07-18T13:39:43Z

Corrected $VER string template

← Older revision		Revision as of 13:39, 18 July 2023
Line 202:		Line 202:
	A text sequence that indicates the current version of your application should be embedded within your code. (It should also be put in your ARexx scripts and your configuration files.) The format of this text sequence is:		A text sequence that indicates the current version of your application should be embedded within your code. (It should also be put in your ARexx scripts and your configuration files.) The format of this text sequence is:

	$VER: <name> <version>.<revision> (<d>.<m>.<y>)		<pre>$VER: <name> <version>.<revision> (<dd>.<mm>.<yyyy>)</pre>

	<name> The name of your application		<nowiki><name></nowiki> The name of your application
	<version> Major version number		<nowiki><version></nowiki> Major version number
	<revision> Minor revision number		<nowiki><revision></nowiki> Minor revision number
	<d> Day created		<nowiki><dd></nowiki> Day created
	<m> Numeric month created		<nowiki><mm></nowiki> Numeric month created
	<y> Year created		<nowiki><yyyy></nowiki> Year created

	If you follow this template, the user can find out what version of your software he is using with the Shell command VERSION.		If you follow this template, the user can find out what version of your software he is using with the Shell command VERSION.

Alexandre Balaban: Categorized into User Interface Style Guide

2013-04-26T09:27:49Z

Categorized into User Interface Style Guide

← Older revision		Revision as of 09:27, 26 April 2013
Line 1:		Line 1:
			[[Category:User Interface Style Guide]]
	== The Shell ==		== The Shell ==

Steven Solie: /* The Shell */

2013-04-23T19:42:24Z

The Shell

← Older revision		Revision as of 19:42, 23 April 2013
Line 17:		Line 17:
	would list only those files ending with ".info".		would list only those files ending with ".info".

	[[File:SG8-1.png\|frame\|center\|~~Fig 8.1:~~ The Shell]]		[[File:SG8-1.png\|frame\|center\|The Shell]]

	In addition to being able to do things with finer control than Workbench, the Shell can also do some things that Workbench cannot do at all. For instance, from the Shell you can create a script - a pre-recorded set of commands that helps to automate repetitive tasks.		In addition to being able to do things with finer control than Workbench, the Shell can also do some things that Workbench cannot do at all. For instance, from the Shell you can create a script - a pre-recorded set of commands that helps to automate repetitive tasks.

Steven Solie at 19:41, 23 April 2013

2013-04-23T19:41:44Z

← Older revision		Revision as of 19:41, 23 April 2013
Line 146:		Line 146:

	Pattern matching is part of the appeal of the Shell. It would be difficult to use icons to perform an operation on 50 files at once - not to mention the problem of fitting all the icons on a 12-inch monitor. Some complex operations are just easier to do with a text interface.		Pattern matching is part of the appeal of the Shell. It would be difficult to use icons to perform an operation on 50 files at once - not to mention the problem of fitting all the icons on a 12-inch monitor. Some complex operations are just easier to do with a text interface.

⚫	~~'''~~Standard Available Tokens~~'''~~

	{\| class="wikitable"		{\| class="wikitable"
		⚫	\|+ Standard Available Tokens
	! Token		! Token
	! Description		! Description

Steven Solie: /* Built-in Parsing */

2013-04-23T19:40:47Z

Built-in Parsing

← Older revision		Revision as of 19:40, 23 April 2013
Line 46:		Line 46:

	The system also needs to parse these arguments. Parsing refers to the job of examining the arguments to find out what they mean so the appropriate operation can be performed.		The system also needs to parse these arguments. Parsing refers to the job of examining the arguments to find out what they mean so the appropriate operation can be performed.

	Prior to Release 2 of the Amiga operating system, each application designer had to manage his own parsing. This resulted in a variety of command styles and a more complicated Shell environment for the user. So the designers of Release 2 built a standard way of processing Shell arguments into the system.

	When your application is started from the Shell, any arguments should be parsed using the command template method - the same method used to parse all the system-supplied Shell commands. This argument parsing method should also be used by your ARexx or scripting commands.		When your application is started from the Shell, any arguments should be parsed using the command template method - the same method used to parse all the system-supplied Shell commands. This argument parsing method should also be used by your ARexx or scripting commands.
Line 53:		Line 51:
	By far, the greatest benefit of this method is that it allows you to use AmigaDOS routines to handle the chore of parsing the command line. The DOS routines will handle errors and give help messages so both your code and your development time can be shorter. Using standard argument parsing also makes the Shell interface more consistent and more comfortable for the user.		By far, the greatest benefit of this method is that it allows you to use AmigaDOS routines to handle the chore of parsing the command line. The DOS routines will handle errors and give help messages so both your code and your development time can be shorter. Using standard argument parsing also makes the Shell interface more consistent and more comfortable for the user.

		⚫	{{Note\|text=Using AmigaDOS routines to handle command line parsing can shorten both your code and your development time.}}
	{\| class="wikitable"
⚫	\| Using AmigaDOS routines to handle command line parsing can shorten both your code and your development time.
	\|}

	=== The Command Template ===		=== The Command Template ===

Steven Solie at 20:13, 1 September 2012

2012-09-01T20:13:37Z

← Older revision		Revision as of 20:13, 1 September 2012
Line 1:		Line 1:
			== The Shell ==

	One of the best things about the Amiga is its versatility. While the rest of the personal computing community continues to argue about the best type of interface, Amiga users have both - a graphic interface with Workbench and a text-based interface with the Shell.		One of the best things about the Amiga is its versatility. While the rest of the personal computing community continues to argue about the best type of interface, Amiga users have both - a graphic interface with Workbench and a text-based interface with the Shell.

Steven Solie at 16:58, 30 August 2012

2012-08-30T16:58:48Z

← Older revision		Revision as of 16:58, 30 August 2012
Line 15:		Line 15:
	would list only those files ending with ".info".		would list only those files ending with ".info".

	Fig 8.1: The Shell		[[File:SG8-1.png\|frame\|center\|Fig 8.1: The Shell]]

	In addition to being able to do things with finer control than Workbench, the Shell can also do some things that Workbench cannot do at all. For instance, from the Shell you can create a script - a pre-recorded set of commands that helps to automate repetitive tasks.		In addition to being able to do things with finer control than Workbench, the Shell can also do some things that Workbench cannot do at all. For instance, from the Shell you can create a script - a pre-recorded set of commands that helps to automate repetitive tasks.

		⚫	{{Note\|text=Your application should support all three interfaces built into the Amiga: the GUI, the Shell and ARexx.}}
	{\| class="wikitable"
⚫	\| Your application should support all three interfaces built into the Amiga: the GUI, the Shell and ARexx.
	\|}

	== Parsing Commands ==		== Parsing Commands ==

Steven Solie at 18:15, 28 June 2012

2012-06-28T18:15:07Z

← Older revision		Revision as of 18:15, 28 June 2012
Line 73:		Line 73:
	\|-		\|-
	\| = - Equivalents		\| = - Equivalents
	\| The equal sign indicates equivalent abbreviations for keywords, eg. PS=PUBSCREEN/K.		\| The equal sign indicates equivalent abbreviations for keywords, e.g. PS=PUBSCREEN/K.
	\|-		\|-
	\| A - Always required		\| A - Always required
Line 90:		Line 90:
	This allows commands such as:		This allows commands such as:
	Join file1 file2 file3 as bigfile		Join file1 file2 file3 as bigfile
	When the /M modifier is the first argument in a template, any number of ~~filenames~~ may be specified by the user.		When the /M modifier is the first argument in a template, any number of file names may be specified by the user.

	If a command line has any leftover arguments, they will be interpreted as belonging to the /M argument. So only specify one /M per template. For example, in the command ''Join one two as bigfile three'', the word ''three'' is an extra argument. In this case, one, two and three will be merged together to form bigfile; the extra argument is tacked onto the /M arguments.		If a command line has any leftover arguments, they will be interpreted as belonging to the /M argument. So only specify one /M per template. For example, in the command ''Join one two as bigfile three'', the word ''three'' is an extra argument. In this case, one, two and three will be merged together to form bigfile; the extra argument is tacked onto the /M arguments.
Line 116:		Line 116:
	ANIM/A,LOOPS/K/N		ANIM/A,LOOPS/K/N

	This means the command has two arguments: the Anim argument and the Loops argument. The Anim argument consists of the optional keyword ''ANIM'' followed by an animation ~~filename~~. The /A modifier means this argument must always be given.		This means the command has two arguments: the Anim argument and the Loops argument. The Anim argument consists of the optional keyword ''ANIM'' followed by an animation file name. The /A modifier means this argument must always be given.

	In the Loops part of the argument, the /K means that the keyword ''LOOPS'' is required for the argument to be processed correctly, and the /N means that the ''LOOPS'' keyword should be followed by a decimal number. Notice that since the Loops argument does not have a /A modifier, it could be left out altogether.		In the Loops part of the argument, the /K means that the keyword ''LOOPS'' is required for the argument to be processed correctly, and the /N means that the ''LOOPS'' keyword should be followed by a decimal number. Notice that since the Loops argument does not have a /A modifier, it could be left out altogether.
Line 129:		Line 129:

	play myanimfile 20 (the required keyword LOOPS is missing)		play myanimfile 20 (the required keyword LOOPS is missing)
	play anim (no ~~filename~~ is given)		play anim (no file name is given)
	play anim myanimfile loops (the numeric value for LOOPS is missing)		play anim myanimfile loops (the numeric value for LOOPS is missing)

Steven Solie: Created page with "One of the best things about the Amiga is its versatility. While the rest of the personal computing community continues to argue about the best type of interface, Amiga users ..."

2012-06-28T17:32:15Z

Created page with "One of the best things about the Amiga is its versatility. While the rest of the personal computing community continues to argue about the best type of interface, Amiga users ..."

New page

One of the best things about the Amiga is its versatility. While the rest of the personal computing community continues to argue about the best type of interface, Amiga users have both - a graphic interface with Workbench and a text-based interface with the Shell.

The Shell (also known as the Command Line Interface or CLI) preserves the best features of operating computers the "old-fashioned way", that is, by typing commands at a console. Although that is in some ways more difficult than clicking on graphics with a mouse, it provides a finer level of control, less overhead and greater power than is possible through a GUI.

Virtually anything that can be done through Workbench can also be done through the Shell. On Workbench, for instance, a user can move into a subdirectory by double-clicking on its drawer icon. The equivalent of this in the Shell is to type

cd <subdirectory name>

The command ''dir'' will then list the contents of the directory.

The same example can be used to illustrate the greater power of the Shell. In addition to ''dir'', which gives a brief listing of files and subdirectories, the user can also use ''list'' which gives a more in-depth listing including the size of each file, information about the file and when it was last updated. Or you could list only a subset of files by using wildcards in the command. For example,

list #?.info

would list only those files ending with ".info".

Fig 8.1: The Shell

In addition to being able to do things with finer control than Workbench, the Shell can also do some things that Workbench cannot do at all. For instance, from the Shell you can create a script - a pre-recorded set of commands that helps to automate repetitive tasks.

{| class="wikitable"
| Your application should support all three interfaces built into the Amiga: the GUI, the Shell and ARexx.
|}

== Parsing Commands ==

You should use the command template method for parsing the command line:

=== Standard Form ===

In general, Shell commands take the form:

COMMAND [redirection-argument] [<argument1>,<argument2>, ...]

where COMMAND is the name of an executable file, [redirection-argument] is a "<", ">", and/or ">>" symbol followed by an AmigaDOS device name, and [<argument1>, <argument2>, ...] is a list of arguments that will be passed to the executable file.

Here's a sample Shell command:

play myanim loops 20

The command is ''play' (an executable program), there is no direction and three arguments are passed to the play program: ''myanim'' (the name of the data file), ''loops'' (a command option) and ''20'' (another command option).

=== Built-in Parsing ===

The Amiga, like UNIX and many other systems, passes command line arguments to your application. The system automatically provides the list of arguments and counts them for the application.

The system also needs to parse these arguments. Parsing refers to the job of examining the arguments to find out what they mean so the appropriate operation can be performed.

Prior to Release 2 of the Amiga operating system, each application designer had to manage his own parsing. This resulted in a variety of command styles and a more complicated Shell environment for the user. So the designers of Release 2 built a standard way of processing Shell arguments into the system.

When your application is started from the Shell, any arguments should be parsed using the command template method - the same method used to parse all the system-supplied Shell commands. This argument parsing method should also be used by your ARexx or scripting commands.

By far, the greatest benefit of this method is that it allows you to use AmigaDOS routines to handle the chore of parsing the command line. The DOS routines will handle errors and give help messages so both your code and your development time can be shorter. Using standard argument parsing also makes the Shell interface more consistent and more comfortable for the user.

{| class="wikitable"
| Using AmigaDOS routines to handle command line parsing can shorten both your code and your development time.
|}

=== The Command Template ===

In order for your application to use standard argument parsing, a command template must be constructed to describe the arguments that the command understands.

In the command template, each argument is specified by a keyword (a preset argument that the program understands) followed by a modifier that describes the properties of that argument. Modifiers take the form "/X" where X is one of the characters from the table below. Each keyword can have none or many of the modifiers.

Neither the keywords nor the modifiers are case-dependent. The format shown here corresponds to the way the system displays command templates in the Shell.

{| class="wikitable"
! Modifier
! Description
|-
| ,(comma) - No arguments
| The comma indicates a null argument. It also separates arguments in the command template.
|-
| = - Equivalents
| The equal sign indicates equivalent abbreviations for keywords, eg. PS=PUBSCREEN/K.
|-
| A - Always required
| The argument must be supplied in order for the command to be accepted.
|-
| F - Final argument
| If this is specified, the entire rest of the line is taken together as a single argument, even if other keywords appear in it.
|-
| K - Keyword required
| This means [that] the actual keyword must be typed on the command line along with its argument in order for the argument to be processed (often the keyword is optional). The argument will not be interpreted unless the keyword appears.
For example, if the template is NAME/K, then unless Name=<string> or Name <string> appears in the command line, the command will be interpreted as having no Name argument at all.
|-
| M - Multiple argument
| There can be a number of instances of this argument. For example, the AmigDOS Join command lets your merge together any number of files into a single file. The template is:
FILE/M,AS=TO/K/A
This allows commands such as:
Join file1 file2 file3 as bigfile
When the /M modifier is the first argument in a template, any number of filenames may be specified by the user.

If a command line has any leftover arguments, they will be interpreted as belonging to the /M argument. So only specify one /M per template. For example, in the command ''Join one two as bigfile three'', the word ''three'' is an extra argument. In this case, one, two and three will be merged together to form bigfile; the extra argument is tacked onto the /M arguments.

The /M argument also interacts with the /A argument. If there aren't enough arguments given to fill all the /As, then part of the previous /M argument will be used to fill in the /As.
|-
| N - Number
| This argument is a decimal number. If an invalid number is specified, an error message will be returned to the user. Unless the /N modifier is specified, all arguments are assumed to be strings.
|-
| S - Switch keyword
| This modifier indicates a switch keyword argument. If the keyword is given, the switch is "on". If the keyword isn't given, the switch is "off"
|-
| T - Toggle keyword
| This is similar to /S but, when specified, it causes the switch value to toggle from "on" to "off" or vice-versa.
|}

{| class="wiktiable"
| Use the standard command template described here in your Shell and ARexx commands.
|}

=== Displaying the Command Template ===

When a user types a command name in the Shell followed by a space and a question mark, the command template should be shown to him. This acts as a sort of help message that gives the syntax of the command. For instance, in the above example of ''play myanim loops 20' the command is ''play''. When the user types ''play ?'' in the Shell he should see this:

ANIM/A,LOOPS/K/N

This means the command has two arguments: the Anim argument and the Loops argument. The Anim argument consists of the optional keyword ''ANIM'' followed by an animation filename. The /A modifier means this argument must always be given.

In the Loops part of the argument, the /K means that the keyword ''LOOPS'' is required for the argument to be processed correctly, and the /N means that the ''LOOPS'' keyword should be followed by a decimal number. Notice that since the Loops argument does not have a /A modifier, it could be left out altogether.

Other possible commands a user could come up with include:

play myanimfile loops 20
play myanimfile
play anim myanimfile

These commands, however, would be illegal:

play myanimfile 20 (the required keyword LOOPS is missing)
play anim (no filename is given)
play anim myanimfile loops (the numeric value for LOOPS is missing)

== Standard Arguments ==

The following Shell arguments are standard within the system. Don't use these names for application-specific arguments with purposes different than those given below:

FILES/M List of files to work with as projects
PUBSCREEN/K Name of the public screen to open on
PORTNAME/K Name to assign to the ARexx port
STARTUP/K ARexx script to run at startup time
NOGUI/S Indicates that no GUI is desired
SETTINGS/K Name of preferences file to load at startup

If you need a keyword for your application, try to find an applicable one that is already in use - and use it the same way. If you need to make a new keyword, don't make it the same as a common command name; e.g. "list".

== Pattern Matching ==

When most people think of pattern matching, they think of using wilcards, but pattern matching is actually much more. It's a powerful feature that enables more efficient operations, especially on systems like the Amiga that have a hierarchical file system with few size limits.

Pattern matching is part of the appeal of the Shell. It would be difficult to use icons to perform an operation on 50 files at once - not to mention the problem of fitting all the icons on a 12-inch monitor. Some complex operations are just easier to do with a text interface.

'''Standard Available Tokens'''

{| class="wikitable"
! Token
! Description
|-
| ?
| Matches a single character. For instance ''a?'' matches any string with two characters that starts with the letter a.
|-
| #
| Matches a subsequent expression 0 or more times. For instance, the pattern #? will match any string.
|-
| (ab|cd)
| Matches any one of the items separated by |.
|-
| ~
| Negates the following expression. For instance the pattern ~x? will match any two letter string except those starting with x. Another corollary of this is the pattern ''~(x?)'' which will match anything except two-letter strings beginning with x; ie. xaa or ab but not xa.
|-
| [abc]
| Character class; matches any one of the characters in the brackets.
|-
| [a-z]
| Character range (must be within character classes). You can also use [a-e,x-z] style.
|-
| %
| Matches 0 characters always. For example, the pattern (foo|whiskey|%)bar matches foobar, whiskeybar and bar.
|-
| *
| Synonym for #?. Not available by default but it is an option that can be turned on.
|}

Expression in this table means either a single token or character token (such as ''?'' or ''x''), or an alternation (such as ''(ab|cd|ef)''), or a character class (such as ''[a-z,A-Z]'').

=== The Amiga's Wildcard ===

On the Amiga, the wilcard is #? - as opposed to * on other platforms. For example, the command

delete #?.info

would delete all the files in the current directory that end in .info.

=== Within Applications ===

In addition to its usefulness on the filing system, pattern matching is also useful within applications. For example, the Find function within a text editor should be able to find strings according to a pattern.

Your application should support pattern matching from the Shell and from functions within the application itself, through AmigaDOS system routines.

== Embedded Version IDs ==

Follow the standard method for indicating the version of your software.

The Shell command VERSION provides support for version identification, but you have to follow a standard template.

A text sequence that indicates the current version of your application should be embedded within your code. (It should also be put in your ARexx scripts and your configuration files.) The format of this text sequence is:

$VER: <name> <version>.<revision> (<d>.<m>.<y>)

<name> The name of your application
<version> Major version number
<revision> Minor revision number
<d> Day created
<m> Numeric month created
<y> Year created

If you follow this template, the user can find out what version of your software he is using with the Shell command VERSION.