auger-convert-time.cc

Go to the documentation of this file.

// C++
#include <cstring> // strrchr()
#include <iostream>
#include <iomanip>
#include <sstream>

// C
#include <unistd.h> // getopt

// Auger Offline
#include <utl/AugerUnits.h>
#include <utl/TimeStamp.h>
#include <utl/TimeInterval.h>
#include <utl/UTCDateTime.h>
#include <utl/MoonCycle.h>
#include <utl/LeapSeconds.h>
#include <utl/ModifiedJulianDate.h>
#include <utl/AugerException.h>
#include <utl/ErrorLogger.h>

// Terminal escape to underline text
#define ul(text) << "\033[4m" << #text << "\033[0m" <<

class Parser {
  public:
    // Possible input and output formats
    enum Format {
      eNone,
      eGPS,
      eUTC,
      eMoon,
      eUnix,
      eMJD
    };

    Parser() :
      fInputFormat(eNone),
      fOutputFormat(eNone),
      fLeapSeconds( utl::LeapSeconds::GetInstance() )
    {}

    void
    Dump()
      const
    {
      fLeapSeconds.Dump();
    }

    // Clear error states and seek back to start of stream so we can try reading it again
    void
    ResetStream(std::istringstream& stream)
      const
    {
      stream.clear();
      stream.seekg(0);
    }

    // Perform typical validation of the input stream
    bool
    ValidateStream(std::istringstream& stream, const std::string& description)
      const
    {
      // Check if the read failed
      if ( stream.fail() ) {
        ResetStream(stream);
        std::string what;
        stream >> what;
        ERROR("Could not parse " + description + " \"" + what + "\"");
        return false;
      }

      // Check for additional characters
      std::string what;
      stream >> what;
      if ( !what.empty() ) {
        ERROR("Unexpected characters in " + description + " \"" + what + "\"");
        return false;
      }

      return true;
    }

    /* Offline provides no mechanism to convert lunation to GPS second, however by studying the
      source code in MoonCycle.cc, we can infer the method to achieve this reverse
      conversion. However, Offline uses Unix time (via MJD) to calculate the moon cycle, so
      leap seconds are lost. This means that converting UTC to moon cycle and *back* to UTC will
      give a different answer by the number of leap seconds since 2004 */
    utl::TimeStamp
    MoonCycleToGPS(const double& lunation)
      const
    {
      /* Assume input is a full moon lunation in the Jan 2004 epoch and convert to a new moon
        lunation in the Jan 2000 epoch */
      const double altLunation(lunation + 0.5 + 49.0);

      // Calculate the interval of time between this lunation and the start of the Jan 2000 epoch
      // From MoonCycle.cc:15, which isn't in the .h so it isn't in the accessible utl namespace!
      const double kMeanSynodicMonth(29.530589);
      const utl::TimeInterval interval(altLunation*kMeanSynodicMonth*utl::day);

      /* The mean start of the Jan 2000 epoch, i.e., new moon lunation 0.0 in the Jan 2000 epoch.
        This date is given in the source code in MJD */
      const utl::UTCDateTime epoch(2000, 1, 6, 14, 20, 30);

      // Important: round off the nanosecond because we don't purport that much precision
      utl::TimeStamp result(epoch.GetTimeStamp() + interval);
      result.SetGPSTime(result.GetGPSSecond() + (result.GetGPSNanoSecond() > 500e6 ? 1 : 0), 0);
      return result;
    }

    void
    SetInputFormat(Format expected)
    {
      fInputFormat = expected;
    }

    void
    SetOutputFormat(Format expected)
    {
      fOutputFormat = expected;
    }

    bool
    ReadStrToTime(std::string& str)
    {
      std::istringstream inputStrm(str);

      if (fInputFormat == eMoon) {
        // Extract the input
        double moonCycle(-1.0);
        inputStrm >> moonCycle;

        if ( !ValidateStream(inputStrm, "moon cycle") )
          return false;

        fTime = MoonCycleToGPS(moonCycle);
      }
      else if (fInputFormat == eUnix) {
        time_t unixSec(0);
        inputStrm >> unixSec;

        if ( !ValidateStream(inputStrm, "Unix timestamp") )
          return false;

        // Let Offline handle the error checking
        try {
          unsigned long GPSsec(0);
          fLeapSeconds.ConvertUnixToGPS(unixSec, GPSsec);
          fTime.SetGPSTime(GPSsec);
        }
        catch (utl::OutOfBoundException&) {
          // Offline already prints the exception
          return false;
        }
      }

      // Try to parse as UTC
      if (fInputFormat == eNone || fInputFormat == eUTC) {
        // This parsing logic is adapted from UTCDate::Parse() in utl/UTCDate.cc
        int year(0);
        char dash1('?');
        int month(1);
        char dash2('?');
        int day(1);
        char tee('?');
        int hour(0);
        char colon1('?');
        int minute(0);
        char colon2('?');
        int second(0);
        std::string what;
        inputStrm >> year >> dash1 >> month >> dash2 >> day >> tee >> hour >> colon1 >> minute
          >> colon2 >> second >> what;

        if (!what.empty() && what != "Z") {
          // We let a 'Z' through because that's the UTC time zone specifier
          ERROR("Unexpected characters in UTC timestamp \"" + what + "\"");
          return false;
        }

        // If we don't know what we're expecting yet, decide
        if (fInputFormat == eNone) {
          if (dash1 != '-') {
            // Didn't start as UTC, so try the input as GPS second instead
            fInputFormat = eGPS;
            ResetStream(inputStrm);
          }
          else {
            // Try and proceed with interpreting as UTC
            fInputFormat = eUTC;
          }
        }

        // By this step, we could be checking any of the timestamps on stdin
        if (fInputFormat == eUTC) {
          if (dash1 == '?' || (dash1 == '-' && dash2 == '?')) {
            ResetStream(inputStrm);
            std::string what;
            inputStrm >> what;
            ERROR("UTC timestamp \"" + what + "\" not given to sufficient precision (at least"
              " to the day)");
            return false;
          }
          if (dash1 != '-' || dash2 != '-' || (tee != '?' && tee != 'T') || (colon1 != '?'
          && colon1 != ':') || (colon2 != '?' && colon2 != ':')) {
            ResetStream(inputStrm);
            std::string what;
            inputStrm >> what;
            ERROR("Could not parse UTC timestamp \"" + what + "\"");
            return false;
          }

          // Let Offline handle the error checking
          try {
            fTime = utl::UTCDateTime(year, month, day, hour, minute, second).GetTimeStamp();
          }
          catch (utl::OutOfBoundException& ex) {
            ERROR( ex.GetMessage() );
            return false;
          }
        }
      }

      // We've worked out the format by now
      if (fInputFormat == eGPS) {
        // Use a signed long because that's what utl::TimeStamp::SetNormalized() ultimately gets
        long GPSsec(0);
        inputStrm >> GPSsec;

        if ( !ValidateStream(inputStrm, "GPS second timestamp") )
          return false;

        // Let Offline handle the error checking
        try {
          fTime.SetGPSTime(GPSsec);
        }
        catch (utl::OutOfBoundException&) {
          // Offline already prints the exception
          return false;
        }
      }

      // At this stage, fTime is guaranteed to be set

      // Decide the output if needed
      if (fOutputFormat == eNone) {
        if (fInputFormat == eUTC)
          fOutputFormat = eGPS;
        else
          fOutputFormat = eUTC;
      }

      return true;
    }

    void
    PrintTime()
      const
    {
      // Produce the desired output
      switch (fOutputFormat) {
        case eGPS: {
          std::cout << fTime.GetGPSSecond() << std::endl;
          break;
        }
        case eUTC: {
          // The XML format is ISO 8601 UTC by Auger convention
          std::cout << utl::UTCDateTime(fTime).GetInXMLFormat() << std::endl;
          break;
        }
        case eMoon: {
          /* 7 decimal places gives us precision to the second, which is all we guarantee */
          std::cout << std::fixed << std::setprecision(7)
            << utl::MoonCycle(fTime).GetLunation() << std::endl;
          break;
        }
        case eUnix: {
          time_t unixSec;
          fLeapSeconds.ConvertGPSToUnix(fTime.GetGPSSecond(), unixSec);
          std::cout << unixSec << std::endl;
          break;
        }
        case eMJD: {
          // The standard for MJD seems to be 5 decimal places
          std::cout << std::fixed << std::setprecision(5)
            << utl::ModifiedJulianDate(fTime) << std::endl;
          break;
        }
        default:
          break;
      }
    }

  private:
    Format fInputFormat;
    Format fOutputFormat;
    utl::TimeStamp fTime;
    utl::LeapSeconds& fLeapSeconds;
};

int
help(char*& execPath, const int& exitCode)
{
  // Find the basename of the exec path
  char* execBase( strrchr(execPath, '/') );
  if (execBase == 0)
    execBase = execPath;
  else
    execBase += 1;

  // Keep printed lines to 80 chars or fewer
  std::cout << "Usage: " << execBase << " [" ul(OPTION) "]... [" ul(TIMESTAMP) "]\n"
    << "Unless the interpretation of " ul(TIMESTAMP) " is made explicit with an option, it is\n"
    << "assumed to be either a GPS second timestamp or a UTC timestamp in ISO 8601\n"
    << "format (eg, YYYY-MM-DDTHH:MM:SSZ) given to at least the day.\n"
    << "Unless the desired output format is chosen with an option, it will be GPS\n"
    << "second if the input was UTC, and UTC in all other cases.\n"
    << "\n"
    << "Options\n"
    << "-------\n"
    << "  -d   Dump the Offline leap second table and exit, ignoring " ul(TIMESTAMP) ".\n"
    << "  -M   Interpret " ul(TIMESTAMP) " as a full moon cycle in the January 2004 epoch (ie,\n"
    << "       full moon at 0.0, new moon at 0.5, and so on). Note that moon cycle skips\n"
    << "       leap seconds.\n"
    << "  -m   Print output as full moon cycle in the January 2004 epoch.\n"
    << "  -j   Print output as Modified Julian Date (days since 1858-11-17 UTC).\n"
    << "  -U   Interpret " ul(TIMESTAMP) " as a Unix timestamp (seconds since 1970-01-01 UTC).\n"
    << "       Note that Unix time skips leap seconds.\n"
    << "  -u   Print output as Unix timestamp.\n"
    << "\n"
    << "With no " ul(TIMESTAMP) " parameter, timestamps will be read from stdin. If multiple\n"
    << "times are provided via stdin, then they must all be of the same format (eg,\n"
    << "they must all be GPS second timestamps, or all UTC timestamps, etc).\n";
  return exitCode;
}

int
main(int argc, char* argv[])
{
  Parser parse;

  // Read options - documentation at `man 3 getopt`
  char opt;
  while ( (opt = getopt(argc, argv, ":dhMmjUu")) != -1 ) {
    switch (opt) {
      case 'd': parse.Dump(); return 0;
      case 'h': return help(argv[0], 0);
      case 'M': parse.SetInputFormat(Parser::eMoon); break;
      case 'm': parse.SetOutputFormat(Parser::eMoon); break;
      case 'j': parse.SetOutputFormat(Parser::eMJD); break;
      case 'U': parse.SetInputFormat(Parser::eUnix); break;
      case 'u': parse.SetOutputFormat(Parser::eUnix); break;
      case '?': ERROR(std::string("Unrecognised option -") + char(optopt)); return 2;
      case ':': ERROR(std::string("Expected an argument for option -") + char(optopt)); return 2;
    }
  }

  // Check if a parameter was given after the options
  bool readParam;
  if (optind == argc)
    readParam = false; // No parameters left, so read stdin
  else if (optind == argc - 1)
    readParam = true; // Exactly one parameter to use
  else {
    ERROR("Too many input parameters. To convert multiple timestamps you must "
      "pass them over stdin (ie, pipe them into this program)");
    return 2;
  }

  // Start the run loop
  bool hadErrors(false);
  for (std::string token; readParam || std::cin >> token; ) {
    // Not reading from stdin, so use remaining parameter as our token
    if (readParam)
      token = argv[argc - 1];

    if ( parse.ReadStrToTime(token) )
      parse.PrintTime();
    else {
      hadErrors = true;
      break;
    }

    // Stop if we are only reading the one parameter
    if (readParam)
      break;
  }

  if (hadErrors)
    return 1;
  else
    return 0;
}