Journal Namespace Reference

Facilities for recording and playback of sequences of user interaction. More...

Namespaces
namespace	anonymous_namespace{Journal.cpp}
namespace	anonymous_namespace{JournalOutput.cpp}
namespace	anonymous_namespace{JournalRegistry.cpp}
namespace	Events
namespace	WindowPaths

Classes
struct	RegisteredCommand
struct	RegisteredInitializer
class	SyncException

Typedefs
using	InteractiveAction = std::function< int() >
	Function that returns a value which will be written to the journal. More...
using	Dispatcher = std::function< bool(const wxArrayStringEx &fields) >
using	Dictionary = std::unordered_map< wxString, Journal::Dispatcher >
using	Initializer = std::function< bool() >
using	Initializers = std::vector< Initializer >

Functions
bool	RecordEnabled ()
bool	SetRecordEnabled (bool value)
bool	IsReplaying ()
void	SetInputFileName (const wxString &path)
bool	Begin (const FilePath &dataDir)
wxArrayStringEx	GetTokens ()
bool	Dispatch ()
void	Sync (const wxString &string)
void	Sync (const wxArrayString &strings)
void	Sync (std::initializer_list< const wxString > strings)
int	IfNotPlaying (const wxString &string, const InteractiveAction &action)
	Call action only if not replaying; synchronize on string and int values. More...
int	GetExitCode ()
bool	IsRecording ()
bool	OpenOut (const wxString &fullPath)
void	Output (const wxString &string)
void	Output (const wxArrayString &strings)
void	Output (std::initializer_list< const wxString > strings)
void	Comment (const wxString &string)
bool	GetError ()
void	SetError ()
const Dictionary &	GetDictionary ()
static std::vector< Initializer > &	sInitializers ()
const Initializers &	GetInitializers ()

Variables
constexpr auto	SeparatorCharacter = ','
constexpr auto	EscapeCharacter = '\\'
constexpr auto	CommentCharacter = '#'

Detailed Description

Facilities for recording and playback of sequences of user interaction.

Typedef Documentation

Dictionary

using Journal::Dictionary = typedef std::unordered_map< wxString, Journal::Dispatcher >

Definition at line 46 of file JournalRegistry.h.

Dispatcher

using Journal::Dispatcher = typedef std::function< bool(const wxArrayStringEx &fields) >

Definition at line 35 of file JournalRegistry.h.

Initializer

using Journal::Initializer = typedef std::function< bool() >

Definition at line 53 of file JournalRegistry.h.

Initializers

using Journal::Initializers = typedef std::vector< Initializer >

Definition at line 61 of file JournalRegistry.h.

InteractiveAction

using Journal::InteractiveAction = typedef std::function< int() >

Function that returns a value which will be written to the journal.

In future, might generalize to more return values and of other types

Definition at line 79 of file Journal.h.

Function Documentation

Begin()

WX_INIT_API bool Journal::Begin

(

const FilePath &

dataDir

)

Definition at line 226 of file Journal.cpp.

{
   if ( !GetError() && !sFileNameIn.empty() ) {
      wxFileName fName{ sFileNameIn };
      fName.MakeAbsolute( dataDir );
      const auto path = fName.GetFullPath();
      sFileIn.Open( path );
      if (!sFileIn.IsOpened())
      {
         Log("Journal: failed to open journal file \"{}\"", path);
         SetError();
      }
      else {
         sLine = sFileIn.GetFirstLine();
         sLineNumber = 0;
 
         auto tokens = PeekTokens();
         NextIn();
 
         if (!(tokens.size() == 2 && tokens[0] == VersionToken &&
               VersionCheck(tokens[1])))
         {
            Log("Journal: invalid journal version: \"{}\"", tokens[1]);
            SetError();
         }
      }
   }
 
   if ( !GetError() && RecordEnabled() ) {
      wxFileName fName{ dataDir, "journal", "txt" };
      const auto path = fName.GetFullPath();
      if ( !OpenOut( path ) )
         SetError();
      else {
         // Generate a header
         Comment( wxString::Format(
            wxT("Journal recorded by %s on %s")
               , wxGetUserName()
               , wxDateTime::Now().Format()
         ) );
         Output({ VersionToken, VersionString() });
      }
   }
 
   // Call other registered initialization steps
   for (auto &initializer : GetInitializers()) {
      if (initializer && !initializer()) {
         SetError();
         break;
      }
   }
 
   return !GetError();
}

References Comment(), GetError(), GetInitializers(), Journal::Events::anonymous_namespace{JournalEvents.cpp}::initializer, Journal::anonymous_namespace{Journal.cpp}::Log(), Journal::anonymous_namespace{Journal.cpp}::NextIn(), OpenOut(), Output(), Journal::anonymous_namespace{Journal.cpp}::PeekTokens(), RecordEnabled(), SetError(), Journal::anonymous_namespace{Journal.cpp}::sFileIn, Journal::anonymous_namespace{Journal.cpp}::sFileNameIn, Journal::anonymous_namespace{Journal.cpp}::sLine, Journal::anonymous_namespace{Journal.cpp}::sLineNumber, Journal::anonymous_namespace{Journal.cpp}::VersionCheck(), Journal::anonymous_namespace{Journal.cpp}::VersionString(), Journal::anonymous_namespace{Journal.cpp}::VersionToken, and wxT().

Referenced by AudacityApp::InitPart2(), anonymous_namespace{Registry.cpp}::CollectedItems::InsertNewItemUsingHint(), and anonymous_namespace{Registry.cpp}::CollectedItems::MergeItems().

Here is the call graph for this function:

Here is the caller graph for this function:

Comment()

WX_INIT_API void Journal::Comment

(

const wxString &

string

)

Definition at line 62 of file JournalOutput.cpp.

{
   if ( IsRecording() )
      sFileOut.AddLine( CommentCharacter + string );
}

References CommentCharacter, IsRecording(), and Journal::anonymous_namespace{JournalOutput.cpp}::sFileOut.

Referenced by Begin().

Here is the call graph for this function:

Here is the caller graph for this function:

Dispatch()

WX_INIT_API bool Journal::Dispatch

(

)

Definition at line 291 of file Journal.cpp.

{
   if ( GetError() )
      // Don't repeatedly indicate error
      // Do nothing
      return false;
 
   if ( !IsReplaying() )
      return false;
 
   // This will throw if no lines remain.  A proper journal should exit the
   // program before that happens.
   auto words = GetTokens();
 
   // Lookup dispatch function by the first field of the line
   auto &table = GetDictionary();
   auto &name = words[0];
   auto iter = table.find( name );
   if (iter == table.end())
      throw SyncException(
         wxString::Format("unknown command: %s", name.ToStdString().c_str()));
 
   // Pass all the fields including the command name to the function
   if (!iter->second(words))
      throw SyncException(wxString::Format(
         "command '%s' has failed", wxJoin(words, ',').ToStdString().c_str()));
 
   return true;
}

References GetDictionary(), GetError(), GetTokens(), IsReplaying(), and name.

Referenced by AudacityApp::OnIdle().

Here is the call graph for this function:

Here is the caller graph for this function:

GetDictionary()

const Dictionary & Journal::GetDictionary

(

)

Definition at line 53 of file JournalRegistry.cpp.

{
   return sDictionary();
}

References Journal::anonymous_namespace{JournalRegistry.cpp}::sDictionary().

Referenced by Dispatch().

Here is the call graph for this function:

Here is the caller graph for this function:

GetError()

WX_INIT_API bool Journal::GetError

(

)

Definition at line 30 of file JournalRegistry.cpp.

{
   return sError;
}

References Journal::anonymous_namespace{JournalRegistry.cpp}::sError.

Referenced by Begin(), Dispatch(), and GetExitCode().

Here is the caller graph for this function:

GetExitCode()

WX_INIT_API int Journal::GetExitCode

(

)

Definition at line 386 of file Journal.cpp.

{
   // Unconsumed commands remaining in the input file is also an error condition.
   if( !GetError() && !PeekTokens().empty() ) {
      NextIn();
      SetError();
   }
   if ( GetError() ) {
      // Return nonzero
      // Returning the (1-based) line number at which the script failed is a
      // simple way to communicate that information to the test driver script.
      return sLineNumber ? sLineNumber : -1;
   }
 
   // Return zero to mean all is well, the convention for command-line tools
   return 0;
}

References GetError(), Journal::anonymous_namespace{Journal.cpp}::NextIn(), Journal::anonymous_namespace{Journal.cpp}::PeekTokens(), SetError(), and Journal::anonymous_namespace{Journal.cpp}::sLineNumber.

Referenced by AudacityApp::OnRun().

Here is the call graph for this function:

Here is the caller graph for this function:

GetInitializers()

WX_INIT_API const Initializers & Journal::GetInitializers

(

)

Definition at line 69 of file JournalRegistry.cpp.

{
   return sInitializers();
}

References sInitializers().

Referenced by Begin().

Here is the call graph for this function:

Here is the caller graph for this function:

GetTokens()

WX_INIT_API wxArrayStringEx Journal::GetTokens

(

)

Definition at line 281 of file Journal.cpp.

{
   auto result = PeekTokens();
   if ( !result.empty() ) {
      NextIn();
      return result;
   }
   throw SyncException("unexpected end of stream");
}

References Journal::anonymous_namespace{Journal.cpp}::NextIn(), and Journal::anonymous_namespace{Journal.cpp}::PeekTokens().

Referenced by Dispatch(), IfNotPlaying(), and BasicMenu::anonymous_namespace{BasicMenu.cpp}::ReplayPopup().

Here is the call graph for this function:

Here is the caller graph for this function:

IfNotPlaying()

WX_INIT_API int Journal::IfNotPlaying	(	const wxString &	string,
		const InteractiveAction &	action
	)

Call action only if not replaying; synchronize on string and int values.

If not replaying, call the function, and if recording, output the string and the return value.

If replaying, skip the action; Sync on the string; parse a value from the journal; throw SyncException if the value is ill-formed; otherwise output the value (if also recording), and return it

Definition at line 352 of file Journal.cpp.

{
   // Special journal word
   Sync(string);
 
   // Then read or write the return value on another journal line
   if ( IsReplaying() ) {
      auto tokens = GetTokens();
      if ( tokens.size() == 1 ) {
         try {
            std::wstring str{ tokens[0].wc_str() };
            size_t length = 0;
            auto result = std::stoi(str, &length);
            if (length == str.length()) {
               if (IsRecording())
                  Journal::Output( std::to_wstring(result) );
               return result;
            }
         }
         catch ( const std::exception& ) {}
      }
 
      throw SyncException(wxString::Format(
         "unexpected tokens: %s", wxJoin(tokens, ',').ToStdString().c_str()));
   }
    else {
      auto result = action ? action() : 0;
      if ( IsRecording() )
         Output( std::to_wstring( result ) );
      return result;
   }
}

References GetTokens(), IsRecording(), IsReplaying(), Output(), str, and Sync().

Referenced by AudacityMessageBox().

Here is the call graph for this function:

Here is the caller graph for this function:

IsRecording()

WX_INIT_API bool Journal::IsRecording

(

)

Definition at line 28 of file JournalOutput.cpp.

{
  return sFileOut.IsOpened();
}

References Journal::anonymous_namespace{JournalOutput.cpp}::sFileOut.

Referenced by Comment(), IfNotPlaying(), Output(), and Sync().

Here is the caller graph for this function:

IsReplaying()

WX_INIT_API bool Journal::IsReplaying

(

)

Definition at line 216 of file Journal.cpp.

{
  return sFileIn.IsOpened();
}

References Journal::anonymous_namespace{Journal.cpp}::sFileIn.

Referenced by Dispatch(), IfNotPlaying(), Journal::anonymous_namespace{Journal.cpp}::PeekTokens(), BasicMenu::Handle::Popup(), and Sync().

Here is the caller graph for this function:

OpenOut()

WX_INIT_API bool Journal::OpenOut

(

const wxString &

fullPath

)

Definition at line 33 of file JournalOutput.cpp.

{
   sFileOut.Open( fullPath );
   if ( sFileOut.IsOpened() )
      sFileOut.Clear();
   else {
      sFileOut.Create();
      sFileOut.Open( fullPath );
   }
   return sFileOut.IsOpened();
}

References Journal::anonymous_namespace{JournalOutput.cpp}::sFileOut.

Referenced by Begin().

Here is the caller graph for this function:

Output() [1/3]

WX_INIT_API void Journal::Output

(

const wxArrayString &

strings

)

Definition at line 51 of file JournalOutput.cpp.

{
   if ( IsRecording() )
      Output( ::wxJoin( strings, SeparatorCharacter, EscapeCharacter ) );
}

References EscapeCharacter, IsRecording(), Output(), and SeparatorCharacter.

Here is the call graph for this function:

Output() [2/3]

WX_INIT_API void Journal::Output

(

const wxString &

string

)

Definition at line 45 of file JournalOutput.cpp.

{
   if ( IsRecording() )
      sFileOut.AddLine( string );
}

References IsRecording(), and Journal::anonymous_namespace{JournalOutput.cpp}::sFileOut.

Referenced by Begin(), MenuCreator::ExecuteCommand(), Journal::Events::anonymous_namespace{JournalEvents.cpp}::Watcher::FilterEvent(), BasicMenu::anonymous_namespace{BasicMenu.cpp}::Watcher::FilterEvent(), IfNotPlaying(), Output(), BasicMenu::Handle::Popup(), and Sync().

Here is the call graph for this function:

Here is the caller graph for this function:

Output() [3/3]

WX_INIT_API void Journal::Output

(

std::initializer_list< const wxString >

strings

)

Definition at line 57 of file JournalOutput.cpp.

{
   return Output( wxArrayStringEx( strings ) );
}

References Output().

Here is the call graph for this function:

RecordEnabled()

WX_INIT_API bool Journal::RecordEnabled

(

)

Definition at line 204 of file Journal.cpp.

{
   return JournalEnabled.Read();
}

References Journal::anonymous_namespace{Journal.cpp}::JournalEnabled, and Setting< T >::Read().

Referenced by Begin(), anonymous_namespace{PluginMenus.cpp}::OnWriteJournal(), and anonymous_namespace{PluginMenus.cpp}::ToolsMenu().

Here is the call graph for this function:

Here is the caller graph for this function:

SetError()

WX_INIT_API void Journal::SetError

(

)

Definition at line 35 of file JournalRegistry.cpp.

{
   sError = true;
}

References Journal::anonymous_namespace{JournalRegistry.cpp}::sError.

Referenced by Begin(), GetExitCode(), Journal::RegisteredCommand::RegisteredCommand(), and Journal::SyncException::SyncException().

Here is the caller graph for this function:

SetInputFileName()

WX_INIT_API void Journal::SetInputFileName

(

const wxString &

path

)

Definition at line 221 of file Journal.cpp.

{
   sFileNameIn = path;
}

References Journal::anonymous_namespace{Journal.cpp}::sFileNameIn.

Referenced by AudacityApp::InitPart2().

Here is the caller graph for this function:

SetRecordEnabled()

WX_INIT_API bool Journal::SetRecordEnabled

(

bool

value

)

Definition at line 209 of file Journal.cpp.

{
   auto result = JournalEnabled.Write(value);
   gPrefs->Flush();
   return result;
}

References audacity::BasicSettings::Flush(), gPrefs, Journal::anonymous_namespace{Journal.cpp}::JournalEnabled, and Setting< T >::Write().

Referenced by anonymous_namespace{PluginMenus.cpp}::OnWriteJournal().

Here is the call graph for this function:

Here is the caller graph for this function:

sInitializers()

static std::vector< Initializer > & Journal::sInitializers ( )

static

Definition at line 58 of file JournalRegistry.cpp.

{
   static std::vector<Initializer> sTheFunctions;
   return sTheFunctions;
}

Referenced by GetInitializers(), and Journal::RegisteredInitializer::RegisteredInitializer().

Here is the caller graph for this function:

Sync() [1/3]

WX_INIT_API void Journal::Sync

(

const wxArrayString &

strings

)

Definition at line 339 of file Journal.cpp.

{
   if ( IsRecording() || IsReplaying() ) {
      auto string = ::wxJoin( strings, SeparatorCharacter, EscapeCharacter );
      Sync( string );
   }
}

References EscapeCharacter, IsRecording(), IsReplaying(), SeparatorCharacter, and Sync().

Here is the call graph for this function:

Sync() [2/3]

WX_INIT_API void Journal::Sync

(

const wxString &

string

)

Definition at line 321 of file Journal.cpp.

{
   if ( IsRecording() || IsReplaying() ) {
      if ( IsRecording() )
         Output( string );
      if ( IsReplaying() ) {
         if (sFileIn.Eof() || sLine != string)
         {
            throw SyncException(wxString::Format(
               "sync failed. Expected '%s', got '%s'",
               string.ToStdString().c_str(), sLine.ToStdString().c_str()));
         }
 
         NextIn();
      }
   }
}

References IsRecording(), IsReplaying(), Journal::anonymous_namespace{Journal.cpp}::NextIn(), Output(), Journal::anonymous_namespace{Journal.cpp}::sFileIn, and Journal::anonymous_namespace{Journal.cpp}::sLine.

Referenced by IfNotPlaying(), Sync(), and audacity::cloud::audiocom::CloudSyncService::SyncCloudSnapshot().

Here is the call graph for this function:

Here is the caller graph for this function:

Sync() [3/3]

WX_INIT_API void Journal::Sync

(

std::initializer_list< const wxString >

strings

)

Definition at line 347 of file Journal.cpp.

{
   return Sync( wxArrayStringEx( strings ) );
}

References Sync().

Here is the call graph for this function:

Variable Documentation

CommentCharacter

constexpr auto Journal::CommentCharacter = '#'

constexpr

Definition at line 24 of file JournalOutput.h.

Referenced by Comment(), and Journal::anonymous_namespace{Journal.cpp}::PeekTokens().

EscapeCharacter

constexpr auto Journal::EscapeCharacter = '\\'

constexpr

Definition at line 23 of file JournalOutput.h.

Referenced by Journal::WindowPaths::FindByPath(), Journal::WindowPaths::FindPath(), Output(), Journal::anonymous_namespace{Journal.cpp}::PeekTokens(), and Sync().

SeparatorCharacter

constexpr auto Journal::SeparatorCharacter = ','

constexpr

Definition at line 22 of file JournalOutput.h.

Referenced by Output(), Journal::anonymous_namespace{Journal.cpp}::PeekTokens(), and Sync().