module RubymentInternalModule

# begin_documentation This module offers function to interface with certain internal structures. Ie, these functions are supposed to be useless unless running Rubyment.

The module InternalRubymentModule should have been called RubymentInternalModule instead, to preserve the naming standards. RubymentInternalModule will receive the new functions, and InternalRubymentModule must be closed for extensions.

# end_documentation

Public Instance Methods

help__concept__rubyment_memory_persistence() click to toggle source

returns a string having help for the idea of persistence achieved with many of the functions of this module:

# File lib/rubyment.rb, line 921
def help__concept__rubyment_memory_persistence
  string = [
    "# saves the current memory to the default memory_json_file_default ('memory.rubyment.json' by default, in the current dir): ",
    "rubyment_memory__to_json_file",
    "",
    "# if you add a new key to that file, you can load it to memory with",
    "rubyment_memory__merge_shallow_on_load_json_file",
    "# in the above case, keys in the current memory will prevail, when they equal.",
    "",
    "# this function will try to restore the memory, as much as possible (not everything is serializable), to the state of when it was saved: ",
    "rubyment_memory__merge_shallow_with_json_file",
    "# in the above case, keys in the json file will prevail, when they equal.",
    "",
  ]
  [ string.join("\n") ]
end
invoke_pwd_persistent(*args) click to toggle source

By default, @memory (see rubyment_memory__ functions), is lost after a rubyment invocation.

This function allows a rudimentar method of persisting the memory (just that “on load” method is used, check help__concept__rubyment_memory_persistence ; here rubyment_memory__merge_shallow_on_load_json_file but it will be replaced by a deep version when that's available), based on the current PWD.

The invocation lines will be logged along with their results in memory.rubyment.json. Just try running rubyment multiple times and check that file.

Note: changed running dir, another context, another memory. If you return to the current dir you can retake the state. Either carry memory.rubyment.json around or symlink it, if really needed to run rubyment from another dir.

# File lib/rubyment.rb, line 976
def invoke_pwd_persistent *args
  rubyment_memory__merge_shallow_on_load_json_file
  result = invoke *args
  @memory[:invocation_history] ||=  Array.new
  time = time__now_strftime_default
  @memory[:invocation_history].push({
    "time" => time,
    "command" => args,
    "result" => result,
  })
  rubyment_memory__to_json_file
  result
end
rubyment_file_sha256(file=nil) click to toggle source

The actual release of rubyment it is not tied to the version returned by version (that's the execution version). This function returns a SHA256 hex digest (string) for this file, which is unique per file change set. However, it's not sequencial, and therefore not used for versioning.

# File lib/rubyment.rb, line 948
def rubyment_file_sha256 file=nil
  require 'openssl'
  file = containerize(file).first.nne __FILE__
  (Digest::SHA256.hexdigest File.read file)
end
rubyment_memory__merge_shallow(m) click to toggle source

merges the current @memory with m (so @memory will contain the resulting merged hash). The merge is shallow, ie, only top-level keys are merged. If the same key is present in both objects, the one in m will prevail.

# File lib/rubyment.rb, line 767
def rubyment_memory__merge_shallow m
  @memory.merge!  m
end
rubyment_memory__merge_shallow_on(m) click to toggle source

merges the m with the current @memory (so @memory will contain the resulting merged hash). The merge is shallow, ie, only top-level keys are merged. If the same key is present in both objects, the one in @memory will prevail. Note that this is the inverted behaviour as of rubyment_memory__merge_shallow

# File lib/rubyment.rb, line 783
def rubyment_memory__merge_shallow_on m
  rubyment_memory__set m.merge @memory
end
rubyment_memory__merge_shallow_on_load_json_file(filepath=nil, debug=nil) click to toggle source

merge @memory with the hash loaded from filepath, or @memory if not given (still @memory if nil).

The merge is shallow, ie, only top-level keys are merged. If the same key is present in both objects, the one in @memory will prevail. Note that this is the inverse behaviour compared to rubyment_memory__merge_shallow_with_json_file

# File lib/rubyment.rb, line 899
def rubyment_memory__merge_shallow_on_load_json_file filepath=nil, debug=nil
  filepath = filepath.nne(
    @memory[:memory_json_file_default]
  ).nne(
    @memory["memory_json_file_default"]
  )
  m = load__file_json_quiet [
    filepath,
    debug,
  ]
  rubyment_memory__merge_shallow_on(
    rubyment_memory__without_closure_keys(
      rubyment_memory__symbol_keys_shallow m
    )
  )
end
rubyment_memory__merge_shallow_with_json_file(filepath=nil, debug=nil) click to toggle source

merge @memory with the hash loaded from filepath, or @memory if not given (still @memory if nil).

The merge is shallow, ie, only top-level keys are merged. If the same key is present in both objects, the one in m will prevail.

# File lib/rubyment.rb, line 868
def rubyment_memory__merge_shallow_with_json_file filepath=nil, debug=nil
  filepath = filepath.nne(
    @memory[:memory_json_file_default]
  ).nne(
    @memory["memory_json_file_default"]
  )
  m = load__file_json_quiet [
    filepath,
    debug,
  ]
  rubyment_memory__merge_shallow(
    rubyment_memory__without_closure_keys(
      rubyment_memory__symbol_keys_shallow m
    )
  )
end
rubyment_memory__symbol_keys_shallow(m = nil) click to toggle source

ensure the top level keys of m, @memory if not given, are all symbols returns a copy of m, @memory if not given, where all the keys are ensured to be symbols.

When a ruby hash is stored as a JSON file, the symbol keys will be restored as strings. When that JSON file is reloaded, those strings will be loaded as strings. Therefore the resulting hash is not the same as the original. There may be other issues with keys having other types than strings and symbols, and deep keys can also be lost with that transformation. This function just takes cares of the issues created by the Rubyment memory implementation itself.

other special cases: m contents will be converted into symbols

# File lib/rubyment.rb, line 848
def rubyment_memory__symbol_keys_shallow m = nil
  update_memory = m.nne.negate_me
  m = m.nne @memory
  m = m.map { |k, v|  [k.to_sym, v] }.to_h
  m[:closure_keys].map!(&:to_sym)
  update_memory && (@memory = m) || m
end
rubyment_memory__to_json_file(filepath=nil, m=nil) click to toggle source

dumps the contents of m, or @memory if not given, into filepath, or m if not given (still m if nil).

# File lib/rubyment.rb, line 814
def rubyment_memory__to_json_file filepath=nil, m=nil
  m = m.nne @memory
  filepath = filepath.nne(
    m[:memory_json_file_default]
  ).nne(
    m["memory_json_file_default"]
  )
  file__json [
    filepath,
    m,
  ]
end
rubyment_memory__without_closure_keys(m=nil, closure_keys=nil) click to toggle source

returns a m, or copy of @memory if not given, without the keys listed in closure_keys, or m, if not given (still, m if m is empty).

# File lib/rubyment.rb, line 794
def rubyment_memory__without_closure_keys m=nil, closure_keys=nil
  m = m.nne @memory.dup
  closure_keys = closure_keys.nne(
    m[:closure_keys]
  ).nne(
    m["closure_keys"]
  )
  closure_keys.each {|closure_key|
    m.delete closure_key
  }
  m
end