{"id":20315223,"url":"https://github.com/sysread/auto-mata","last_synced_at":"2025-12-12T02:47:27.184Z","repository":{"id":56835953,"uuid":"83568794","full_name":"sysread/Auto-Mata","owner":"sysread","description":"An easy to use finite state machine for Perl","archived":false,"fork":false,"pushed_at":"2017-03-20T19:07:16.000Z","size":53,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-24T05:58:44.233Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sysread.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-01T15:17:06.000Z","updated_at":"2021-04-22T19:31:40.000Z","dependencies_parsed_at":"2022-09-07T07:10:22.720Z","dependency_job_id":null,"html_url":"https://github.com/sysread/Auto-Mata","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FAuto-Mata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FAuto-Mata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FAuto-Mata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FAuto-Mata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sysread","download_url":"https://codeload.github.com/sysread/Auto-Mata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241818877,"owners_count":20025210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T18:18:22.119Z","updated_at":"2025-12-12T02:47:27.128Z","avatar_url":"https://github.com/sysread.png","language":"Perl","readme":"=pod\n\n=encoding UTF-8\n\n=head1 NAME\n\nAuto::Mata - A simple, reliable finite state machine\n\n=head1 VERSION\n\nversion 0.09\n\n=head1 SYNOPSIS\n\n  use strict;\n  use warnings;\n  use Auto::Mata;\n  use Types::Standard -types;\n\n  my $NoData   = Undef,\n  my $HasFirst = Tuple[Str];\n  my $HasLast  = Tuple[Str, Str];\n  my $Complete = Tuple[Str, Str, Int];\n\n  sub get_input {\n    my $query = shift;\n    print \"\\n$query \";\n    my $input = \u003cSTDIN\u003e;\n    chomp $input;\n    return $input;\n  }\n\n  my $fsm = machine {\n    ready 'READY';\n    term  'TERM';\n\n    transition 'READY', to 'FIRST',\n      on $NoData,\n      with { return [get_input(\"What is your first name? \")] };\n\n    transition 'FIRST', to 'LAST',\n      on $HasFirst,\n      with { return [@$_, get_input(\"What is your last name? \")] };\n\n    transition 'LAST', to 'AGE',\n      on $HasLast,\n      with { return [@$_, get_input(\"What is your age? \")] };\n\n    transition 'AGE', to 'TERM',\n      on $Complete;\n  };\n\n  my $prog = $fsm-\u003e();\n  my $data = $prog-\u003e();\n\n  printf \"Hello %s %s, aged %d years!\\n\", @$data;\n\n=head1 DESCRIPTION\n\nFinite state machines (or automata) are a technique for modeling the workflow\nof a program as a series of dependent, programmable steps. State machines are\nuseful tools for building software whose behavior can be predicted with a high\ndegree of confidence.\n\nUsing a state machine to implement a program helps to ensure determinacy, where\nthe program state is known at all times. Designing software this way leads to\ngreater accuracy and testability.\n\n=head1 WHAT IS A STATE MACHINE\n\nA program can be described as a set of discrete I\u003cstates\u003e. Each state is\ndefined by the existence or value of a variable, the presence of a file, etc.\nA state machine replaces the if/else clauses typically used to inspect and\nbranch based on run-time conditions.\n\nRather than performing ad hoc tests using if/else conditions, the program is\ninstead described as a set of I\u003ctransitions\u003e which move the program from an\ninitial state to a final state. The state machine begins in the \"ready\" state.\nThe initial state is described using an identifier and a type constraint (see\nL\u003cType::Tiny\u003e and L\u003cTypes::Standard\u003e).  When input matches the transition's\ninitial state, the transition step is executed, after which the new initial\nstate is the final state described in the transition. This proceeds until the\n\"terminal\" state is reached.\n\n=head1 EXPORTED SUBROUTINES\n\nC\u003cAuto::Mata\u003e is an C\u003cExporter\u003e. All subroutines are exported by default.\n\n=head2 machine\n\nCreates a lexical context in which a state machine is defined. Returns a\nfunction that creates new instances of the defined automata.\n\nThe automata instance is itself a builder function. When called, it returns a\nnew function that accepts the initial program state as input and returns the\nfinal state.\n\nThis instance function's input value in conjunction with the current state\nlabel is matched (see L\u003c/on\u003e) against the transition table (defined with\nL\u003c/transition\u003e) to determine the next state.\n\nOnce a match has been made, the action defined for the transition (using\nL\u003c/with\u003e) will be executed. During evaluation of the L\u003c/with\u003e function, C\u003c$_\u003e\nis a reference to the input value.\n\nNote that the input state is modified in place during the transition.\n\n  # Define the state machine\n  my $builder = machine { ... };\n\n  # Create an instance\n  my $instance = $builder-\u003e();\n\n  # Run the program to get the result\n  my $result = $instance-\u003e($state_data);\n\nIf the builder function is called with a true value as the first argument, it\nwill instead build an interactive iterator that performs a single transition\nper call. It accepts a single value as input representing the program's current\nstate.\n\nThe return value is new state's label in scalar context, the label and state in\nlist context, and C\u003cundef\u003e after the terminal state has been reached.\n\n  # Define the state machine\n  my $builder = machine { ... };\n\n  # Create an instance of the machine\n  my $program = $builder-\u003e();\n\n  # Run the program\n  my $state = [];\n  while (my ($token, $data) = $program-\u003e($state)) {\n    print \"Current state is $token\\n\"; # $token == label of current state (e.g. READY)\n    print \"State data: @$data\\n\";      # $data == $state input to $program\n  }\n\n=head2 ready\n\nSets the name given to the \"ready\" state. This is the initial state held by the\nstate machine.\n\n=head2 terminal\n\nSets the name given to the \"terminal\" state. This is the final state held by\nthe state machine. Once in this state, the machine will cease to perform any\nmore work.\n\n=head2 term\n\nAlias for L\u003c/terminal\u003e.\n\n=head2 transition\n\nDefines a transition between two states by matching the symbol identifying the\nstate at the end of the most recent transition and the input passed into the\ntransition engine (see L\u003c/machine\u003e) for the transition being performed.\n\nThe first argument to C\u003ctransition\u003e is the symbol identifying the state at the\noutset of the transition. A L\u003cType::Tiny\u003e constraint is used to identify the\nexpected input using L\u003c/on\u003e. When both of these match the current program\nstate, the return value of L\u003c/with\u003e replaces the current input in place.\nL\u003c/with\u003e is permitted to the current input. If L\u003c/with\u003e is not specified, the\ninput remains unchanged. Once the transition is complete, the symbol supplied\nby L\u003c/to\u003e will identify the current program state.\n\nThe first transition is always from the \"ready\" state. The final transition is\nalways to the \"terminal\" state. There may be no transitions from the \"terminal\"\nstate.\n\nThe following functions are used in concert with L\u003c/transition\u003e.\n\n=over\n\n=item to\n\nA name identifying the state held I\u003cafter\u003e the transition.\n\n=item on\n\nA L\u003cType::Tiny\u003e constraint that matches the state immediately I\u003cbefore\u003e the\ntransition.\n\n=item with\n\nA code block whose return value is the mutable state used to determine the next\ntransition to perform. Within the code block C\u003c$_\u003e is a reference to the\nprogram state.\n\n=item using\n\nAlias for L\u003c/with\u003e that may be used to avoid conflicts with other packages\nexporting C\u003cwith\u003e. Prevent the export of C\u003cwith\u003e in the typical way (see\nL\u003cExporter/Specialised-Import-Lists\u003e).\n\n  use Auto::Mata '!with';\n\n  machine {\n    ...\n\n    transition 'INITIAL_STATE', to 'THE_NEXT_STATE',\n      on Dict[command =\u003e Str, remember =\u003e Bool],\n      with {\n        if ($_-\u003e{command} eq 'fnord') {\n          return {command =\u003e undef, remember =\u003e 0};\n        }\n        else {\n          return {command =\u003e undef, remember =\u003e 1};\n        }\n      };\n  };\n\n=back\n\n=head1 DEBUGGING\n\nIf C\u003c$ENV{DEBUG_AUTOMATA}\u003e is true, helpful debugging messages will be emitted\nto C\u003cSTDERR\u003e.\n\n=head1 AUTHOR\n\nJeff Ober \u003csysread@fastmail.fm\u003e\n\n=head1 COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2017 by Jeff Ober.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n\n=cut\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysread%2Fauto-mata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsysread%2Fauto-mata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysread%2Fauto-mata/lists"}