objectname  h m s  d m s  equinox 

All fields are normally separated by whitespace.  (A common mistake is to put spaces into the object's name.)   The position fields may optionally be separated by colons (h:m:s d:m:s).

If colons are not used to separate the fields, you can use decimal hours, degrees, or minutes in any RA or Dec entry. When coords sees a decimal point in one of these fields, it extracts the remaining fields from the fractional part. For example, the following lines are equivalent:

obj1a 

 12 34 56 
 1 2 3 
 2000.0 
obj1b 

 12.58222222 
 1 2 3 
 2000.0 

obj1c  

 12 34.9333333 
 1 2 3 
 2000.0 

obj1d 

 12 34 56 
 1.034166667 
 2000.0 

obj1e 

 12 34 56 
 1 2.05 
 2000.0 

The standard format may be expanded to include optional fields:

objectname  h m s  d m s  equinox [key=val ...] [comment]

Optional fields are interpreted as zero or more (keyword)=(value) fields. Anything following a keyword/value pair, other than another keyword/value pair, is interpreted as comment text. The currently defined keyword/values are:

N.B. Older versions of coords required a magnitude to follow the equinox. Though discouraged, this is still allowed for backward compatibility using the following format:

objectname  h m s  d m s  equinox [mag] [key=val ...] [comment]

The rule is: if the equinox field is followed by a number, that number is interpreted as a magnitude. Therefore, if a comment follows the equinox field, and if that comment begins with a number, the comment will be misinterpreted as a magnitude. Specifying magnitude with the the mag keyword is preferred.

For example, the comment directive: !Comment {^#} {Object.*RA}, contains the two patterns ^# and Object.*RA. It tells coords, respectively, that any line beginning with # or any line containing Object ... RA is a comment and should be ignored.

Notes:

1. If a pattern contains whitespace, $, or [, you must enclose the pattern in braces.
2. A blank line is always a comment. You can't change this, and you don't need to include blank lines in your comment patterns.
3. The default comment rule !Comment {^[ \t]*#} matches any line that begins with optional whitespace followed by #.

Bearing in mind that coords always requires object name, RA, Dec, and equinox for each entry, and that other data are optional, you can use the Data Directive to tell coords

• the order in which data appear on each line
• how to skip fields in the data that coords can't use
• to supply values for required fields that aren't in your tabular data (e.g. you can specify equinox=2000.0 for all lines).

The Data directive consists of !Data followed by a list, each of whose values is in turn a one- or two-element list of the form:

fieldname or {fieldname fieldformat}

The field names you can put in a !Data directive are:

For example, name and {dec_d %s} are valid list elements. The fieldformat is a scanf format that will read the field value into a variable. Generally, all elements should be treated as simple strings (even for numeric fields), and thus a fieldformat like %s is the preferred format.

When the fieldname is keyval then coords will match 0 or more key=value entries embedded in each data line, where the key-val fields are:

You can use decimal hours, degrees, or minutes in any RA or Dec entry. When coords sees a decimal point in one of these fields, it extracts the remaining fields from the fractional part. For example, the following lines are equivalent:

    
obj1a 

 12 34 56 
        
 1 2 3 
 2000.0 
    
obj1b 

 12.58222222 
        
 1 2 3 
 2000.0 

    
obj1c  

 12 34.9333333 
        
 1 2 3 
 2000.0 

    
obj1d 

 12 34 56 
        
 1.034166667 
 2000.0 

    
obj1e 

 12 34 56 
        
 1 2.05 
 2000.0 

Even if you are using decimal values in the data fields, you must still specify all three of the h,m,s or d,m,s fields in any !Data directive. Coords will recognize on its own whenever decimal data are present, and will then not expect to see minutes and/or seconds fields for that RA or Dec value.

If and only if coords is expecting to read an hours or degrees value from a field, and the field matches xx:mm:ss, then the minutes and seconds values are also read from the field.  (Note that both minutes and seconds are required: you cannot mix decimal minutes with a colon!)

Special Cases:

• !Data without any following arguments restores default line processing.
• The fieldname skip may appear any number of times, and it means that the corresponding data are ignored. This tells coords to skip over columns that aren't meaningful to coords.
• If the format is missing, %s is assumed.
• If the format is %n, where n is any integer (e.g. %10), coords reads a fixed-width field that is n characters wide. You can use this when your object names contain whitespace (see the examples below).
• The format * stands for "rest of the line", and is replaced by the scanf format %[^\n].
• If the fieldformat doesn't contain a % and isn't *, then it is a literal value for the field. This is useful to supply fixed-value fields that aren't present in the lines of data. For example, {equinox J2000.0} will set the equinox and reference frame.
• A fieldformat cannot be used with ra_hms, ra_dms or dec_dms. That is because ra_hms is internally handled by replacing it with {ra_h %[^:]} {ra_m :%[^:]} {ra_s :%s} Similar substitutions are done for ra_dms and dec_dms.  Note that this format explicitly requires a colon between fields.
• When matching dec_d, and the fieldformat isn't specified (or is simply %s), then the optional leading sign may be space-separated from the rest of the value, e.g. - 1 23 54. (Before the fieldformat is used, the sign is right-shifted to snuggle up against the next value.)

name ra_h ra_m ra_s dec_d dec_m dec_s equinox mag keyval {comment *}

{name %20} ra_hms dec_dms equinox mag keyval {comment *}

XXX92.412 00 55 16 +01 01 58  15.036  ...

name ra_h ra_m ra_s dec_d dec_m dec_s mag {equinox 2000.0} {comment *}

XX92.412 00:55:16 +01:01:58  yadda-yadda 15.036  ...

name ra_hms dec_dms {epoch 2000.0} {skip %11} mag {comment *}