Action introspection

[user202729]

Action is one of the more poorly-understood part of the Plover source code/engine/documentation.

There are documentations, but it (currently) doesn't clearly explain what global/local states are.

---

You can somewhat figure out yourself using (my) plover-debugging-console plugin.

• (write some strokes)

• Enter x=list(engine.translator_state.translations)

  (need to copy otherwise the list will change over time)

• Look at the content of x: It's a list of Translation objects, each contains a formatting attribute which is the list of _Action objects.

See https://plover.readthedocs.io/en/latest/api/formatting.html#plover.formatting._Action / https://plover2.readthedocs.io/en/latest/api/formatting.html#plover.formatting._Action / docstrings in

plover/plover/formatting.py

Lines 571 to 696 in 4394ef1

	class _Action:
	"""A hybrid class that stores instructions and resulting state.
	A single translation may be formatted into one or more actions. The
	instructions are used to render the current action and the state is used as
	context to render future translations.
	"""
	def __init__(self,
	# Previous.
	prev_attach=False, prev_replace='',
	# Current.
	glue=False, word=None, orthography=True, space_char=' ',
	upper_carry=False, case=None, text=None, trailing_space='',
	word_is_finished=None, combo=None, command=None,
	# Next.
	next_attach=False, next_case=None
	):
	"""Initialize a new action.
	Arguments:
	prev_attach -- True if there should be no space between this and the
	previous action.
	prev_replace -- Text that should be deleted for this action.
	glue -- True if there be no space between this and the next action if
	the next action also has glue set to True.
	word -- The current root word (sans prefix, and un-cased). This is
	context for future actions whose behavior depends on it such as
	suffixes.
	upper_carry -- True if we are uppercasing the current word.
	word_is_finished -- True if word is finished.
	orthography -- True if orthography rules should be applies when adding
	a suffix to this action.
	space_char -- this character will replace spaces after all other
	formatting has been applied
	case -- an integer to determine which case to output after formatting
	text -- The text that should be rendered for this action.
	trailing_space -- This the space that would be added when rendering
	up to this action with space placement set to
	'after output'.
	combo -- The key combo, in plover's key combo language, that should be
	executed for this action.
	command -- The command that should be executed for this action.
	next_attach -- True if there should be no space between this and the next
	action.
	next_case -- Case to apply to next action: capitalize/lower/upper...
	"""
	# State variables
	self.prev_attach = prev_attach
	self.glue = glue
	self.word = word
	self.upper_carry = upper_carry
	self.orthography = orthography
	self.next_attach = next_attach
	self.next_case = next_case
	if word_is_finished is None:
	self.word_is_finished = not self.next_attach
	else:
	self.word_is_finished = word_is_finished
	# Persistent state variables
	self.space_char = space_char
	self.case = case
	self.trailing_space = trailing_space
	# Instruction variables
	self.prev_replace = prev_replace
	self.text = text
	self.combo = combo
	self.command = command
	def copy_state(self):
	"""Clone this action but only clone the state variables."""
	return _Action(
	# Previous.
	prev_attach=self.next_attach,
	# Current.
	case=self.case, glue=self.glue, orthography=self.orthography,
	space_char=self.space_char, upper_carry=self.upper_carry,
	word=self.word, trailing_space=self.trailing_space,
	word_is_finished=self.word_is_finished,
	# Next.
	next_attach=self.next_attach, next_case=self.next_case,
	)
	def new_state(self):
	return _Action(
	# Previous.
	prev_attach=self.next_attach,
	# Current.
	space_char=self.space_char, case=self.case,
	trailing_space=self.trailing_space,
	# Next.
	)
	def __eq__(self, other):
	return self.__dict__ == other.__dict__
	def __ne__(self, other):
	return not self == other
	def __str__(self):
	kwargs = [
	'%s=%r' % (k, v)
	for k, v in self.__dict__.items()
	if v != self.DEFAULT.__dict__[k]
	]
	return 'Action(%s)' % ', '.join(sorted(kwargs))
	def __repr__(self):
	return str(self)

for some quick overview first.