Sign inRegisterCheck connection

Deprecating an Old Weather Display Parser

Why ClientRaw field maps drift across Weather Display builds, and how to retire an old parser without breaking bookmarks or hiding breaking changes.

Back to Weather Display software guides

A ClientRaw parser is a schema. It says that field 4 is wind direction, field 8 is outdoor humidity, and so on, for a stated Weather Display build. When the application adds a column, reorders a file, or starts emitting an extra daily file, every downstream script that still uses the old map is wrong in a quiet way: the page still renders, the numbers still look like weather, and the labels no longer match the bytes.

/wdparserold/index.php is the bookmark for an older parser surface on the historical TNET Weather site. The original interactive tool is not rehosted here. This page is not a second copy of the current ClientRaw parser article. It is the versioning problem that made an "old" parser exist at all: field maps drift, bookmarks outlive tools, and breaking changes need a public record.

Why field maps drift

Weather Display writes several space-delimited text files for web use. Vendor and community documentation treat clientraw.txt as the current packet, clientrawextra.txt as records (requiring a stated WD version or later), clientrawhour.txt as recent-hour samples, and clientrawdaily.txt as a longer recent-day file. Those files grew with the product. A parser written against an early clientraw.txt does not automatically understand later extra files, and a parser that assumes a fixed field count will attach the wrong name when a new value is inserted rather than appended.

The authoritative field list for a given install is the description file Weather Display ships, commonly discussed in the community as clientrawdescription.txt in the WD folder. Historical TNET notebooks also documented field positions for a stated build; the ClientRaw notebook is that snapshot style of record. A notebook dated to one build is evidence for that build. It is not a living schema.

Drift happens in four patterns, which are not equally dangerous.

Append-only additions. New fields appear at the end of the file. Old parsers that index by position and ignore a trailing remainder stay correct for the fields they already named. They simply omit the new variables.

Inserted or reassigned positions. A new variable lands in the middle, or a previously unused slot is reused. Every subsequent index shifts. This is a breaking change. Temperature may still look plausible if a neighboring numeric field slides into its slot.

Unit or encoding changes. The position is stable, but the file now emits hPa instead of inHg, or a calm wind as 0 instead of a blank. The parser's label is right; the conversion is wrong.

New files in the family. A site that only fetched clientraw.txt will not see hour or daily series until the parser grows a new map. That is an additive API if the old URL still returns the old object. It is a break if the old URL now concatenates files or changes column names.

Weather Display build numbers exist because the vendor changed behavior. Community parsers that advertise "updated to version 10.37L build 20 or higher" are stating a schema epoch. That sentence is the scientific claim. Without it, a field table is folklore.

What "old" means for a parser

An old parser is not merely an older PHP file. It is a map version: a tuple of (file family, field indices, units, WD build range, and output labels). Deprecation starts when that tuple is no longer the one you want newcomers to use, not when the script stops running.

Keep three objects distinct:

  • Schema version — the map (for example, "clientraw.txt positions as of WD 10.37L build 20").
  • Implementation — the program that applied the map.
  • Bookmark — the URL people stored, including /wdparserold/index.php.

You can retire an implementation without retiring the bookmark. You cannot silently replace the schema behind the bookmark and keep the same labels. Callers who deep-linked to "field 19" will not reread your blog post.

The current conceptual parser page at /wd-parser.php is the successor surface in this cluster. This old index exists so that a search result or a forum link from the 2000s still lands on an explanation instead of an empty stub. It must not impersonate the successor.

How to deprecate without breaking bookmarks

The operational pattern is ordinary API retirement, applied to a weather file map.

1. Freeze the old URL. Leave the path exactly as it was. Do not rename /wdparserold/index.php to match a cleaner slug. The bookmark is the asset.

2. State the schema epoch in the first screen. Name the WD builds the old map covered, and name the successor. "This parser described ClientRaw fields for Weather Display 10.x builds through …" is a complete sentence. "Parser (legacy)" is not.

3. Document breaking changes as a list, not as a rewrite. For each change, record: file name, field index or token, old meaning, new meaning, first WD version known to emit the new form, and whether old callers still parse. If you do not know the first version, say the change was observed, not that it shipped on a guessed date.

4. Do not serve the new map under the old names. If field 42 used to be X and is now Y, the old parser page should say that the old map is withdrawn, not quietly print Y as X. A successor page can print Y.

5. Keep a read-only field table for the frozen epoch. Researchers who archived clientraw.txt from 2009 still need the 2009 names. A deprecation page that only says "use the new parser" orphans those files.

6. Separate live fetch from documentation. A tool that pulls a remote clientraw.txt is an implementation. A table of field meanings is a schema. The old URL can become schema documentation even when the fetch tool is gone. That is the honest state of this page: the interactive fetch is not rehosted; the versioning lesson remains.

7. Do not log visitors as if that were part of the parse. Historical parser pages sometimes printed the caller's IP. That is unrelated to ClientRaw and is not restored here.

Breaking changes to write down

When you migrate a station site, the changelog that matters is small and specific.

  • Did clientrawextra.txt exist on the old build? If not, record parsers that assumed only one file.
  • Did clientrawhour.txt appear later? Hour sparklines depend on it; an old parser that ignored it is incomplete, not necessarily wrong.
  • Did any index in clientraw.txt move? If yes, treat every downstream dashboard as suspect until a fixture file from the old build is replayed.
  • Did unit defaults change in Weather Display's setup, so the same index now carries SI units? That is a configuration break, not a column shift.
  • Did HTML reports change even though ClientRaw did not? Pages that scraped tags or daily-report English will fail while a binary-position parser still works. That split is why web tags and ClientRaw need separate version notes.

A fixture is a saved clientraw.txt plus the WD version that wrote it plus the expected labeled output. Regression-test a new parser against old fixtures. If you cannot run the old PHP safely, you can still diff labeled columns by hand. Do not paste unsupported scripts onto a public page in order to "keep compatibility."

Observed files, not live weather

A parser output is observed only when it is a faithful labeling of a real file with a real observation time. A demo row that ships with documentation is historical or illustrative. A forecast string that happens to sit in an extra field is still a forecast. Schema documentation should say which.

The Weather Display category hub is the cluster index. TNET's public note on data sources, quality controls, and methodology is the modern counterpart to the same idea: name the source, name the freshness, and do not hide a schema change behind a familiar URL.

Checklist

  1. Identify the map version, not just the script name.
  2. Freeze old bookmarks; put the successor on its own path.
  3. Publish breaking changes as dated, field-level notes.
  4. Keep a frozen field table for archived files.
  5. Replay fixtures from old WD builds before trusting a new map.
  6. Label demo values as historical; label live files with observation time.
  7. Point operators to /wd-parser.php for the current conceptual parser, not to a resurrected old binary.

Sources