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
filenameName of the text (ASCII) file containing keyword(s) and associated value(s). The structure is similar to a f77-style NAMELIST.
keynameName 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
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.nclThis can be replaced with the following text file (here, 'CLA_SAMPLE.txt'):
year = 2015 data_file = test.nc p = 850, 500, 200 var = T, QOnly, the text file path is needed on the command line:
%> ncl 'key_path="./CLA_SAMPLE.txt"' foo.nclThe '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