Formal Languages Block: Difference between revisions

Latest revision as of 17:26, 28 September 2018

Authors

Idea, string analysis method, general architecture and architecture implementation - Oleg Sychev
Implementation of built-in language - Dmitry Mamontov

Description

The goal of formal languages block is to provide an API for managing formal languages - a well-known mathematical formalism, that defines a set of strings, constrained by rules.

Сurrent status

Feature	Description	Status
Scanning	Breaks string into tokens, that can be useful in further analysis	Implemented
Parsing	Constructs abstract syntax tree from a string, allowing deep analysis of string or even performing evaluation	Not implemented
Managing formal languages	Currently C, C++, printf format string scanners are implemented. Also implemented simple lexer for english language. User-defined lexers and parser are going to be implemented in next releases.	Implemented partially

Current language implementation status

Language	Scanning	Parsing
Simple english	Implemented	Not implemented
C	Implemented	Not implemented
C++	Implemented	Implemented partially
printf formatting string	Implemented	Not implemented

Installation

To work Formal languages block needs some additional components. They all need to be installed in order for question to work.

You need to install question type POASquestion (qtype_poasquestion), which is abstract (i.e. not showing as real question), but contains useful code for scanning and working with Unicode strings.

User interface

After adding formal languages block to course, a teacher could manage language visibilty by clicking on eye icons. The dimmed languages with disabled visibility will not be shown in CorrectWriting or other plugins, that use API of formal language block.

Note, that language visibility can be inherited from site settings. So, when site setting is applied to current course, user will see label "(Site)" before name of language, while "(Course)" label shows that setting applied on course level. If the language visibility for the site and course level are equal, language in this course assumed to be set to site-level visibility, and will be changed when the course-level visibility changes. If site visibility differs from course, it is assumed independent and will not change with the site-level changes.

Administrator also, can edit global visibility of formal languages, using global settings, located in administrator menu (see pictures for details).

A central part of admin page will look just like below.

When changing site-level language visibility, admin is shown the list of courses, affected by this change.

API for developers

A main block class - block_formal_langs provides a two simple functions, that might be useful for someone, that want to use our API to perform string scanning (see CorrectWriting question type examples to see how it works).

block_formal_langs::available_langs - returns array of languages, that could be used in current context. Receives current context ID.
block_formal_langs::lang_object - returns language object by language ID.

After getting language object, you can use create_from_string or create_from_db to scan string without referring to descriptions in database or refer to them. This will return a special object, that can be used for working with lexemes.

If $a is object, returned by create_from_string or create_from_db, you can use $a->string to get scanned string, $a->stream->tokens to return array of scanned lexemes, $a->stream->errors to get array of errors.

Using scanned lexemes, you could use type() method to obtain special type of lexeme, or value() to obtain a semantic value for lexeme.

Example:

1. You can use following code to print names and ids of all available languages in system context.

$langs = block_formal_langs::available_langs( context_system::instance()->id );

foreach($langs as $id => $name)

{

echo 'id :' . $id . ' name: ' . $name . PHP_EOL;

}

2. You can use following code to print all tokens' text, scanned a string with C language lexer.

$lang = block_formal_langs::lang_object(2); // Id for C programming language in most databases will be 2

$string = $lang->create_from_string('int a;');

$tokens = $string->stream->tokens;

foreach($tokens as $token)

{

echo $token->value() . PHP_EOL;

}

@@ Line 6: / Line 6: @@
 == Description ==
 The goal of formal languages block is to provide an API for managing formal languages - a well-known mathematical formalism, that defines a set of strings, constrained by rules.
-== Installation ==
+'''Сurrent status'''
+{| class="wikitable"
+|-
+! Feature
+! Description
+! Status
+|-
+| Scanning
+| Breaks string into tokens, that can be useful in further analysis
+| Implemented
+|-
+| Parsing
+| Constructs [http://en.wikipedia.org/wiki/Abstract_syntax_tree abstract syntax tree]  from a string, allowing deep analysis of string or even performing evaluation
+| Not implemented
+|-
+| Managing formal languages
+| Currently C, C++, printf format string scanners are implemented. Also implemented simple lexer for english language. User-defined lexers and parser are going to be implemented in next releases.
+| Implemented partially
+|}
+''' Current language implementation status'''
-To work CorrectWriting question type needs some additional components. They all need to be installed in order for question to work. You could download all them in one archive (from GoogleCode) or separately.
+{| class="wikitable"
+|-
+! Language
+! Scanning
+! Parsing
+|-
+| Simple english
+| Implemented
+| Not implemented
+|-
+| C
+| Implemented
+| Not implemented
+|-
+| C++
+| Implemented
+| Implemented partially
+|-
+| printf formatting string
+| Implemented
+| Not implemented
+|}
-If you downloaded one archive, unpacking it you should found "question" and "blocks" folders. Copy them in the main directory of Moodle installation (the one containing config.php) - it will install everything in the correct places.
+== Installation ==
-If you downloaded all parts separately (for example because Moodle plugins Directory don't allow them to be downloaded together), you should get 3 archives. Place "correctwriting" and "poasquestion" folders in the question/type folder of Moodle installation. "formal_langs" should be placed in the blocks folder.
+To work Formal languages block needs some additional components. They all need to be installed in order for question to work.
-After having files in place login as administrator and go to the notifications page.
+You need to install question type POASquestion ([https://moodle.org/plugins/view.php?plugin=qtype_poasquestion qtype_poasquestion]), which is abstract (i.e. not showing as real question), but contains useful code for scanning and working with Unicode strings.
 == User interface ==
@@ Line 23: / Line 65: @@
 After adding formal languages block to course, a teacher could manage language visibilty by clicking on eye icons.  The dimmed languages with disabled visibility will not be shown in CorrectWriting or other plugins, that use API of formal language block.
+Note, that language visibility can be inherited from site settings. So, when site setting is applied to current course, user will see label "(Site)" before name of language, while "(Course)" label shows that setting applied on course level. If the language visibility for the site and course level are equal, language in this course assumed to be set to site-level visibility, and will be changed when the course-level visibility changes. If site visibility differs from course, it is assumed independent and will not change with the site-level changes.
 Administrator also, can edit global visibility of formal languages, using global settings, located in administrator menu (see pictures for details).
 [[{{ns:file}}:block_formal_langs_global_settings_link.PNG]]
+A central part of admin page will look just like below.
 [[{{ns:file}}:block_formal_langs_global_settings_page.PNG]]
+When changing site-level language visibility, admin is shown the list of courses, affected by this change.
 == API for developers ==
+A main block class - '''block_formal_langs''' provides a two simple functions, that might be useful for someone, that want to use our API to perform string scanning (see CorrectWriting question type examples to see how it works).
+#'''block_formal_langs::available_langs''' - returns array of languages, that could be used in current context. Receives current context ID.
+#'''block_formal_langs::lang_object'''    - returns language object by language ID.
+After getting language object, you can use '''create_from_string''' or '''create_from_db''' to scan string without referring to descriptions in database or refer to them. This will return a special object, that can be used for working with lexemes.
+If $a is object, returned by '''create_from_string''' or '''create_from_db''', you can use $a->string to get scanned string, $a->stream->tokens to return array of scanned lexemes, $a->stream->errors to get array of errors.
+Using scanned lexemes, you could use '''type()''' method to obtain special type of lexeme, or '''value()''' to obtain a semantic value for lexeme.
+'''Example:'''
+'''1. You can use following code to print names and ids of all available languages in system context.'''
+<code php>
+$langs = block_formal_langs::available_langs( context_system::instance()->id );
+foreach($langs as $id => $name)
+{
+echo  'id :' . $id  . ' name: ' . $name . PHP_EOL;
+}
+</code>
+'''2.  You can use following code to print all tokens' text, scanned a string with C language lexer.'''
+<code php>
+$lang = block_formal_langs::lang_object(2); // Id for C programming language in most databases will be 2
+$string = $lang->create_from_string('int a;');
+$tokens = $string->stream->tokens;
+foreach($tokens as $token)
+{
+echo  $token->value() . PHP_EOL;
+}
+</code>
+[[Category: Block]]
+[[Category: Contributed code]]
-[[Category: Blocks]][[Category: Contributed code]]
+[[es:Bloque de Lenguajes Formales]]

Documentation