Notes on Syntax
Here are some notes on the somewhat exotic argument syntax of the //XL directives in CSV2XL.
| • | To insert a comment in the CSV file, start the line with //; (two slashes followed by a semicolon). This is consistent with the syntax for comments with normal GDI directives, e.g.: |
//; This is a comment
| • | Because there are so many potential parameters and most of them are optional, they have been assigned names. This allows you to specify only the ones you are interested in setting, and in any order. So for example, here we define a font by specifying the fontname and color, but not the size or any other attributes: |
//XL,DefineFont,fontid=myfont,fontname=Courier New,fontcolor=COLOR_BLUE
| • | Because some of the attribute values have symbolic names (e.g. COLOR_BLUE) which are more descriptive than the numeric values, you can use the symbolic names—as in the example above—or the corresponding numeric values (defined in libxl.def). |
| • | Because many of those attribute value symbolic names only apply to a single attribute type, e.g. NUMFMT_xxx only applies to the format parameter numfmtid, you can leave off the name= part of the name=value pair, e.g. |
//XL,DefineFormat,formatid=fmt_pct,NUMFMT_PERCENT,fontid=myfont
| is equivalent to |
//XL,DefineFormat,formatid=fmt_pct,numfmtid=NUMFMT_PERCENT,fontid=myfont
| • | In order to accommodate lengthy footnotes and banners, all parameters can be up to 512 characters long. |
| • | Parameters with Boolean attributes like bold, italic, etc., are all assumed FALSE (0) unless specified. Also, so there is no real need to say "wrap=1". Just say "wrap". |
| • | Fonts and formats both have internal identifiers or handles, which can be shared between cells. To be more precise, fonts may be shared by formats, and formats may be shared by columns or rows. Thus the DefineFont directive assigns the resulting font to the fontid specified in the fontid= clause, which may then be referenced in a subsequent DefineFormat statement (as in the above example). The DefineFormat directive assigns the resulting format handle to the formatid specified in the formatid= clause (fmt_pct in the above example), which can then be used to assign it to one or more columns, e.g. |
| • | The three part process described in the previous point—define a font, define a format using the font, then associate the format with columns—is logical but tedious and verbose in the simple case where you just want to apply some kind of formatting to a single column, or different formatting to different columns, where there is little or no opportunity to share formats or fonts. In that case, you can just do it all in the SetCol (or SetRow) directive, e.g.: |
//XL,SetCol,9,mask="###,###.00",fontcolor=COLOR_VIOLET,italic
| The above example creates a numeric format using the specified mask and assigns column 9 to use it and to also use violet colored italic text. Internally this generates DefineFont and DefineFormat directives, but the handles are lost, so you can't re-use them in subsequent directives. But there is nothing stopping you from specifying the same attributes in additional SetCol or SetRow directives. |
| • | Some directives have an obvious or natural first parameter whose name can therefore be omitted. For example, the obvious/natural first parameter to the Setrow directive is the row number. The obvious/natural first parameter to the DefineFont and DefineFormat directives are the fontid and formatid to be assigned. In the case of the SetIni directive, the only parameter is the ini file spec, so there is no point in even defining a name for that parameter. For example: |
//; following two are equivalent
//XL,DefineFont,fontid=hdrfont,name=Broadway
//XL,DefineFont,hdrfont,name=Broadway
//; following two are equivalent
//XL,SetCol,6,formatid=fmt_pct
//XL,SetCol,colfirst=6,formatid=fmt_pct
