;+
; NAME:
;	smei_star_list
; PURPOSE:
;	Reads content of star catalogues used for star subtraction in SMEI frames
; CATEGORY:
;	camera
; CALLING SEQUENCE:
	FUNCTION smei_star_list 	, $
		root		= root		, $
		silent		= silent	, $
		count		= count 	, $
		name		= name		, $
		catalogues	= catalogues, $
		get_format	= get_format
; OPTIONAL INPUT PARAMETERS:
;	root=root		scalar; type: string 
;						directory where star catalogue files are located.
;						By default, this is a subdirectory 'list' in the
;						directory where this file is located.
;	name=name		array; type: string
;						list of star names; only the data for the
;						specified stars are returned.
;	catalogues		scalar or array; type: string;
;						default: ['brightstars','variables_4th','big_variables','duhstars']
;						list of catalogues to be used. Must be one or more of
;						the entries on the defaults list (lowercase! and NO typos!).
;	/silent			suppresses informational messages
;
;	/get_format 	if set, return the format used for the bright star catalogue
; OUTPUTS:
;	star			array; type: SMEI_STAR_LIST structure
;					if 'name' NOT specified:
;						all stars in the selected catalogues
;					if 'name' specified:
;						array of length n_elements(name); if the name is present
;						in one of the catalogues the information is returned; if
;						the name is not present and empty SMEI_STAR_LIST
;						structure is returned
; OPTIONAL OUTPUT PARAMETERS:
;	count=count		scalar; type: integer
;					if 'name' NOT specified:
;						# stars in return array 'star'
;					if 'name' specified:
;						# stars in 'name' present in catalogues (for which
;						information is returned).
; INCLUDE:
	@compile_opt.pro		; On error, return to caller
; CALLS:
;	InitVar, IsType, txt_read, who_am_i, where_common, smei_star_info
; EXTERNAL:
;	smei_star_list__define
; RESTRICTIONS:
;	Small declinations (-1<lat<0) need special attention: the minus sign
;	needs to be put in front of the first non-zero component (i.e. minutes
;	or arcseconds)
; PROCEDURE:
; MODIFICATION HISTORY:
;	JAN-2003, Paul Hick (UCSD/CASS)
;	MAR-2003, Paul Hick (UCSD/CASS)
;		Rewrite to deal with single bright star catalogue
;	JAN-2004, Paul Hick (UCSD/CASS)
;		Added big_variables.txt and variables_4th.txt
;	NOV-2005, Paul Hick (UCSD/CASS)
;		Removed duplicate entries from list of stars (this should take
;		care of the overlap between 'brightstars' and 'big_variables'
;		catalogues.
;	MAR-2008, Paul Hick (UCSD/CASS)
;		Removed keyword 'pos'. Added 'duhstars' catalogue.
;	DEC-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added 'nova_list' catalogue.
;		Edited 'big_variables' catalogue to make format the same as
;		all other catalogues
;-
InitVar, root		, who_am_i(/dir)
InitVar, silent 	, 0
InitVar, get_format , /key

; Preread the star catalogue files to determine total number of stars
; The last record in each file appears to be a dummy record, so we skip it.

; brightstars.txt and variables_4th.txt have same format
;
;  #     Name         Typ Spec      RA            Dec     Mb    Mv    Msmei
;   1     HD 224855    sr* NIab:p     0  1 15.86   60 21 19 10.14 7.06 5.93
;
; big_variables.txt
;   1  V* SV And    Mi* M6.5e      0  4 20.07   40  6 35  0.00 7.70 5.66  6.6    316.21  M5e-M7e

all_catalogues = ['brightstars','variables_4th','big_variables','duhstars','stars_not_subtracted','nova_list']
all_frmts = '(I4,5X,A12,1X,A12,1X,2I3,F6.2,2X,I3,2I3,1X,3F5.2)'

InitVar, catalogues, all_catalogues[0:3]
IF n_elements(catalogues) EQ 1 THEN $
	IF catalogues EQ '*' THEN		$
		catalogues = all_catalogues

files = filepath(root=root, catalogues+'.txt')

IF get_format THEN	$
	RETURN, all_frmts

one_star = {smei_star_list}

count = 0

FOR i=0,n_elements(catalogues)-1 DO BEGIN

	; The catalogues should ONLY CONTAIN DATA,
	; i.e. no comments, no headers, no trailers.

	IF txt_read(files[i], cstar, nrec=nrec, silent=silent) THEN BEGIN	; Get # records

		; Read files into structure array and store
		; in output structure 'star'

		tmp = replicate( one_star, nrec )
		ifrmt = (where(all_catalogues EQ catalogues[i]))[0] > 0
		reads, cstar, tmp, format=all_frmts

		CASE count OF
		0   : star = tmp
		ELSE: star = [star,tmp]
		ENDCASE

		count += nrec

	ENDIF

ENDFOR


CASE count OF

0   : star = one_star

ELSE: BEGIN

	; Remove duplicate entries by removing duplicate names

	names = smei_star_info(star, /get_name)
	tmp   = uniq(names,sort(names))
	star  = star[tmp]
	count = n_elements(star)

	IF IsType(name, /defined) THEN BEGIN

		cat  = star
		star = replicate( one_star, n_elements(name) )

		; Extract requested names

		; tmp  : indices into array 'name' for stars present in catalogues
		; inref: indices in catalogue array 'cat'

		tmp = where_common( $
			strlowcase(strtrim(smei_star_alias(name)		))	, $
			strlowcase(strtrim(smei_star_info(cat,/get_name)))	, $
				count=count, inref=inref)

		IF count NE 0 THEN star[tmp] = cat[inref]

	ENDIF

END

ENDCASE

RETURN, star  &  END