NCL Website header
NCL Home > Documentation > Functions > File I/O, String manipulation

keyword_values

Read a text file that contains keywords and one-or-more values (similar to fortran NAMELIST).

Available in version 6.5.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"  ; This library is automatically loaded
                                                             ; from NCL V6.2.0 onward.
                                                             ; No need for user to explicitly load.

	function keyword_values (
		filename [1] : string,  
		keyname  [1] : string,  
		keytype  [1] : string   
	)

	return_val [*] 

Arguments

filename

Name of the text (ASCII) file containing keyword(s) and associated value(s). The structure is similar to a f77-style NAMELIST.

keyname

Name of keyword. No spaces are allowed.

Return value

A variable containing one (a scalar, [1]) or more ([*]) value(s). Only one-dmensional return arrays are supported.

Description

The keyname===>value(s) method is a convenient method for variable input without altering the source code. The structure of the text (ascii) file is similar to a fortran NAMELIST. However, keyword_values does not have the capabilities of the Fortran NAMELIST. The user should examine the text file apriori to determine the appropriate return type and determine if the 'value' is within the scope of the function.

A simple fortran NAMELIST may be input. NCL's keyword_values does not recognize multiple NAMELIST groups. All NAMELIST group names are ignored. Effectively, the contents are treated as a flat text file.

A basic use case would be replacing multiple Command Line Assignment statements (CLAs) with a simple text file. Each line (row) has a keyword and one or more associated values. This usage is less tedious than CLAs because the user need not escape {u/li}nix command line shell syntax. This is particularly true when there are many CLAs.

The function's internal delimiters include TAB/space/double-quotes/single-quote/assignment (equal) symbol. The function ignores blank lines; keynames without associated values; assignment (=) syntax; end-of-line commas, etc.

   + A duplicate keyname will cause a fatal error message and the function will terminate.
   + The values can not not span multiple lines. 
   + Strings: 
     + A string value such as "foo_d<domain>_<date>" is returned as a literal string.
     + Generally, strings can not have any embedded spaces. There is one exception.
       A string enclosed within a <" and >" syntax pair will return a string with spaces. 

See Also

cla_sq

Examples

Consider the following simple keyword ===> value(s) file ("keyword_sample.txt"):


&time_control
 run_days                            = 5,
 run_hours                           = 0,
 run_minutes                         = 0,
 run_seconds                         = 0,
 start_year                          = 2015, 2001, 2001,
 start_month                         = 06,   06,   06,
 start_day                           = 19,   11,   11,
 start_hour                          = 00,   12,   12,
 start_minute                        = 00,   00,   00,
 start_second                        = 00,   00,   00,
 end_year                            = 2015, 2001, 2001,
 end_month                           = 06,   06,   06,
 end_day                             = 24,   12,   12,
 end_hour                            = 00,   12,   12,
 end_minute                          = 00,   00,   00,
 end_second                          = 00,   00,   00,
 interval_seconds                    = 600
 input_from_file                     = True,False, .true.,.false.,T, F,TRUE,  FALSE
 history_interval                    = 10,   60,   60,
 frames_per_outfile                  = 1,    1,    1,
 restart                             = .false.,
 restart_interval                    = 5000,
 io_form_history                     = 2
 io_form_restart                     = 2
 io_form_input                       = 2
 io_form_boundary                    = 2
 auxinput1                           = ../../WPS/wpsout_4km/met.d
 debug_level                         = 0
 HDF                                   3B-MO.MS.MRG.3IMERG.20141201.HDF5
 STRING_2                              "STRING_A" , "STRING_B"
 x                                   = 7.123
 y                                   = 1e5    
 z                                   = 1e5, 12.12, -7.37
 FOO
 INT_3                                 1, -9, 5
 INT_3A                                1, -9, 5,
 INT_3B                              = 1, -9, 5,
 FLOAT_0                               1, -9, 3.2                
 FLOAT_1                               1, -9, 3.2, 1e3                
 DBLE                                  12, 1e3, 8.2

 year        2015
 data_file   test.nc
 p           850, 500, 200
 var         T, Q

! CAVEATS and COMMENTS:   

! The following will be returned as a single string. 
! The 'domain' and 'date' are not filled-in.
  hist_out          = "wrfout/wrf_d<domain>_<date>"    

! The following will result in four (4) values ... not two (2). 
! In general, embedded spaces within strings are treated as delimiters..
  string_ab           "string a" , "string b"     

! The following will be returned as a single string with spaces via use of: "< ... >"
  meta_title  = "<title meta-data for netCDF file>"
  meta_source = "<data source meta-data for netCDF file>"

Example 1: Consider the above text file:

   diri    = "./"
   fili    = "keyword_sample.txt"
   pthi    =  diri+fili

   run_days = keyword_values( pthi, "run_days", "integer")        ; run_days=5
   fil_src  = keyword_values( pthi, "input_from_file", "logical") ; fil_src=(/ True,False,True,False \
                                                                             , True,False,True,False /)
   yearStrt = keyword_values( pthi, "start_year", "integer")      ; yearStrt=(/ 2015, 2001, 2001 /) 
   flt      = keyword_values( pthi, "FLOAT_1", "float")           ; flt=(/1,9, 3.2,1000 /) 
   fil_aux  = keyword_values( pthi, "auxinput1", "string")        ; fil_aux="../../WPS/wpsout_4km/met.d" 
   fil_hdf  = keyword_values( pthi, "HDF", "string") ; fil_hdf="3B-MO.MS.MRG.3IMERG.20141201.HDF5"

   hst_nam  = keyword_values( pthi, "hist_out", "string")         ; hst_nam="wrfout/wrf_d<domain>_<date>"
   title    = keyword_values( pthi, "meta_title", "string")       ; title="title meta-data for netCDF file"

Example 2: The keyword_values function provides an alternative to Command Line Assignments (CLAs). A major advantage is that it is not necessary to escape {u/li}nix shell sensitive characters. This can be a significant benefit when there are many CLAs. Consider the following simple command line:

 
   %> ncl year=2015 'data_file="test.nc"' 'p=(/850,500,200/)' 'var=(/"T","Q"/)' foo.ncl
This can be replaced with the following text file (here, 'CLA_SAMPLE.txt'):

   year      = 2015
   data_file = test.nc 
   p         = 850, 500, 200
   var       = T, Q
Only, the text file path is needed on the command line:
   
  %> ncl 'key_path="./CLA_SAMPLE.txt"' foo.ncl
The 'foo.ncl' script would contain:

   year      = keyword_values(key_path, "year", "integer")      ; year=2015
   data_file = keyword_values(key_path, "data_file", "string")  ; data_file="test.nc"
   pres      = keyword_values(key_path, "p", "integer")         ; pres=(/850, 500, 200/)
   var       = keyword_values(key_path, "var", "string")        ; var=(/"T", "Q"/)

Of course, in addition to the keyname==>text file, additional CLAs could be added to the command line.:
   
  %> ncl 'key_path="./CLA_SAMPLE.txt"' yearStop=2050 ... foo.ncl