wiki.visual-prolog.com - User contributions [en]

Visual Prolog 7.4 New Features

2013-06-04T04:35:02Z

Alexander Doronin: /* Build 7402 */

== Language ==

=== 64 bit programs ===

The main new feature in Visual Prolog 7.4 is the ability to generate 64 bit programs (Commercial Edition only), making it possible to write programs that exploit more of the computers resources.

'''Notice''' to ensure source code compatability between 32 and 64 bit programs a number of types have been changed and it is necessary to update the programs, see [[Visual Prolog 7.4 Upgrade Notes]].

See also [[64 bit Windows]]

=== Program Point ===

Support for exceptions handling improvement (programPoint type and attribute, implicit programPoint argument). See also [[Language Reference/Predicates#programPoint|programPoint]].

=== Syntax & Warnings ===

* Better handling of comma (,) before then, elseif, else, end if, do and end foreach
* Error c550 for inlining a field from a null pointer
* Warning c647 if bound/1 is applied to a variable which is always free
* Warning if scope is only opened but is not actually used (unused open for class core is ignored). Removing such excessive open-directives makes the Optimal Includes more effective. This warning is switched off by the default (option /w:231 turns it on).

== PFC ==

PFC have been updated to be 64 bit compatible. A few packages have not been updated, but have instead been deprecated and replaced by new packages.

* <vp>vpiEditor</vp> is deprecated (replaced by <vp>sciLexer</vp> editor)
* <vp>regExp</vp> is deprecated (replaced by <vp>regEx</vp>)

=== PFC/GUI ===

* <vp>sciLexer</vp> New editor control based on the [http://www.scintilla.org/ Scintilla] editor with lexers (including Visual Prolog lexer).
* <vp>webBrowser</vp> New control control comprehensive wrapping of the Internet Explorer WebBrowserControl
* Improved clipboard handling (with HTML support)
* <vp>ribbonControl</vp> and command system and controlSerialization; with a run-time visual designer that simplifies the process of making ribbons
* <vp>toolboxControl</vp> New control
* <vp>headerControl</vp> New control
* <vp>rebar</vp> + <vp>statusBar</vp> New packages
* <vp>shellNotificationIcon</vp> for handing notifications in the shells notification area + Demo
* <vp>toolTip</vp> New package and toolTip functionality on standard controls + Demo
* <vp>splitControl</vp> New control for multi-split management; with a run-time visual designer that simplifies the process of making splits
* <vp>splitterControl</vp> New control for the split in windows
* <vp>dragNdrop</vp> New class for (in-program) drag and drop functionality + Demo
* Object oriented GDI support
* Object oriented GDI+ support for
** <vp>bitmap</vp>
** <vp>brush</vp>
** <vp>font</vp>
** <vp>palette</vp>
** <vp>pen</vp>
** <vp>deviceContext</vp>
** <vp>icon</vp>
* <vp>gui_native::createDialogIndirectParam</vp> Update for font handling
* <vp>window::listenUntilDestroy</vp> New predicate for listening to an event, but detach the listening when the window is destroyed
* <vp>messageLoop</vp> for SDI applications

=== PFC (non-GUI) ===

* <vp>regEx</vp> package based on [www.boost.org/libs/regex boost regular expression library]
* <vp>mapM_hash</vp> & <vp>setM_hash</vp> New classes for hash table implementations of maps and sets
* <vp>arrayM</vp> uses pointer to memory instead of binary: makes it possible to interpret non-binaries as arrays and is more efficient
* <vp>arrayM_inline</vp> New class for interpretation of C/C++ struct arrays
* <vp>arrayM_boolean</vp> New class for compact boolean arrays (1 bit per boolean).
* <vp>array2M</vp> New class for 2 dimensional arrays
* <vp>socket</vp> New class for object oriented WinSock2 support
* <vp>event0</vp> - <vp>event7</vp> New classes for general/generic event handling (notify+listener)
* <vp>iStream_stream</vp> class for mapping a Visual Prolog stream as an IStream com object (CE-only)
* improved '''ISAPI''' support
* <vp>json</vp> (pfc/web/json) and <vp>jsonRpc</vp> New packages for JSON and JSON RPC 2.0 support (CE-only)
* memory allocate functions with argument for atomic/non-atomic
* ODBC auto parameter binding get the size from the database by means of SQLDescribeParam
* <vp>shell_api::sHCreateStreamOnFileEx</vp> new predicate for creating an IStream com object from a file
* <vp>xhtmlWriter</vp> class for writing xhtml/xhtml5 using an <vp>xmlWriter</vp>
* <vp>xmlReader</vp> & <vp>xmlWriter</vp> based on the xmlLite API (CE-only) + Demo
* <vp>internetExplorer</vp> class for automating an out-of-process Internet Explorer

== IDE ==

* New simplified settings dialog
* Add "No To All" button to the dialog for removing file from a project
* Create empty clause if there is compiler error for absent clause for a predicate
* Global unreachability support
* History of Run Arguments
* Improved Browse View
* Improved the manifest handling
* Load browse info in a separate thread (performance optimization)
* SDI applications support
* Tools entries in project-tree popup menu

== Debugger ==

* Soft/hard breakpoints
* Add current class facts into the variable window
* Show class facts in the Variable Window for a class predicate
* Give names to objects
* Show <vp>gmtTimeValue</vp> and <vp>localTimeValue</vp> as dates and times.
* Show the error description for <vp>hResult</vp> values.
* Watch Window improvement
* Copying the entire debug tree to the clipboard
* Improve memory view for 64bit and break points handling

== Others ==

* win32.lib + win32.x64.lib updated to '''Windows Software Development Kit (SDK) for Windows 8'''
* PFC, VPI, IDE: Help button in the title bar
* SolutionManager. A utility for better handling of a collection of projects
* VipBuilder: Add /platform option for target machine
* VPI: Support DDE in SDI application

== Updates ==

=== Build 7402 ===

Important bug fixes:

*Compiler. Incorrect handling of some special floating-point constants leads to unexpected compile time errors (see [http://discuss.visual-prolog.com/viewtopic.php?t=9582 Real value 1.#INF is out of the range]).
*Compiler. Missing warning for unreachable codes (see [http://discuss.visual-prolog.com/viewtopic.php?t=9569 Unused Variable]).
*Compiler. [http://discuss.visual-prolog.com/viewtopic.php?t=9502 Ambiguity in wedBrowserControl].
*Compiler. Codes generation bug for string comparisson (it can lead to access violation exception at runtime in some cases).
*Compiler. Nested <vp>if</vp>-<vp>then</vp>-<vp>else</vp> expressions can raise unexpected error messages related to the wrong flow patterns.
*Compiler. Unexpected error message for supported interface and inherited class conflict for a generic scope.
*Compiler. No error if constructor is absent for an object class with <vp>noDefaultConstructor</vp> attribute.
*Compiler. Incorrect warning c231 (scope is opened but not used) in some cases.
*Compiler. Code generation bug for nested <vp>finally</vp> statements with cuts in the <vp>try</vp> part (this could could lead to exceptions at runtime in some cases).
*Compiler. Code generation bug for read-only property implemented by a clause with several heads.
*Compiler. Anonymous predicates in both ''xxx'' as function and ''xxx'' as predicate give declaration conflict.
*Compiler. Incorrect object file if number of fixups exceeds the limit of <vp>0xFFFF</vp> (this could lead to the incorrect state of some statically initialized data, like class facts, etc.).
*Compiler. Several bugs in 64bit codes generation.
*Runtime: Bug in symbol comparison (see ).
*IDE: Browse search shows the same predicate many times.
*Debugger: Several bugs related to the Variables view.
*Debugger: Some problems in single step in if-then-else expression.
*PFC: [http://discuss.visual-prolog.com/viewtopic.php?t=9565 Bug in arrayM_boolean].
*PFC: Some keywords coloring (see [http://discuss.visual-prolog.com/viewtopic.php?t=9610 Cosmetic detail : <vp>guard</vp>]).
*PFC: Some problems with handling of enter/leave mouse event.
*VPI: Incorrect behavior of predicate <vp>getText/1-></vp>.
*Vip Linker: It does not accept utf-8 '''.def''' files (see [http://discuss.visual-prolog.com/viewtopic.php?t=9515 Dll - error in file MyDll.def]).

+ Some minor bug fixes

=== Build 7401 ===

The following new feature has been implemented:

* if-the-else expressions
* Condition in if-statement/expression can be <vp>nondeterm</vp>/<vp>multi</vp>
* <vp>thiscall</vp> calling convention

Important bug fixes:

* ChainDB, 64bit: Problems when storing terms in a chain if "in_memory" is used See [http://discuss.visual-prolog.com/viewtopic.php?t=9390 External Databases in V7.4 in 64bits]
* PFC: [http://discuss.visual-prolog.com/viewtopic.php?t=9377 Problem with console::setLocation in vip 7.4]
* VPI: Incorrect behavior of getText/1->
* [http://discuss.visual-prolog.com/viewtopic.php?t=9421 Header prints in chinese!?!]

+ Some minor bug fixes

== See also ==

* [[Visual Prolog 7.4 Upgrade Notes]]

[[Category:Release Notes]]

Visual Prolog 7.4 New Features

2013-06-04T04:23:45Z

Alexander Doronin: /* Build 7402 */

== Language ==

=== 64 bit programs ===

The main new feature in Visual Prolog 7.4 is the ability to generate 64 bit programs (Commercial Edition only), making it possible to write programs that exploit more of the computers resources.

'''Notice''' to ensure source code compatability between 32 and 64 bit programs a number of types have been changed and it is necessary to update the programs, see [[Visual Prolog 7.4 Upgrade Notes]].

See also [[64 bit Windows]]

=== Program Point ===

Support for exceptions handling improvement (programPoint type and attribute, implicit programPoint argument). See also [[Language Reference/Predicates#programPoint|programPoint]].

=== Syntax & Warnings ===

* Better handling of comma (,) before then, elseif, else, end if, do and end foreach
* Error c550 for inlining a field from a null pointer
* Warning c647 if bound/1 is applied to a variable which is always free
* Warning if scope is only opened but is not actually used (unused open for class core is ignored). Removing such excessive open-directives makes the Optimal Includes more effective. This warning is switched off by the default (option /w:231 turns it on).

== PFC ==

PFC have been updated to be 64 bit compatible. A few packages have not been updated, but have instead been deprecated and replaced by new packages.

* <vp>vpiEditor</vp> is deprecated (replaced by <vp>sciLexer</vp> editor)
* <vp>regExp</vp> is deprecated (replaced by <vp>regEx</vp>)

=== PFC/GUI ===

* <vp>sciLexer</vp> New editor control based on the [http://www.scintilla.org/ Scintilla] editor with lexers (including Visual Prolog lexer).
* <vp>webBrowser</vp> New control control comprehensive wrapping of the Internet Explorer WebBrowserControl
* Improved clipboard handling (with HTML support)
* <vp>ribbonControl</vp> and command system and controlSerialization; with a run-time visual designer that simplifies the process of making ribbons
* <vp>toolboxControl</vp> New control
* <vp>headerControl</vp> New control
* <vp>rebar</vp> + <vp>statusBar</vp> New packages
* <vp>shellNotificationIcon</vp> for handing notifications in the shells notification area + Demo
* <vp>toolTip</vp> New package and toolTip functionality on standard controls + Demo
* <vp>splitControl</vp> New control for multi-split management; with a run-time visual designer that simplifies the process of making splits
* <vp>splitterControl</vp> New control for the split in windows
* <vp>dragNdrop</vp> New class for (in-program) drag and drop functionality + Demo
* Object oriented GDI support
* Object oriented GDI+ support for
** <vp>bitmap</vp>
** <vp>brush</vp>
** <vp>font</vp>
** <vp>palette</vp>
** <vp>pen</vp>
** <vp>deviceContext</vp>
** <vp>icon</vp>
* <vp>gui_native::createDialogIndirectParam</vp> Update for font handling
* <vp>window::listenUntilDestroy</vp> New predicate for listening to an event, but detach the listening when the window is destroyed
* <vp>messageLoop</vp> for SDI applications

=== PFC (non-GUI) ===

* <vp>regEx</vp> package based on [www.boost.org/libs/regex boost regular expression library]
* <vp>mapM_hash</vp> & <vp>setM_hash</vp> New classes for hash table implementations of maps and sets
* <vp>arrayM</vp> uses pointer to memory instead of binary: makes it possible to interpret non-binaries as arrays and is more efficient
* <vp>arrayM_inline</vp> New class for interpretation of C/C++ struct arrays
* <vp>arrayM_boolean</vp> New class for compact boolean arrays (1 bit per boolean).
* <vp>array2M</vp> New class for 2 dimensional arrays
* <vp>socket</vp> New class for object oriented WinSock2 support
* <vp>event0</vp> - <vp>event7</vp> New classes for general/generic event handling (notify+listener)
* <vp>iStream_stream</vp> class for mapping a Visual Prolog stream as an IStream com object (CE-only)
* improved '''ISAPI''' support
* <vp>json</vp> (pfc/web/json) and <vp>jsonRpc</vp> New packages for JSON and JSON RPC 2.0 support (CE-only)
* memory allocate functions with argument for atomic/non-atomic
* ODBC auto parameter binding get the size from the database by means of SQLDescribeParam
* <vp>shell_api::sHCreateStreamOnFileEx</vp> new predicate for creating an IStream com object from a file
* <vp>xhtmlWriter</vp> class for writing xhtml/xhtml5 using an <vp>xmlWriter</vp>
* <vp>xmlReader</vp> & <vp>xmlWriter</vp> based on the xmlLite API (CE-only) + Demo
* <vp>internetExplorer</vp> class for automating an out-of-process Internet Explorer

== IDE ==

* New simplified settings dialog
* Add "No To All" button to the dialog for removing file from a project
* Create empty clause if there is compiler error for absent clause for a predicate
* Global unreachability support
* History of Run Arguments
* Improved Browse View
* Improved the manifest handling
* Load browse info in a separate thread (performance optimization)
* SDI applications support
* Tools entries in project-tree popup menu

== Debugger ==

* Soft/hard breakpoints
* Add current class facts into the variable window
* Show class facts in the Variable Window for a class predicate
* Give names to objects
* Show <vp>gmtTimeValue</vp> and <vp>localTimeValue</vp> as dates and times.
* Show the error description for <vp>hResult</vp> values.
* Watch Window improvement
* Copying the entire debug tree to the clipboard
* Improve memory view for 64bit and break points handling

== Others ==

* win32.lib + win32.x64.lib updated to '''Windows Software Development Kit (SDK) for Windows 8'''
* PFC, VPI, IDE: Help button in the title bar
* SolutionManager. A utility for better handling of a collection of projects
* VipBuilder: Add /platform option for target machine
* VPI: Support DDE in SDI application

== Updates ==

=== Build 7402 ===

Important bug fixes:

*Compiler. Incorrect handling of some special floating-point constants leads to unexpected compile time errors (see [http://discuss.visual-prolog.com/viewtopic.php?t=9582 Real value 1.#INF is out of the range]).
*Compiler. Missing warning for unreachable codes (see [http://discuss.visual-prolog.com/viewtopic.php?t=9569 Unused Variable]).
*Compiler. [http://discuss.visual-prolog.com/viewtopic.php?t=9502 Ambiguity in wedBrowserControl].
*Compiler. Codes generation bug for string comparisson (it can lead to access violation exception at runtime in some cases).
*Compiler. Nested <vp>if</vp>-<vp>then</vp>-<vp>else</vp> expressions can raise unexpected error messages related to the wrong flow patterns.
*Compiler. Unexpected error message for supported interface and inherited class conflict for a generic scope.
*Compiler. No error if constructor is absent for an object class with <vp>noDefaultConstructor</vp> attribute.
*Compiler. Incorrect warning c231 (scope is opened but not used) in some cases.
*Compiler. Code generation bug for nested <vp>finally</vp> statements with cuts in the <vp>try</vp> part (this could could lead to exceptions at runtime in some cases).
*Compiler. Code generation bug for read-only property implemented by a clause with several heads.
*Compiler. Anonymous predicates in both ''xxx'' as function and ''xxx'' as predicate give declaration conflict.
*Compiler. Incorrect object file if number of fixups exceeds the limit of <vp>0xFFFF</vp> (this could lead to the incorrect state of some statically initialized data, like class facts, etc.).
*Compiler. Several bugs in 64bit codes generation.

+ Some minor bug fixes

=== Build 7401 ===

The following new feature has been implemented:

* if-the-else expressions
* Condition in if-statement/expression can be <vp>nondeterm</vp>/<vp>multi</vp>
* <vp>thiscall</vp> calling convention

Important bug fixes:

* ChainDB, 64bit: Problems when storing terms in a chain if "in_memory" is used See [http://discuss.visual-prolog.com/viewtopic.php?t=9390 External Databases in V7.4 in 64bits]
* PFC: [http://discuss.visual-prolog.com/viewtopic.php?t=9377 Problem with console::setLocation in vip 7.4]
* VPI: Incorrect behavior of getText/1->
* [http://discuss.visual-prolog.com/viewtopic.php?t=9421 Header prints in chinese!?!]

+ Some minor bug fixes

== See also ==

* [[Visual Prolog 7.4 Upgrade Notes]]

[[Category:Release Notes]]

Visual Prolog 7.4 New Features

2013-06-04T04:17:40Z

Alexander Doronin: /* Build 7402 */

== Language ==

=== 64 bit programs ===

The main new feature in Visual Prolog 7.4 is the ability to generate 64 bit programs (Commercial Edition only), making it possible to write programs that exploit more of the computers resources.

'''Notice''' to ensure source code compatability between 32 and 64 bit programs a number of types have been changed and it is necessary to update the programs, see [[Visual Prolog 7.4 Upgrade Notes]].

See also [[64 bit Windows]]

=== Program Point ===

Support for exceptions handling improvement (programPoint type and attribute, implicit programPoint argument). See also [[Language Reference/Predicates#programPoint|programPoint]].

=== Syntax & Warnings ===

* Better handling of comma (,) before then, elseif, else, end if, do and end foreach
* Error c550 for inlining a field from a null pointer
* Warning c647 if bound/1 is applied to a variable which is always free
* Warning if scope is only opened but is not actually used (unused open for class core is ignored). Removing such excessive open-directives makes the Optimal Includes more effective. This warning is switched off by the default (option /w:231 turns it on).

== PFC ==

PFC have been updated to be 64 bit compatible. A few packages have not been updated, but have instead been deprecated and replaced by new packages.

* <vp>vpiEditor</vp> is deprecated (replaced by <vp>sciLexer</vp> editor)
* <vp>regExp</vp> is deprecated (replaced by <vp>regEx</vp>)

=== PFC/GUI ===

* <vp>sciLexer</vp> New editor control based on the [http://www.scintilla.org/ Scintilla] editor with lexers (including Visual Prolog lexer).
* <vp>webBrowser</vp> New control control comprehensive wrapping of the Internet Explorer WebBrowserControl
* Improved clipboard handling (with HTML support)
* <vp>ribbonControl</vp> and command system and controlSerialization; with a run-time visual designer that simplifies the process of making ribbons
* <vp>toolboxControl</vp> New control
* <vp>headerControl</vp> New control
* <vp>rebar</vp> + <vp>statusBar</vp> New packages
* <vp>shellNotificationIcon</vp> for handing notifications in the shells notification area + Demo
* <vp>toolTip</vp> New package and toolTip functionality on standard controls + Demo
* <vp>splitControl</vp> New control for multi-split management; with a run-time visual designer that simplifies the process of making splits
* <vp>splitterControl</vp> New control for the split in windows
* <vp>dragNdrop</vp> New class for (in-program) drag and drop functionality + Demo
* Object oriented GDI support
* Object oriented GDI+ support for
** <vp>bitmap</vp>
** <vp>brush</vp>
** <vp>font</vp>
** <vp>palette</vp>
** <vp>pen</vp>
** <vp>deviceContext</vp>
** <vp>icon</vp>
* <vp>gui_native::createDialogIndirectParam</vp> Update for font handling
* <vp>window::listenUntilDestroy</vp> New predicate for listening to an event, but detach the listening when the window is destroyed
* <vp>messageLoop</vp> for SDI applications

=== PFC (non-GUI) ===

* <vp>regEx</vp> package based on [www.boost.org/libs/regex boost regular expression library]
* <vp>mapM_hash</vp> & <vp>setM_hash</vp> New classes for hash table implementations of maps and sets
* <vp>arrayM</vp> uses pointer to memory instead of binary: makes it possible to interpret non-binaries as arrays and is more efficient
* <vp>arrayM_inline</vp> New class for interpretation of C/C++ struct arrays
* <vp>arrayM_boolean</vp> New class for compact boolean arrays (1 bit per boolean).
* <vp>array2M</vp> New class for 2 dimensional arrays
* <vp>socket</vp> New class for object oriented WinSock2 support
* <vp>event0</vp> - <vp>event7</vp> New classes for general/generic event handling (notify+listener)
* <vp>iStream_stream</vp> class for mapping a Visual Prolog stream as an IStream com object (CE-only)
* improved '''ISAPI''' support
* <vp>json</vp> (pfc/web/json) and <vp>jsonRpc</vp> New packages for JSON and JSON RPC 2.0 support (CE-only)
* memory allocate functions with argument for atomic/non-atomic
* ODBC auto parameter binding get the size from the database by means of SQLDescribeParam
* <vp>shell_api::sHCreateStreamOnFileEx</vp> new predicate for creating an IStream com object from a file
* <vp>xhtmlWriter</vp> class for writing xhtml/xhtml5 using an <vp>xmlWriter</vp>
* <vp>xmlReader</vp> & <vp>xmlWriter</vp> based on the xmlLite API (CE-only) + Demo
* <vp>internetExplorer</vp> class for automating an out-of-process Internet Explorer

== IDE ==

* New simplified settings dialog
* Add "No To All" button to the dialog for removing file from a project
* Create empty clause if there is compiler error for absent clause for a predicate
* Global unreachability support
* History of Run Arguments
* Improved Browse View
* Improved the manifest handling
* Load browse info in a separate thread (performance optimization)
* SDI applications support
* Tools entries in project-tree popup menu

== Debugger ==

* Soft/hard breakpoints
* Add current class facts into the variable window
* Show class facts in the Variable Window for a class predicate
* Give names to objects
* Show <vp>gmtTimeValue</vp> and <vp>localTimeValue</vp> as dates and times.
* Show the error description for <vp>hResult</vp> values.
* Watch Window improvement
* Copying the entire debug tree to the clipboard
* Improve memory view for 64bit and break points handling

== Others ==

* win32.lib + win32.x64.lib updated to '''Windows Software Development Kit (SDK) for Windows 8'''
* PFC, VPI, IDE: Help button in the title bar
* SolutionManager. A utility for better handling of a collection of projects
* VipBuilder: Add /platform option for target machine
* VPI: Support DDE in SDI application

== Updates ==

=== Build 7402 ===

Important bug fixes:

*Compiler. Incorrect handling of some special floating-point constants leads to unexpected compile time errors (see [http://discuss.visual-prolog.com/viewtopic.php?t=9582 Real value 1.#INF is out of the range]).
*Compiler. Missing warning for unreachable codes (see [http://discuss.visual-prolog.com/viewtopic.php?t=9569 Unused Variable]).
*Compiler. [http://discuss.visual-prolog.com/viewtopic.php?t=9502 Ambiguity in wedBrowserControl].
*Compiler. Codes generation bug for string comparisson (it can lead to access violation exception at runtime in some cases).
*Compiler. Nested '''if-then-else''' expressions can raise unexpected error messages related to the wrong flow patterns.
*Compiler. Unexpected error message for supported interface and inherited class conflict for a generic scope.
*Compiler. No error if constructor is absent for an object class with ''noDefaultConstructor'' attribute.
*Compiler. Incorrect warning c231 (scope is opened but not used) in some cases.
*Compiler. Code generation bug for nested '''finally''' statements with cuts in '''try''' part (this could could lead to exceptions at runtime in some cases).
*Compiler. Code generation bug for read-only property implemented by a clause with several heads.
*Compiler. Anonymous predicates in both ''xxx'' as function and ''xxx'' as predicate give declaration conflict.
*Compiler. Incorrect object file if number of fixups exceeds the limit of oxFFFF (this could lead to the incorrect state of some statically initialized data, like class facts, etc.).
*Compiler. Several bugs in 64bit codes generation.

+ Some minor bug fixes

=== Build 7401 ===

The following new feature has been implemented:

* if-the-else expressions
* Condition in if-statement/expression can be <vp>nondeterm</vp>/<vp>multi</vp>
* <vp>thiscall</vp> calling convention

Important bug fixes:

* ChainDB, 64bit: Problems when storing terms in a chain if "in_memory" is used See [http://discuss.visual-prolog.com/viewtopic.php?t=9390 External Databases in V7.4 in 64bits]
* PFC: [http://discuss.visual-prolog.com/viewtopic.php?t=9377 Problem with console::setLocation in vip 7.4]
* VPI: Incorrect behavior of getText/1->
* [http://discuss.visual-prolog.com/viewtopic.php?t=9421 Header prints in chinese!?!]

+ Some minor bug fixes

== See also ==

* [[Visual Prolog 7.4 Upgrade Notes]]

[[Category:Release Notes]]

Visual Prolog 7.4 New Features

2013-06-04T04:12:17Z

Alexander Doronin: /* Build 7402 */

== Language ==

=== 64 bit programs ===

The main new feature in Visual Prolog 7.4 is the ability to generate 64 bit programs (Commercial Edition only), making it possible to write programs that exploit more of the computers resources.

'''Notice''' to ensure source code compatability between 32 and 64 bit programs a number of types have been changed and it is necessary to update the programs, see [[Visual Prolog 7.4 Upgrade Notes]].

See also [[64 bit Windows]]

=== Program Point ===

Support for exceptions handling improvement (programPoint type and attribute, implicit programPoint argument). See also [[Language Reference/Predicates#programPoint|programPoint]].

=== Syntax & Warnings ===

* Better handling of comma (,) before then, elseif, else, end if, do and end foreach
* Error c550 for inlining a field from a null pointer
* Warning c647 if bound/1 is applied to a variable which is always free
* Warning if scope is only opened but is not actually used (unused open for class core is ignored). Removing such excessive open-directives makes the Optimal Includes more effective. This warning is switched off by the default (option /w:231 turns it on).

== PFC ==

PFC have been updated to be 64 bit compatible. A few packages have not been updated, but have instead been deprecated and replaced by new packages.

* <vp>vpiEditor</vp> is deprecated (replaced by <vp>sciLexer</vp> editor)
* <vp>regExp</vp> is deprecated (replaced by <vp>regEx</vp>)

=== PFC/GUI ===

* <vp>sciLexer</vp> New editor control based on the [http://www.scintilla.org/ Scintilla] editor with lexers (including Visual Prolog lexer).
* <vp>webBrowser</vp> New control control comprehensive wrapping of the Internet Explorer WebBrowserControl
* Improved clipboard handling (with HTML support)
* <vp>ribbonControl</vp> and command system and controlSerialization; with a run-time visual designer that simplifies the process of making ribbons
* <vp>toolboxControl</vp> New control
* <vp>headerControl</vp> New control
* <vp>rebar</vp> + <vp>statusBar</vp> New packages
* <vp>shellNotificationIcon</vp> for handing notifications in the shells notification area + Demo
* <vp>toolTip</vp> New package and toolTip functionality on standard controls + Demo
* <vp>splitControl</vp> New control for multi-split management; with a run-time visual designer that simplifies the process of making splits
* <vp>splitterControl</vp> New control for the split in windows
* <vp>dragNdrop</vp> New class for (in-program) drag and drop functionality + Demo
* Object oriented GDI support
* Object oriented GDI+ support for
** <vp>bitmap</vp>
** <vp>brush</vp>
** <vp>font</vp>
** <vp>palette</vp>
** <vp>pen</vp>
** <vp>deviceContext</vp>
** <vp>icon</vp>
* <vp>gui_native::createDialogIndirectParam</vp> Update for font handling
* <vp>window::listenUntilDestroy</vp> New predicate for listening to an event, but detach the listening when the window is destroyed
* <vp>messageLoop</vp> for SDI applications

=== PFC (non-GUI) ===

* <vp>regEx</vp> package based on [www.boost.org/libs/regex boost regular expression library]
* <vp>mapM_hash</vp> & <vp>setM_hash</vp> New classes for hash table implementations of maps and sets
* <vp>arrayM</vp> uses pointer to memory instead of binary: makes it possible to interpret non-binaries as arrays and is more efficient
* <vp>arrayM_inline</vp> New class for interpretation of C/C++ struct arrays
* <vp>arrayM_boolean</vp> New class for compact boolean arrays (1 bit per boolean).
* <vp>array2M</vp> New class for 2 dimensional arrays
* <vp>socket</vp> New class for object oriented WinSock2 support
* <vp>event0</vp> - <vp>event7</vp> New classes for general/generic event handling (notify+listener)
* <vp>iStream_stream</vp> class for mapping a Visual Prolog stream as an IStream com object (CE-only)
* improved '''ISAPI''' support
* <vp>json</vp> (pfc/web/json) and <vp>jsonRpc</vp> New packages for JSON and JSON RPC 2.0 support (CE-only)
* memory allocate functions with argument for atomic/non-atomic
* ODBC auto parameter binding get the size from the database by means of SQLDescribeParam
* <vp>shell_api::sHCreateStreamOnFileEx</vp> new predicate for creating an IStream com object from a file
* <vp>xhtmlWriter</vp> class for writing xhtml/xhtml5 using an <vp>xmlWriter</vp>
* <vp>xmlReader</vp> & <vp>xmlWriter</vp> based on the xmlLite API (CE-only) + Demo
* <vp>internetExplorer</vp> class for automating an out-of-process Internet Explorer

== IDE ==

* New simplified settings dialog
* Add "No To All" button to the dialog for removing file from a project
* Create empty clause if there is compiler error for absent clause for a predicate
* Global unreachability support
* History of Run Arguments
* Improved Browse View
* Improved the manifest handling
* Load browse info in a separate thread (performance optimization)
* SDI applications support
* Tools entries in project-tree popup menu

== Debugger ==

* Soft/hard breakpoints
* Add current class facts into the variable window
* Show class facts in the Variable Window for a class predicate
* Give names to objects
* Show <vp>gmtTimeValue</vp> and <vp>localTimeValue</vp> as dates and times.
* Show the error description for <vp>hResult</vp> values.
* Watch Window improvement
* Copying the entire debug tree to the clipboard
* Improve memory view for 64bit and break points handling

== Others ==

* win32.lib + win32.x64.lib updated to '''Windows Software Development Kit (SDK) for Windows 8'''
* PFC, VPI, IDE: Help button in the title bar
* SolutionManager. A utility for better handling of a collection of projects
* VipBuilder: Add /platform option for target machine
* VPI: Support DDE in SDI application

== Updates ==

=== Build 7402 ===

Important bug fixes:

*Compiler. Incorrect handling of some special floating-point constants leads to unexpected compile time errors (see [http://discuss.visual-prolog.com/viewtopic.php?t=9582]).
*Compiler. Missing warning for unreachable codes (see [http://discuss.visual-prolog.com/viewtopic.php?t=9569]).
*Compiler. Ambiguity in wedBrowserControl (see [http://discuss.visual-prolog.com/viewtopic.php?t=9502]).
*Compiler. Codes generation bug for string comparisson (it can lead to access violation exception at runtime in some cases).
*Compiler. Nested '''if-then-else''' expressions can raise unexpected error messages related to the wrong flow patterns.
*Compiler. Unexpected error message for supported interface and inherited class conflict for a generic scope.
*Compiler. No error if constructor is absent for an object class with ''noDefaultConstructor'' attribute.
*Compiler. Incorrect warning c231 (scope is opened but not used) in some cases.
*Compiler. Code generation bug for nested '''finally''' statements with cuts in '''try''' part (this could could lead to exceptions at runtime in some cases).
*Compiler. Code generation bug for read-only property implemented by a clause with several heads.
*Compiler. Anonymous predicates in both ''xxx'' as function and ''xxx'' as predicate give declaration conflict.
*Compiler. Incorrect object file if number of fixups exceeds the limit of oxFFFF (this could lead to the incorrect state of some statically initialized data, like class facts, etc.).
*Compiler. Several bugs in 64bit codes generation.

+ Some minor bug fixes

=== Build 7401 ===

The following new feature has been implemented:

* if-the-else expressions
* Condition in if-statement/expression can be <vp>nondeterm</vp>/<vp>multi</vp>
* <vp>thiscall</vp> calling convention

Important bug fixes:

* ChainDB, 64bit: Problems when storing terms in a chain if "in_memory" is used See [http://discuss.visual-prolog.com/viewtopic.php?t=9390 External Databases in V7.4 in 64bits]
* PFC: [http://discuss.visual-prolog.com/viewtopic.php?t=9377 Problem with console::setLocation in vip 7.4]
* VPI: Incorrect behavior of getText/1->
* [http://discuss.visual-prolog.com/viewtopic.php?t=9421 Header prints in chinese!?!]

+ Some minor bug fixes

== See also ==

* [[Visual Prolog 7.4 Upgrade Notes]]

[[Category:Release Notes]]

Language Reference/Domains

2012-12-19T08:16:48Z

Alexander Doronin: /* Calling Convention */

{{languageReferenceNavbar|Domains}}

=== Domains Sections ===

A domain section defines a set of domains in the current scope (see {{lang|Interfaces|Interface}}, {{lang|Classes|Class Declaration}}, and {{lang|Implementations|Class Implementation}}).

<vipbnf><DomainsSection>:
domains <DomainDefinition>-dot-term-list-opt</vipbnf>

=== Domain Definitions ===

A domain definition defines a named domain in the current scope.

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression></vipbnf>

If the domain on the right hand side denotes an interface or a compound domain, then the defined domain is synonym (i.e. identical) to the type expression. Otherwise the defined domain becomes a subtype of the domain denoted by the type expression. Here a domain name <vpbnf><DomainName></vpbnf> should be a {{lang2|Lexical_Elements|Identifiers|lower case identifier}}.

There are certain places where you must use a domain name rather than a type expression:

*as a declaration of a formal argument type;
*as a type of a constant or a fact variable;
*as a type in a list domain.

=== Type Expressions ===

A type expression denotes a type.

<vipbnf><TypeExpression>:
<TypeName>
<CompoundDomain>
<ListDomain>
<PredicateDomain>
<IntegralDomain>
<RealDomain>
<TypeVariable>
<ScopeTypeVariable>
<TypeApplication></vipbnf>

==== Type Names ====

A type name is either an ''interface'' name or the name of a ''value domain''. We use the term ''value domain'' to specify domains whose elements are {{lang2|Basic_Concepts|Types|immutable}} (unchangeable). Here we can say that objects, belonging to domains correspondent to ''interface'' names, have mutable state and terms of any other domains are immutable. So actually value types are everything except object types. A type name (obviously) denotes the type corresponding to the name of an existing domain.

<vipbnf><TypeName>:
<InterfaceName>
<DomainName>
<ClassQualifiedDomainName></vipbnf>

<vipbnf><InterfaceName>:
<LowercaseIdentifier></vipbnf>

<vipbnf><DomainName>:
<LowercaseIdentifier></vipbnf>

<vipbnf><ClassQualifiedDomainName>:
<ClassName>::<DomainName></vipbnf>

<vipbnf><ClassName>:
<LowercaseIdentifier></vipbnf>

Here <vpbnf><InterfaceName></vpbnf> is an interface name, <vpbnf><DomainName></vpbnf> is a value domain name, and <vpbnf><ClassName></vpbnf> is a class name.

{{Example|
<vip>domains
newDomain1 = existingDomain.
newDomain2 = myInterface.</vip>

In this example the domain name <vp>existingDomain</vp> and the interface name <vp>myInterface</vp> are used to define new domains.
}}

==== Compound Domains ====

Compound domains (also known as algebraic data types) are used to represent lists, trees, and other tree structured values. In its simple forms compound domains are used to represent structures and enumeration values. Compound domains can have a recursive definition. They can also be mutually/indirectly recursive.

<vipbnf><CompoundDomain>:
<Alignment>-opt <FunctorAlternative>-semicolon-sep-list</vipbnf>

<vipbnf><Alignment>:
align <IntegralConstantExpression></vipbnf>

Here <vpbnf><IntegralConstantExpression></vpbnf> is an expression, which must be compile time evaluated to an integral value.

A compound domain declaration declares a list of functor alternatives with optional alignment. Alignment must be <vp>1</vp>, <vp>2</vp> or <vp>4</vp>.

If a compound domain consists of one functor alternative, then it is considered as structure and has representation, which is binary compatible with the appropriate structure in language C.

<vipbnf><FunctorAlternative>:
<FunctorName> <FunctorName> ( <FormalArgument>-comma-sep-list-opt )</vipbnf>

Here <vpbnf><FunctorName></vpbnf> is the name of a functor alternative it should be a {{lang2|Lexical_Elements|Identifiers|lower case identifier}}.

<vipbnf><FormalArgument>:
<TypeExpression> <ArgumentName>-opt</vipbnf>

Here <vpbnf><ArgumentName></vpbnf> can be any {{lang2|Lexical_Elements|Identifiers|upper case identifier}}. The compiler ignores it.

Compound domains have no subtype relations to any other domains.

If a domain is defined as being equal to a compound domain, then these two domains are synonym types rather than subtypes. Meaning that they are just two different names for the same type.

{{Example|
<vip>domains
t1 = ff(); gg(integer, t1).</vip>

<vp>t1</vp> is a compound domain with two alternatives. The first alternative is the null-ary functor <vp>ff</vp>, while the second alternative is the two-ary functor <vp>gg</vp>, which takes an {{lang2|Built-in_entities|integer|integer}} and a term of the domain <vp>t1</vp> itself as arguments. So the domain <vp>t1</vp> is recursively defined.

The following expressions are terms of the domain <vp>t1</vp>:

<vip>ff()
gg(77, ff())
gg(33, gg(44, gg(55, ff())))</vip>
}}

{{Example|
<vip>domains
t1 = ff(); gg(t2).
t2 = hh(t1, t1).</vip>

<vp>t1</vp> is a compound domain with two alternatives. The first alternative is the null-ary functor <vp>ff</vp>, while the second alternative is the unary functor <vp>gg</vp>, which takes a term of the domain <vp>t2</vp> as argument. <vp>t2</vp> is a compound domain with one alternative the functor <vp>hh</vp>, which takes two <vp>t1</vp> terms as argument. So the domains <vp>t1</vp> and <vp>t2</vp> are mutually recursive.

The following are terms in the domain <vp>t1</vp>:

<vip>ff()
gg(hh(ff(), ff()))
gg(hh(gg(hh(ff(), ff())), ff()))
ggg(hh(ff(), g(hh(ff(), ff()))))
gg(hh(gg(hh(ff(), ff())), gg(hh(ff(), ff()))))</vip>
}}

{{Example|

In this example <vp>t1</vp> and <vp>t2</vp> are synonym types.

<vip>domains
t1 = f(); g(integer).
t2 = t1.</vip>
}}

Normally, it is not necessary to use empty parenthesis after null-ary functors. But in a domain definition consisting only of a single null-ary functor, empty parenthesis are required to distinguish it from a synonym/subtype definition.

{{Example|
<vp>t1</vp> is a compound domain with a single null-ary functor, whereas <vp>t2</vp> is defined to be synonym to <vp>t1</vp>.

<vip>domains
t1 = f().
t2 = t1.</vip>
}}

==== List Domains ====

List domains represent sequences of values of a certain domain. Thus, all elements in a <vp>T</vp> list must be of type <vp>T</vp>.

<vipbnf><ListDomain>:
<TypeName> *</vipbnf>

<vp>T*</vp> is the type of lists of <vp>T</vp> elements.

The following syntax is used for lists:

<vipbnf><ListExpression>:
[ <Term>-comma-sep-list-opt ]
[ <Term>-comma-sep-list | <Tail> ]</vipbnf>

<vipbnf><Tail>:
<Term></vipbnf>

Here <vpbnf><Tail></vpbnf> is a term which should have a value of the <vpbnf><ListDomain></vpbnf> type. Each <vpbnf><Term></vpbnf> should be of {{lang2|Domains|Type_Names|typeName}} type.

Actually, lists are just compound domains with two functors: <vp>[]</vp> denoting the empty list and the mix-fix functor <vp>[HD|TL]</vp> denoting the list with head <vp>HD</vp> and tail <vp>TL</vp>. The head must be of the underlying element type, whereas the tail must be a list of relevant type.

Lists are however syntactically sugared.

<vp>[E1, E2, E3, ..., En | L ]</vp> is shorthand for <vp>[E1 |[ E2 |[ ...[ En | L ]...}}]</vp>

<vp>[E1, E2, E3, ..., En]</vp> is shorthand for <vp>[E1, E2, E3, ..., En |[}}</vp>, which in turn is shorthand for <vp>[E1 |[ E2 |[ ...[ En | [] ]...}}]</vp>

==== Predicate Domains ====

Values of a predicate domain are predicates with the same "signature", i.e. the same argument and return types, the same flow pattern and the same (or stronger) predicate mode.

A predicate that returns a value is called a '''''function''''', whereas a predicate that does not return a value is sometimes called an '''''ordinary''''' predicate, to stress that it is not a function.

<vipbnf><PredicateDomain>:
( <FormalArgument>-comma-sep-list-opt ) <ReturnArgument>-opt
<PredicateModeAndFlow>-list-opt <CallingConvention>-opt</vipbnf>

<vipbnf><FormalArgument>:
<PredicateArgumentType> <VariableName>-opt
<Ellipsis></vipbnf>

<vipbnf><ReturnArgument>:
-> <FormalArgument></vipbnf>

<vipbnf><PredicateArgumentType>:
<TypeName>
<AnonymousIdentifier></vipbnf>

<vipbnf><VariableName>:
<UpperCaseIdentifier></vipbnf>

Predicate domains can have <vpbnf><Ellipsis></vpbnf> argument as the last <vpbnf><FormalArgument></vpbnf> in the <vpbnf><FormalArgument>-comma-sep-list</vpbnf>.

Predicate domains can have <vpbnf><AnonymousIdentifier></vpbnf> as a {{lang2|Domains|Type_Expressions|predicateArgumentType}} to specify that the argument can be of any type.

Currently, predicate domains with ellipsis can only be used in predicate declarations.

Predicate domains that are used in domain definitions can at most state one flow.

<vipbnf><PredicateModeAndFlow>:
<PredicateMode>-opt
<FlowPattern>-list-opt</vipbnf>

===== Predicate Mode =====

The specified predicate mode applies for each member of a flow pattern list following it.

<vipbnf><PredicateMode>: one of
erroneous
failure
procedure
determ
multi
nondeterm</vipbnf>

Predicate modes can be described by the following sets:

<vip>erroneous = {}
failure = {Fail}
procedure = {Succeed}
determ = {Fail, Succeed}
multi = {Succeed, BacktrackPoint}
nondeterm = {Fail, Succeed, BacktrackPoint}</vip>

If ''Fail'' is in the set it means that the predicate can fail. If ''succeed'' is in the set it means that the predicate can succeed. If ''BacktrackPoint'' is in the set it means that the predicate can return with an active backtrack point in it.

If such a set, say <vp>failure</vp>, is a subset of another set, say <vp>nondeterm</vp>, then we say that the mode is stronger than the other, i.e. <vp>failure</vp> is stronger than <vp>nondeterm</vp>.

A predicate domain actually contain all predicates (with correct type and flow), which have the mode specified or a '''''stronger''''' mode.

It is illegal to state a predicate mode for constructors, they always have the <vp>procedure</vp> mode.

Omitting of a predicate mode means <vp>procedure</vp>.

Omitting of flows means that all arguments are input.

Notice that, in difference to Visual Prolog v. 5.x, inside implementations (i.e. for a local predicates) the needed flows and modes '''are NOT derived from the usages of the predicate'''. Now in declarations of for local predicates omitting the predicate mode means <vp>procedure</vp> and omitting flows means that all arguments are input.

If inside an implementation you do not want to specify all possible flows of a predicate usage explicitly, you still can deliver this duty to the compiler. For this task inside class implementations you can use the special flow pattern <vp>anyflow</vp>. In this case the compiler during the compilation will derive the needed flows from usages of the predicate. But if the optional preceding predicate mode is omitted before the <vp>anyflow</vp> flow pattern, then the <vp>procedure mode</vp> is always assumed.

===== Flow Pattern =====

The flow pattern defines the input/output direction of the arguments, which in combination with functor domains can be structures with parts of a single argument being input and other parts of the same argument being output.

A flow pattern consists of a sequence of flows, each flow corresponds to an argument (fist flow to first argument, etc).

<vipbnf><FlowPattern>:
( <Flow>-comma-sep-list-opt ) AnyFlow</vipbnf>

<vipbnf><Flow>: one of
i
o
<FunctorFlow>
<ListFlow>
<Ellipsis></vipbnf>

Ellipsis flow must match an ellipsis argument and can therefore be only the last flow in the flow pattern.

<vipbnf><Ellipsis>:
...</vipbnf>

A functor flow <vpbnf><FunctorFlow></vpbnf> states a functor and flows of each of the components of that flow. The functor must of course be in the domain of the corresponding argument.

<vipbnf><FunctorFlow>:
<FunctorName> ( <Flow>-comma-sep-list-opt )</vipbnf>

A functor flow declaration cannot contain ellipsis flow.

List flows are just like functor flows, but with the same syntactic sugaring as the list domain.

<vipbnf><ListFlow>:
[ <Flow>-comma-sep-list-opt <ListFlowTail>-opt]</vipbnf>

<vipbnf><ListFlowTail>:
| <Flow></vipbnf>

A list flow cannot contain ellipsis flow.

When declaring a predicate the flow can be omitted. Inside an implementation (i.e. for a local predicate) the needed flows are derived from the usages of the predicate. Inside an interface or a class declaration (i.e. for a public predicate) omitting flows means that all arguments are input.

Special flow pattern <vp>anyflow</vp> can be stated only in declarations of local predicates (i.e. in predicate declarations inside the implementation of a class). It means that the exact flow pattern will be evaluated during the compilation. If the optional preceding predicate mode is omitted for this flow pattern, then it assumes to be a <vp>procedure</vp>.

{{Example|
<vip>domains
pp1 = (integer Argument1).</vip>

<vp>pp1</vp> is a predicate domain. The predicates that have type <vp>pp1</vp> takes one {{lang2|Built-in_entities|integer|integer}} argument. Since no flow-pattern is stated the argument is input, and since no predicate mode is mentioned the predicates are <vp>procedure</vp>.
}}

{{Example|
<vip>domains
pp2 = (integer Argument1) -> integer ReturnType.</vip>

Predicates of type <vp>pp2</vp> take one {{lang2|Built-in_entities|integer|integer}} argument and returns a value of type {{lang2|Built-in_entities|integer|integer}}. Therefore, <vp>pp2</vp> is actually a function domain and the predicates that have type <vp>pp2</vp> are actually functions. Since no flow-pattern is stated the argument is input and since no predicate mode is mentioned the predicates are <vp>procedure</vp>.
}}

{{Example|
<vip>predicates
ppp : (integer Argument1, integer Argument2) determ (o,i) (i,o) nondeterm (o,o).</vip>

The predicate <vp>ppp</vp> takes two {{lang2|Built-in_entities|integer|integer}} arguments. It exists in three flow variants: <vp>(o,i)</vp> and <vp>(i,o)</vp>, which are <vp>determ</vp>, and <vp>(o,o)</vp>, which is <vp>nondeterm</vp>.
}}

===== Calling Convention =====

The calling convention determines how arguments, etc. are passed to the predicate, it also determines how the link name is derived from a predicate name.

<vipbnf><CallingConvention>:
language <CallingConventionKind></vipbnf>

<vipbnf><CallingConventionKind>: one of
c thiscall stdcall apicall prolog</vipbnf>

If a calling convention is not stated, then the <vp>prolog</vp> convention is assumed. The <vp>prolog</vp> calling convention is the standard convention used for Prolog predicates.

The calling convention <vp>c</vp> follows the C/C++ standard calling convention. The link name of a predicate is created from the predicate name by adding a leading underscore (<vp>_</vp>).

The calling convention <vp>thiscall</vp> follows the C++ standard calling convention for virtual functions. This calling convention uses the <vp>c</vp> link name strategy but sometimes it may use the different argument and stack handling rules. Calling convention <vp>thiscall</vp> can be applied to the object predicates only.

The calling convention <vp>stdcall</vp> uses the <vp>c</vp> link name strategy but it uses the different argument and stack handling rules. The following table shows the implementation of <vp>stdcall</vp> calling convention:

{|{{prettytable}}
|-
!Feature
!Implementation
|-
|Argument-passing order
|Right to left.
|-
|Argument-passing convention
|By value, unless a compound domain term is passed. So it cannot be used to predicates with variable number of arguments.
|-
|Stack-maintenance responsibility
|Called predicate pops its own arguments from the stack.
|-
|Name-decoration convention
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|Case-translation convention
|No case translation of the predicate name is performed.
|}

The calling convention <vp>apicall</vp> uses the same argument and stack handling rules as <vp>stdcall</vp>, but for convenience to call MS Windows API functions <vp>apicall</vp> uses the naming conventions that are used by most MS Windows API functions. According to <vp>apicall</vp> naming conventions the link name of a predicate is constructed as follows:

*an leading underscore (<vp>_</vp>) is prefixed to the predicate name;
*the predicate name in which the first letter is changed in to a capital letter;
*the '<vp>A</vp>', the '<vp>W</vp>' or nothing is suffixed, if the arguments and the return type indicate an ANSI, Unicode or neutral predicate, respectively;
*the '<vp>@</vp>' is suffixed;
*the number of bytes pushed on the call stack is suffixed.

{{Example|
<vip>predicates
predicateName : (integer, string) language apicall</vip>

The argument types of this predicate indicates that it is a Unicode predicate (as {{lang2|Built-in_entities|string|string}} is the domain of Unicode strings). An {{lang2|Built-in_entities|integer|integer}} and a {{lang2|Built-in_entities|string|string}} each occupies 4 bytes on the call stack and, therefore, the link name becomes:

<source lang="text">_PredicateNameW@8</source>
}}

If <vp>apicall</vp> is used together with the "<vp>as</vp>" construction the name stated in the "<vp>as</vp>" construction is decorated in the same manner.

<vp>apicall</vp> can only be used directly in a predicate declaration, not in a predicate domain definition. In predicate domain definitions <vp>stdcall</vp>, must be used instead. A predicate declared with <vp>apicall</vp> calling convention cannot have clauses and it also cannot be resolved externally without explicit DLL name.

The following table compares implementations of <vp>c</vp>, <vp>apicall</vp>, and <vp>stdcall</vp> calling conventions (the <vp>prolog</vp> calling convention has the special implementation, which is not discussed here):

{|{{prettytable}}
|-
!Keyword
!Stack cleanup
!Predicate name case-translation
!Link predicate name decoration convention
|-
|<vp>c</vp>
|'''Calling''' predicate pops the arguments from the stack.
|None.
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|<vp>thiscall</vp>
|'''Calling''' predicate pops the arguments from the stack except the implicit '''This''' argument which is passed in the register.
|None.
|<vp>c</vp> link name strategy is used.
|-
|<vp>stdcall</vp>
|'''Called''' predicate pops its own arguments from the stack.
|None.
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|<vp>apicall</vp>
|'''Called''' predicate pops its own arguments from the stack.
|The first letter of the predicate name is changed to the capital letter.
|An underscore (<vp>_</vp>) is prefixed to the name. The first letter is changed to the upper case. The '<vp>A</vp>', the '<vp>W</vp>' or nothing is suffixed. The sign <vp>@</vp> is suffixed. The (decimal) number of bytes in the argument list is suffixed.
|}

Visual Prolog notion of predicate domains covers both class and object members. Class members are handled straight forward, but the handling of object members requires attention. The invocation of an object predicate will get "back" in the context of the object to which the member belongs.

{{Example| Assume the following declarations:

<vip>interface actionEventSource
domains
actionListener = (actionEventSource Source) procedure (i).
predicates
addActionListener : (actionListener Listener) procedure (i).
... end interface</vip>

Also assume a class <vp>button_class</vp> which supports the <vp>actionEventSource</vp>. The event is sent when the button is pressed. In <vp>myDialog_class</vp> class, which implements a dialog, I create a button and I want to listen to its action events, so that I can react on button presses:

<vip>implement myDialog_class
clauses
new() :-
OkButton = button_class::new(...),
OkButton:addActionListener(onOk),
...
facts
okPressed : () determ.
predicates
onOk : actionListener.
clauses
onOk(Source) :-
assert(okPressed()).
end implement</vip>

The important thing about the example is that <vp>onOk</vp> is an object member and that, when the button is pressed, the invocation of the registered <vp>onOk</vp> will bring us back in the object that owns <vp>onOk</vp>. This means that we have access to the object fact <vp>okPressed</vp>, so that we can assert it.
}}

===== Format Strings =====

A formal parameter to a predicate can be marked as format string using the attribute {{lang2|Attributes|formatString|formatString}}. The format string can contain ordinary characters which are printed without modification, and format fields, that % begins with the percent '%' sign. If the percent sign is followed % by some unknown character (not the format specifier) - then % this character will be printed without modifications.

<vip>predicates
writef : (string Format [formatstring], ...).</vip>

The format fields specification is:

[-][0][width][.precision][type]

All fields are optional.

[-] Hyphen indicates that the field is to be left justified; right justified is the default. Having no effect when width value is not set, or the number of characters in the actual value is greater than width value.

[0] Zero before width means for values that zeros will be added until the minimum width is reached. If 0(zero) and -(hyphen) appear, the 0 is ignored

[width] Positive decimal number specifying a minimum field size. If the number of characters in the actual value is less than width value - then the required number of space ' ' characters will be added before the value (or after it, if '-' field was set). No changes occurs if number of characters in the actual value is greater than the width value.

[.precision] The point '.' with the following unsigned decimal number can specify either the precision of a floating-point image or the maximum number of characters to be printed from a string.

[type] Specifies other format then the default for the given. For example, in the type field, you can give a specifier that says an integer will be formatted as an unsigned. The possible values are:

:{|{{prettytable}}
|-
| f || Format real's in fixed-decimal notation (such as 123.4 or 0.004321). This is the default for real's.
|-
| e || Format real's in exponential notation (such as 1.234e+002 or 4.321e-003).
|-
| g || Format real's in the shortest of f and e format, but always in e format if exponent of the value is less than -4 or greater than or equal to the precision. Trailing zeros are truncated.
|-
| d or D || Format as a signed decimal number.
|-
| u or U || Format as an unsigned integer.
|-
| x or X || Format as a hexadecimal number.
|-
| o or O || Format as an octal number.
|-
| c || Format as a char.
|-
| B || Format as the Visual Prolog binary type.
|-
| R || Format as a database reference number.
|-
| P || Format as a procedure parameter.
|-
| s || Format as a string.
|}

==== Integral Domains ====

Integral domains are used for representing integral numbers. They are divided in two main categories for signed and unsigned numbers. Integral domains can also have different representation size. The predefined domains {{lang2|Built-in_entities|integer|integer}} and {{lang2|Built-in_entities|unsigned|unsigned}} represent signed and unsigned numbers with natural representation length for the processor architecture (i.e. 32bit on a 32bit machine, etc).

<vipbnf><IntegralDomain>:
<DomainName>-opt <IntegralDomainProperties></vipbnf>

If a <vpbnf><DomainName></vpbnf> is stated in front of the <vpbnf><IntegralDomainProperties></vpbnf>, then this domain must itself be an integral domain and the resulting domain will be child-type (i.e. subtype) of this domain. In that case <vpbnf><IntegralDomainProperties></vpbnf> may not violate the possibility of being a subtype, i.e. the range cannot be extended and the size cannot be changed.

<vipbnf><IntegralDomainProperties>:
<IntegralSizeDescription> <IntegralRangeDescription>-opt
<IntegralRangeDescription> <IntegralSizeDescription>-opt

<IntegralSizeDescription>:
bitsize <DomainSize>

<DomainSize>:
<IntegralConstantExpression></vipbnf>

An integral size description declares the size <vpbnf><DomainSize></vpbnf> of the integral domain, measured in bits. The compiler implement such representation to the integral domain, which has no less than the specified number of bits. The value of <vpbnf><DomainSize></vpbnf> should be positive and no greater than the maximal value supported by the compiler.

If integral size description is omitted, then it will become the same as the parent domain. If there is no parent domain, it will become the natural size for the processor.

<vipbnf><IntegralRangeDescription>:
[ <MinimalBoundary>-opt .. <MaximalBoundary>-opt ]

<MinimalBoundary>:
<IntegralConstantExpression>

<MaximalBoundary>:
<IntegralConstantExpression></vipbnf>

An integral range description declares the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits for the integral domain. If a limit is omitted, then the range of the parent domain is used. If there is no parent domain, then the <vpbnf><DomainSize></vpbnf> is used to determine respectively maximum or minimum value.

Notice that the specified minimum value should not exceed the specified maximum value. That is:

<vipbnf><MinimalBoundary> <= <MaximalBoundary></vipbnf>

Also the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits should satisfy the limits implied by the specified bit size <vp>bitsize</vp>.

The domain bit size <vpbnf><DomainSize></vpbnf> value and values of the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits must be calculated while compiling time.

==== Real Domains ====

Real domains are used to represent numbers with fractional parts (i.e. floating point numbers). Real domains can be used to represent very large and very small numbers. The built-in domain ''real'' have the natural precision for the processor architecture (or the precision given by the compiler).

<vipbnf><RealDomain>:
<DomainName>-opt <RealDomainProperties></vipbnf>

If a <vpbnf><DomainName></vpbnf> is stated in front of the <vpbnf><RealDomainProperties></vpbnf>, then this domain must itself be a real domain and the resulting domain will be a subtype of this domain. In that case <vpbnf><RealDomainProperties></vpbnf> may not violate the possibility of being a subtype, i.e. the range cannot be extended and the precision cannot be increased.

<vipbnf><RealDomainProperties>: one of
<RealPrecisionDescription> <RealRangeDescription>-opt
<RealRangeDescription> <RealPrecisionDescription></vipbnf>

<vipbnf><RealPrecisionDescription>:
digits <IntegralConstantExpression></vipbnf>

The real precision description declares precision of the real domain, measured in number of decimal digits. If precision is omitted then it will become the same as for the parent domain. If there is no parent domain, then it will be the natural precision for the processor or given by the compiler (in Visual Prolog v.6 the compiler limit is 15 digits). Precision have an upper and a lower limits given by the compiler, if the precisions larger than that limit is used the numbers will only obtain the processor (compiler) specified precision anyway.

<vipbnf><RealRangeDescription>:
[ <MinimalRealBoundary>-opt .. <MaximalRealBoundary>-opt ]

<MinimalRealBoundary>:
<RealConstantExpression>

<MaximalRealBoundary>:
<RealConstantExpression></vipbnf>

Here <vpbnf><RealConstantExpression></vpbnf> is an expression, which must be compile time evaluated to a floating point value. That is the real domain precision and limits must be calculated while compiling time.

The real range description declares minimal and maximal limits for the real domain. If a limit is omitted then it will be the same as for the parent domain. If there is no parent domain then the largest possible range for the precision will be used.

Notice that the specified minimum value should not exceed the specified maximum value. That is:

<vipbnf><MinimalBoundary> <= <MaximalBoundary></vipbnf>

==== Generic Domains ====

This section contains the formal syntax for generic domains, for a more complete introduction to generics please see the section ''''' Generics'''''.

<vipbnf><FormalTypeParameterList>:
<TypeVariable>-comma-sep-list-opt</vipbnf>

A formalTypeParameterList is a list of typeVariables

<vipbnf><TypeVariable>:
<UpperCaseIdentifier></vipbnf>

A <vpbnf><TypeVariable></vpbnf> is an upper case identifier. In a domain declaration the type variable must be bound in the <vpbnf><FormalTypeParameterList></vpbnf> on the left hand side of the domain definition. In a predicate declaration all free type variables are implicitly bound and scoped to that predicate declaration.

<vipbnf><TypeApplication>:
<TypeName> {<TypeExpression>-comma-sep-list-opt }</vipbnf>

A <vpbnf><TypeApplication></vpbnf> is the application of a {{lang2|Domains|Type_Names|typeName}} to a list of types. The type name must be generic and the number of formal type parameters must match the number of type expressions.

=== Universal and Root Types ===

Visual Prolog uses some internal types, called ''root'' types and ''universal'' types.

==== Universal Types ====

A number literal like <vp>1</vp> does not have any particular type, it can be used as a value of any type that contains <vp>1</vp>, including real types.

We say that <vp>1</vp> have a universal type. Having a universal type means that it have any type, which can represent its value.

Arithmetic operations also return universal types.

==== Root Types ====

Arithmetic operations are very liberal with their operand requirements: You can add integers of any integer domain with each other.

We say that arithmetic operands takes root types as arguments. The integer root type is super-type of any integer type (regardless that it is not mentioned in their declarations). Hence any integer type can be converted to the integer root type, and, since the arithmetic operations exist for the root types, it means one of them will work on any integer domains.

The actual number of root types and which operands exist is a matter of library facilities, and outside the scope of this document to describe.

Language Reference/Domains

2012-12-19T08:01:57Z

Alexander Doronin: /* Calling Convention */

{{languageReferenceNavbar|Domains}}

=== Domains Sections ===

A domain section defines a set of domains in the current scope (see {{lang|Interfaces|Interface}}, {{lang|Classes|Class Declaration}}, and {{lang|Implementations|Class Implementation}}).

<vipbnf><DomainsSection>:
domains <DomainDefinition>-dot-term-list-opt</vipbnf>

=== Domain Definitions ===

A domain definition defines a named domain in the current scope.

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression></vipbnf>

If the domain on the right hand side denotes an interface or a compound domain, then the defined domain is synonym (i.e. identical) to the type expression. Otherwise the defined domain becomes a subtype of the domain denoted by the type expression. Here a domain name <vpbnf><DomainName></vpbnf> should be a {{lang2|Lexical_Elements|Identifiers|lower case identifier}}.

There are certain places where you must use a domain name rather than a type expression:

*as a declaration of a formal argument type;
*as a type of a constant or a fact variable;
*as a type in a list domain.

=== Type Expressions ===

A type expression denotes a type.

<vipbnf><TypeExpression>:
<TypeName>
<CompoundDomain>
<ListDomain>
<PredicateDomain>
<IntegralDomain>
<RealDomain>
<TypeVariable>
<ScopeTypeVariable>
<TypeApplication></vipbnf>

==== Type Names ====

A type name is either an ''interface'' name or the name of a ''value domain''. We use the term ''value domain'' to specify domains whose elements are {{lang2|Basic_Concepts|Types|immutable}} (unchangeable). Here we can say that objects, belonging to domains correspondent to ''interface'' names, have mutable state and terms of any other domains are immutable. So actually value types are everything except object types. A type name (obviously) denotes the type corresponding to the name of an existing domain.

<vipbnf><TypeName>:
<InterfaceName>
<DomainName>
<ClassQualifiedDomainName></vipbnf>

<vipbnf><InterfaceName>:
<LowercaseIdentifier></vipbnf>

<vipbnf><DomainName>:
<LowercaseIdentifier></vipbnf>

<vipbnf><ClassQualifiedDomainName>:
<ClassName>::<DomainName></vipbnf>

<vipbnf><ClassName>:
<LowercaseIdentifier></vipbnf>

Here <vpbnf><InterfaceName></vpbnf> is an interface name, <vpbnf><DomainName></vpbnf> is a value domain name, and <vpbnf><ClassName></vpbnf> is a class name.

{{Example|
<vip>domains
newDomain1 = existingDomain.
newDomain2 = myInterface.</vip>

In this example the domain name <vp>existingDomain</vp> and the interface name <vp>myInterface</vp> are used to define new domains.
}}

==== Compound Domains ====

Compound domains (also known as algebraic data types) are used to represent lists, trees, and other tree structured values. In its simple forms compound domains are used to represent structures and enumeration values. Compound domains can have a recursive definition. They can also be mutually/indirectly recursive.

<vipbnf><CompoundDomain>:
<Alignment>-opt <FunctorAlternative>-semicolon-sep-list</vipbnf>

<vipbnf><Alignment>:
align <IntegralConstantExpression></vipbnf>

Here <vpbnf><IntegralConstantExpression></vpbnf> is an expression, which must be compile time evaluated to an integral value.

A compound domain declaration declares a list of functor alternatives with optional alignment. Alignment must be <vp>1</vp>, <vp>2</vp> or <vp>4</vp>.

If a compound domain consists of one functor alternative, then it is considered as structure and has representation, which is binary compatible with the appropriate structure in language C.

<vipbnf><FunctorAlternative>:
<FunctorName> <FunctorName> ( <FormalArgument>-comma-sep-list-opt )</vipbnf>

Here <vpbnf><FunctorName></vpbnf> is the name of a functor alternative it should be a {{lang2|Lexical_Elements|Identifiers|lower case identifier}}.

<vipbnf><FormalArgument>:
<TypeExpression> <ArgumentName>-opt</vipbnf>

Here <vpbnf><ArgumentName></vpbnf> can be any {{lang2|Lexical_Elements|Identifiers|upper case identifier}}. The compiler ignores it.

Compound domains have no subtype relations to any other domains.

If a domain is defined as being equal to a compound domain, then these two domains are synonym types rather than subtypes. Meaning that they are just two different names for the same type.

{{Example|
<vip>domains
t1 = ff(); gg(integer, t1).</vip>

<vp>t1</vp> is a compound domain with two alternatives. The first alternative is the null-ary functor <vp>ff</vp>, while the second alternative is the two-ary functor <vp>gg</vp>, which takes an {{lang2|Built-in_entities|integer|integer}} and a term of the domain <vp>t1</vp> itself as arguments. So the domain <vp>t1</vp> is recursively defined.

The following expressions are terms of the domain <vp>t1</vp>:

<vip>ff()
gg(77, ff())
gg(33, gg(44, gg(55, ff())))</vip>
}}

{{Example|
<vip>domains
t1 = ff(); gg(t2).
t2 = hh(t1, t1).</vip>

<vp>t1</vp> is a compound domain with two alternatives. The first alternative is the null-ary functor <vp>ff</vp>, while the second alternative is the unary functor <vp>gg</vp>, which takes a term of the domain <vp>t2</vp> as argument. <vp>t2</vp> is a compound domain with one alternative the functor <vp>hh</vp>, which takes two <vp>t1</vp> terms as argument. So the domains <vp>t1</vp> and <vp>t2</vp> are mutually recursive.

The following are terms in the domain <vp>t1</vp>:

<vip>ff()
gg(hh(ff(), ff()))
gg(hh(gg(hh(ff(), ff())), ff()))
ggg(hh(ff(), g(hh(ff(), ff()))))
gg(hh(gg(hh(ff(), ff())), gg(hh(ff(), ff()))))</vip>
}}

{{Example|

In this example <vp>t1</vp> and <vp>t2</vp> are synonym types.

<vip>domains
t1 = f(); g(integer).
t2 = t1.</vip>
}}

Normally, it is not necessary to use empty parenthesis after null-ary functors. But in a domain definition consisting only of a single null-ary functor, empty parenthesis are required to distinguish it from a synonym/subtype definition.

{{Example|
<vp>t1</vp> is a compound domain with a single null-ary functor, whereas <vp>t2</vp> is defined to be synonym to <vp>t1</vp>.

<vip>domains
t1 = f().
t2 = t1.</vip>
}}

==== List Domains ====

List domains represent sequences of values of a certain domain. Thus, all elements in a <vp>T</vp> list must be of type <vp>T</vp>.

<vipbnf><ListDomain>:
<TypeName> *</vipbnf>

<vp>T*</vp> is the type of lists of <vp>T</vp> elements.

The following syntax is used for lists:

<vipbnf><ListExpression>:
[ <Term>-comma-sep-list-opt ]
[ <Term>-comma-sep-list | <Tail> ]</vipbnf>

<vipbnf><Tail>:
<Term></vipbnf>

Here <vpbnf><Tail></vpbnf> is a term which should have a value of the <vpbnf><ListDomain></vpbnf> type. Each <vpbnf><Term></vpbnf> should be of {{lang2|Domains|Type_Names|typeName}} type.

Actually, lists are just compound domains with two functors: <vp>[]</vp> denoting the empty list and the mix-fix functor <vp>[HD|TL]</vp> denoting the list with head <vp>HD</vp> and tail <vp>TL</vp>. The head must be of the underlying element type, whereas the tail must be a list of relevant type.

Lists are however syntactically sugared.

<vp>[E1, E2, E3, ..., En | L ]</vp> is shorthand for <vp>[E1 |[ E2 |[ ...[ En | L ]...}}]</vp>

<vp>[E1, E2, E3, ..., En]</vp> is shorthand for <vp>[E1, E2, E3, ..., En |[}}</vp>, which in turn is shorthand for <vp>[E1 |[ E2 |[ ...[ En | [] ]...}}]</vp>

==== Predicate Domains ====

Values of a predicate domain are predicates with the same "signature", i.e. the same argument and return types, the same flow pattern and the same (or stronger) predicate mode.

A predicate that returns a value is called a '''''function''''', whereas a predicate that does not return a value is sometimes called an '''''ordinary''''' predicate, to stress that it is not a function.

<vipbnf><PredicateDomain>:
( <FormalArgument>-comma-sep-list-opt ) <ReturnArgument>-opt
<PredicateModeAndFlow>-list-opt <CallingConvention>-opt</vipbnf>

<vipbnf><FormalArgument>:
<PredicateArgumentType> <VariableName>-opt
<Ellipsis></vipbnf>

<vipbnf><ReturnArgument>:
-> <FormalArgument></vipbnf>

<vipbnf><PredicateArgumentType>:
<TypeName>
<AnonymousIdentifier></vipbnf>

<vipbnf><VariableName>:
<UpperCaseIdentifier></vipbnf>

Predicate domains can have <vpbnf><Ellipsis></vpbnf> argument as the last <vpbnf><FormalArgument></vpbnf> in the <vpbnf><FormalArgument>-comma-sep-list</vpbnf>.

Predicate domains can have <vpbnf><AnonymousIdentifier></vpbnf> as a {{lang2|Domains|Type_Expressions|predicateArgumentType}} to specify that the argument can be of any type.

Currently, predicate domains with ellipsis can only be used in predicate declarations.

Predicate domains that are used in domain definitions can at most state one flow.

<vipbnf><PredicateModeAndFlow>:
<PredicateMode>-opt
<FlowPattern>-list-opt</vipbnf>

===== Predicate Mode =====

The specified predicate mode applies for each member of a flow pattern list following it.

<vipbnf><PredicateMode>: one of
erroneous
failure
procedure
determ
multi
nondeterm</vipbnf>

Predicate modes can be described by the following sets:

<vip>erroneous = {}
failure = {Fail}
procedure = {Succeed}
determ = {Fail, Succeed}
multi = {Succeed, BacktrackPoint}
nondeterm = {Fail, Succeed, BacktrackPoint}</vip>

If ''Fail'' is in the set it means that the predicate can fail. If ''succeed'' is in the set it means that the predicate can succeed. If ''BacktrackPoint'' is in the set it means that the predicate can return with an active backtrack point in it.

If such a set, say <vp>failure</vp>, is a subset of another set, say <vp>nondeterm</vp>, then we say that the mode is stronger than the other, i.e. <vp>failure</vp> is stronger than <vp>nondeterm</vp>.

A predicate domain actually contain all predicates (with correct type and flow), which have the mode specified or a '''''stronger''''' mode.

It is illegal to state a predicate mode for constructors, they always have the <vp>procedure</vp> mode.

Omitting of a predicate mode means <vp>procedure</vp>.

Omitting of flows means that all arguments are input.

Notice that, in difference to Visual Prolog v. 5.x, inside implementations (i.e. for a local predicates) the needed flows and modes '''are NOT derived from the usages of the predicate'''. Now in declarations of for local predicates omitting the predicate mode means <vp>procedure</vp> and omitting flows means that all arguments are input.

If inside an implementation you do not want to specify all possible flows of a predicate usage explicitly, you still can deliver this duty to the compiler. For this task inside class implementations you can use the special flow pattern <vp>anyflow</vp>. In this case the compiler during the compilation will derive the needed flows from usages of the predicate. But if the optional preceding predicate mode is omitted before the <vp>anyflow</vp> flow pattern, then the <vp>procedure mode</vp> is always assumed.

===== Flow Pattern =====

The flow pattern defines the input/output direction of the arguments, which in combination with functor domains can be structures with parts of a single argument being input and other parts of the same argument being output.

A flow pattern consists of a sequence of flows, each flow corresponds to an argument (fist flow to first argument, etc).

<vipbnf><FlowPattern>:
( <Flow>-comma-sep-list-opt ) AnyFlow</vipbnf>

<vipbnf><Flow>: one of
i
o
<FunctorFlow>
<ListFlow>
<Ellipsis></vipbnf>

Ellipsis flow must match an ellipsis argument and can therefore be only the last flow in the flow pattern.

<vipbnf><Ellipsis>:
...</vipbnf>

A functor flow <vpbnf><FunctorFlow></vpbnf> states a functor and flows of each of the components of that flow. The functor must of course be in the domain of the corresponding argument.

<vipbnf><FunctorFlow>:
<FunctorName> ( <Flow>-comma-sep-list-opt )</vipbnf>

A functor flow declaration cannot contain ellipsis flow.

List flows are just like functor flows, but with the same syntactic sugaring as the list domain.

<vipbnf><ListFlow>:
[ <Flow>-comma-sep-list-opt <ListFlowTail>-opt]</vipbnf>

<vipbnf><ListFlowTail>:
| <Flow></vipbnf>

A list flow cannot contain ellipsis flow.

When declaring a predicate the flow can be omitted. Inside an implementation (i.e. for a local predicate) the needed flows are derived from the usages of the predicate. Inside an interface or a class declaration (i.e. for a public predicate) omitting flows means that all arguments are input.

Special flow pattern <vp>anyflow</vp> can be stated only in declarations of local predicates (i.e. in predicate declarations inside the implementation of a class). It means that the exact flow pattern will be evaluated during the compilation. If the optional preceding predicate mode is omitted for this flow pattern, then it assumes to be a <vp>procedure</vp>.

{{Example|
<vip>domains
pp1 = (integer Argument1).</vip>

<vp>pp1</vp> is a predicate domain. The predicates that have type <vp>pp1</vp> takes one {{lang2|Built-in_entities|integer|integer}} argument. Since no flow-pattern is stated the argument is input, and since no predicate mode is mentioned the predicates are <vp>procedure</vp>.
}}

{{Example|
<vip>domains
pp2 = (integer Argument1) -> integer ReturnType.</vip>

Predicates of type <vp>pp2</vp> take one {{lang2|Built-in_entities|integer|integer}} argument and returns a value of type {{lang2|Built-in_entities|integer|integer}}. Therefore, <vp>pp2</vp> is actually a function domain and the predicates that have type <vp>pp2</vp> are actually functions. Since no flow-pattern is stated the argument is input and since no predicate mode is mentioned the predicates are <vp>procedure</vp>.
}}

{{Example|
<vip>predicates
ppp : (integer Argument1, integer Argument2) determ (o,i) (i,o) nondeterm (o,o).</vip>

The predicate <vp>ppp</vp> takes two {{lang2|Built-in_entities|integer|integer}} arguments. It exists in three flow variants: <vp>(o,i)</vp> and <vp>(i,o)</vp>, which are <vp>determ</vp>, and <vp>(o,o)</vp>, which is <vp>nondeterm</vp>.
}}

===== Calling Convention =====

The calling convention determines how arguments, etc. are passed to the predicate, it also determines how the link name is derived from a predicate name.

<vipbnf><CallingConvention>:
language <CallingConventionKind></vipbnf>

<vipbnf><CallingConventionKind>: one of
c thiscall stdcall apicall prolog</vipbnf>

If a calling convention is not stated, then the <vp>prolog</vp> convention is assumed. The <vp>prolog</vp> calling convention is the standard convention used for Prolog predicates.

The calling convention <vp>c</vp> follows the C/C++ standard calling convention. The link name of a predicate is created from the predicate name by adding a leading underscore (<vp>_</vp>).

The calling convention <vp>thiscall</vp> follows the C++ standard calling convention for virtual functions. This calling convention uses the <vp>c</vp> link name strategy but sometimes it may use the different argument and stack handling rules. Calling convention <vp>thiscall</vp> can be applied to the object predicates only.

The calling convention <vp>stdcall</vp> uses the <vp>c</vp> link name strategy but it uses the different argument and stack handling rules. The following table shows the implementation of <vp>stdcall</vp> calling convention:

{|{{prettytable}}
|-
!Feature
!Implementation
|-
|Argument-passing order
|Right to left.
|-
|Argument-passing convention
|By value, unless a compound domain term is passed. So it cannot be used to predicates with variable number of arguments.
|-
|Stack-maintenance responsibility
|Called predicate pops its own arguments from the stack.
|-
|Name-decoration convention
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|Case-translation convention
|No case translation of the predicate name is performed.
|}

The calling convention <vp>apicall</vp> uses the same argument and stack handling rules as <vp>stdcall</vp>, but for convenience to call MS Windows API functions <vp>apicall</vp> uses the naming conventions that are used by most MS Windows API functions. According to <vp>apicall</vp> naming conventions the link name of a predicate is constructed as follows:

*an leading underscore (<vp>_</vp>) is prefixed to the predicate name;
*the predicate name in which the first letter is changed in to a capital letter;
*the '<vp>A</vp>', the '<vp>W</vp>' or nothing is suffixed, if the arguments and the return type indicate an ANSI, Unicode or neutral predicate, respectively;
*the '<vp>@</vp>' is suffixed;
*the number of bytes pushed on the call stack is suffixed.

{{Example|
<vip>predicates
predicateName : (integer, string) language apicall</vip>

The argument types of this predicate indicates that it is a Unicode predicate (as {{lang2|Built-in_entities|string|string}} is the domain of Unicode strings). An {{lang2|Built-in_entities|integer|integer}} and a {{lang2|Built-in_entities|string|string}} each occupies 4 bytes on the call stack and, therefore, the link name becomes:

<source lang="text">_PredicateNameW@8</source>
}}

If <vp>apicall</vp> is used together with the "<vp>as</vp>" construction the name stated in the "<vp>as</vp>" construction is decorated in the same manner.

<vp>apicall</vp> can only be used directly in a predicate declaration, not in a predicate domain definition. In predicate domain definitions <vp>stdcall</vp>, must be used instead. A predicate declared with <vp>apicall</vp> calling convention cannot have clauses and it also cannot be resolved externally without explicit DLL name.

The following table compares implementations of <vp>c</vp>, <vp>apicall</vp>, and <vp>stdcall</vp> calling conventions (the <vp>prolog</vp> calling convention has the special implementation, which is not discussed here):

{|{{prettytable}}
|-
!Keyword
!Stack cleanup
!Predicate name case-translation
!Link predicate name decoration convention
|-
|<vp>c</vp>
|'''Calling''' predicate pops the arguments from the stack.
|None.
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|<vp>stdcall</vp>
|'''Called''' predicate pops its own arguments from the stack.
|None.
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|<vp>apicall</vp>
|'''Called''' predicate pops its own arguments from the stack.
|The first letter of the predicate name is changed to the capital letter.
|An underscore (<vp>_</vp>) is prefixed to the name. The first letter is changed to the upper case. The '<vp>A</vp>', the '<vp>W</vp>' or nothing is suffixed. The sign <vp>@</vp> is suffixed. The (decimal) number of bytes in the argument list is suffixed.
|}

Visual Prolog notion of predicate domains covers both class and object members. Class members are handled straight forward, but the handling of object members requires attention. The invocation of an object predicate will get "back" in the context of the object to which the member belongs.

{{Example| Assume the following declarations:

<vip>interface actionEventSource
domains
actionListener = (actionEventSource Source) procedure (i).
predicates
addActionListener : (actionListener Listener) procedure (i).
... end interface</vip>

Also assume a class <vp>button_class</vp> which supports the <vp>actionEventSource</vp>. The event is sent when the button is pressed. In <vp>myDialog_class</vp> class, which implements a dialog, I create a button and I want to listen to its action events, so that I can react on button presses:

<vip>implement myDialog_class
clauses
new() :-
OkButton = button_class::new(...),
OkButton:addActionListener(onOk),
...
facts
okPressed : () determ.
predicates
onOk : actionListener.
clauses
onOk(Source) :-
assert(okPressed()).
end implement</vip>

The important thing about the example is that <vp>onOk</vp> is an object member and that, when the button is pressed, the invocation of the registered <vp>onOk</vp> will bring us back in the object that owns <vp>onOk</vp>. This means that we have access to the object fact <vp>okPressed</vp>, so that we can assert it.
}}

===== Format Strings =====

A formal parameter to a predicate can be marked as format string using the attribute {{lang2|Attributes|formatString|formatString}}. The format string can contain ordinary characters which are printed without modification, and format fields, that % begins with the percent '%' sign. If the percent sign is followed % by some unknown character (not the format specifier) - then % this character will be printed without modifications.

<vip>predicates
writef : (string Format [formatstring], ...).</vip>

The format fields specification is:

[-][0][width][.precision][type]

All fields are optional.

[-] Hyphen indicates that the field is to be left justified; right justified is the default. Having no effect when width value is not set, or the number of characters in the actual value is greater than width value.

[0] Zero before width means for values that zeros will be added until the minimum width is reached. If 0(zero) and -(hyphen) appear, the 0 is ignored

[width] Positive decimal number specifying a minimum field size. If the number of characters in the actual value is less than width value - then the required number of space ' ' characters will be added before the value (or after it, if '-' field was set). No changes occurs if number of characters in the actual value is greater than the width value.

[.precision] The point '.' with the following unsigned decimal number can specify either the precision of a floating-point image or the maximum number of characters to be printed from a string.

[type] Specifies other format then the default for the given. For example, in the type field, you can give a specifier that says an integer will be formatted as an unsigned. The possible values are:

:{|{{prettytable}}
|-
| f || Format real's in fixed-decimal notation (such as 123.4 or 0.004321). This is the default for real's.
|-
| e || Format real's in exponential notation (such as 1.234e+002 or 4.321e-003).
|-
| g || Format real's in the shortest of f and e format, but always in e format if exponent of the value is less than -4 or greater than or equal to the precision. Trailing zeros are truncated.
|-
| d or D || Format as a signed decimal number.
|-
| u or U || Format as an unsigned integer.
|-
| x or X || Format as a hexadecimal number.
|-
| o or O || Format as an octal number.
|-
| c || Format as a char.
|-
| B || Format as the Visual Prolog binary type.
|-
| R || Format as a database reference number.
|-
| P || Format as a procedure parameter.
|-
| s || Format as a string.
|}

==== Integral Domains ====

Integral domains are used for representing integral numbers. They are divided in two main categories for signed and unsigned numbers. Integral domains can also have different representation size. The predefined domains {{lang2|Built-in_entities|integer|integer}} and {{lang2|Built-in_entities|unsigned|unsigned}} represent signed and unsigned numbers with natural representation length for the processor architecture (i.e. 32bit on a 32bit machine, etc).

<vipbnf><IntegralDomain>:
<DomainName>-opt <IntegralDomainProperties></vipbnf>

If a <vpbnf><DomainName></vpbnf> is stated in front of the <vpbnf><IntegralDomainProperties></vpbnf>, then this domain must itself be an integral domain and the resulting domain will be child-type (i.e. subtype) of this domain. In that case <vpbnf><IntegralDomainProperties></vpbnf> may not violate the possibility of being a subtype, i.e. the range cannot be extended and the size cannot be changed.

<vipbnf><IntegralDomainProperties>:
<IntegralSizeDescription> <IntegralRangeDescription>-opt
<IntegralRangeDescription> <IntegralSizeDescription>-opt

<IntegralSizeDescription>:
bitsize <DomainSize>

<DomainSize>:
<IntegralConstantExpression></vipbnf>

An integral size description declares the size <vpbnf><DomainSize></vpbnf> of the integral domain, measured in bits. The compiler implement such representation to the integral domain, which has no less than the specified number of bits. The value of <vpbnf><DomainSize></vpbnf> should be positive and no greater than the maximal value supported by the compiler.

If integral size description is omitted, then it will become the same as the parent domain. If there is no parent domain, it will become the natural size for the processor.

<vipbnf><IntegralRangeDescription>:
[ <MinimalBoundary>-opt .. <MaximalBoundary>-opt ]

<MinimalBoundary>:
<IntegralConstantExpression>

<MaximalBoundary>:
<IntegralConstantExpression></vipbnf>

An integral range description declares the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits for the integral domain. If a limit is omitted, then the range of the parent domain is used. If there is no parent domain, then the <vpbnf><DomainSize></vpbnf> is used to determine respectively maximum or minimum value.

Notice that the specified minimum value should not exceed the specified maximum value. That is:

<vipbnf><MinimalBoundary> <= <MaximalBoundary></vipbnf>

Also the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits should satisfy the limits implied by the specified bit size <vp>bitsize</vp>.

The domain bit size <vpbnf><DomainSize></vpbnf> value and values of the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits must be calculated while compiling time.

==== Real Domains ====

Real domains are used to represent numbers with fractional parts (i.e. floating point numbers). Real domains can be used to represent very large and very small numbers. The built-in domain ''real'' have the natural precision for the processor architecture (or the precision given by the compiler).

<vipbnf><RealDomain>:
<DomainName>-opt <RealDomainProperties></vipbnf>

If a <vpbnf><DomainName></vpbnf> is stated in front of the <vpbnf><RealDomainProperties></vpbnf>, then this domain must itself be a real domain and the resulting domain will be a subtype of this domain. In that case <vpbnf><RealDomainProperties></vpbnf> may not violate the possibility of being a subtype, i.e. the range cannot be extended and the precision cannot be increased.

<vipbnf><RealDomainProperties>: one of
<RealPrecisionDescription> <RealRangeDescription>-opt
<RealRangeDescription> <RealPrecisionDescription></vipbnf>

<vipbnf><RealPrecisionDescription>:
digits <IntegralConstantExpression></vipbnf>

The real precision description declares precision of the real domain, measured in number of decimal digits. If precision is omitted then it will become the same as for the parent domain. If there is no parent domain, then it will be the natural precision for the processor or given by the compiler (in Visual Prolog v.6 the compiler limit is 15 digits). Precision have an upper and a lower limits given by the compiler, if the precisions larger than that limit is used the numbers will only obtain the processor (compiler) specified precision anyway.

<vipbnf><RealRangeDescription>:
[ <MinimalRealBoundary>-opt .. <MaximalRealBoundary>-opt ]

<MinimalRealBoundary>:
<RealConstantExpression>

<MaximalRealBoundary>:
<RealConstantExpression></vipbnf>

Here <vpbnf><RealConstantExpression></vpbnf> is an expression, which must be compile time evaluated to a floating point value. That is the real domain precision and limits must be calculated while compiling time.

The real range description declares minimal and maximal limits for the real domain. If a limit is omitted then it will be the same as for the parent domain. If there is no parent domain then the largest possible range for the precision will be used.

Notice that the specified minimum value should not exceed the specified maximum value. That is:

<vipbnf><MinimalBoundary> <= <MaximalBoundary></vipbnf>

==== Generic Domains ====

This section contains the formal syntax for generic domains, for a more complete introduction to generics please see the section ''''' Generics'''''.

<vipbnf><FormalTypeParameterList>:
<TypeVariable>-comma-sep-list-opt</vipbnf>

A formalTypeParameterList is a list of typeVariables

<vipbnf><TypeVariable>:
<UpperCaseIdentifier></vipbnf>

A <vpbnf><TypeVariable></vpbnf> is an upper case identifier. In a domain declaration the type variable must be bound in the <vpbnf><FormalTypeParameterList></vpbnf> on the left hand side of the domain definition. In a predicate declaration all free type variables are implicitly bound and scoped to that predicate declaration.

<vipbnf><TypeApplication>:
<TypeName> {<TypeExpression>-comma-sep-list-opt }</vipbnf>

A <vpbnf><TypeApplication></vpbnf> is the application of a {{lang2|Domains|Type_Names|typeName}} to a list of types. The type name must be generic and the number of formal type parameters must match the number of type expressions.

=== Universal and Root Types ===

Visual Prolog uses some internal types, called ''root'' types and ''universal'' types.

==== Universal Types ====

A number literal like <vp>1</vp> does not have any particular type, it can be used as a value of any type that contains <vp>1</vp>, including real types.

We say that <vp>1</vp> have a universal type. Having a universal type means that it have any type, which can represent its value.

Arithmetic operations also return universal types.

==== Root Types ====

Arithmetic operations are very liberal with their operand requirements: You can add integers of any integer domain with each other.

We say that arithmetic operands takes root types as arguments. The integer root type is super-type of any integer type (regardless that it is not mentioned in their declarations). Hence any integer type can be converted to the integer root type, and, since the arithmetic operations exist for the root types, it means one of them will work on any integer domains.

The actual number of root types and which operands exist is a matter of library facilities, and outside the scope of this document to describe.

Language Reference/Attributes

2012-10-25T09:17:20Z

Alexander Doronin: /* programPoint */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== programPoint ====

Used for a predicate or constructor declaration to indicate that it recieves an extra input argument which describes the place in a program (program point) where this predicate was called. This additional argument has programPoint type which is declared in the PFC core class like:

<vip>domains
programPoint = programPoint(hScopeDescriptor ClassDescriptor, string PredicateName, sourceCursor Cursor).
</vip>

The clause name of such predicate or constructor should have suffix "_explicit". Valid for a predicate or constructor declaration.

{{Example|
<vip>predicates
pred : (string String) [programPoint].
clauses
pred_explicit(ProgramPoint, String) :-
...
</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the objects of such type. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface

class myClass : myInterface
...
end class myClass</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Attributes

2012-10-25T09:16:51Z

Alexander Doronin: /* programPoint */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== programPoint ====

Used for a predicate or constructor declaration to indicate that it recieves an extra input argument which describes the place in a program (program point) where this predicate was called. This additional argument has programPoint type which is declared in the PFC core class like:

{{
<vip>domains
programPoint = programPoint(hScopeDescriptor ClassDescriptor, string PredicateName, sourceCursor Cursor).
</vip>
}}

The clause name of such predicate or constructor should have suffix "_explicit". Valid for a predicate or constructor declaration.

{{Example|
<vip>predicates
pred : (string String) [programPoint].
clauses
pred_explicit(ProgramPoint, String) :-
...
</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the objects of such type. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface

class myClass : myInterface
...
end class myClass</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Attributes

2012-10-25T09:03:58Z

Alexander Doronin: /* programPoint */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== programPoint ====

Used for a predicate or constructor declaration to indicate that it recieves an extra input argument which describes the place in a program (program point) where this predicate was called. Valid for a predicate or constructor declaration.

{{Example|
<vip>predicates
pred : (string String) [programPoint].
clauses
pred_explicit(ProgramPoint, String) :-
...
</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the objects of such type. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface

class myClass : myInterface
...
end class myClass</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Attributes

2012-10-25T08:57:49Z

Alexander Doronin: /* out */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== programPoint ====

Valid for a predicate or constructor declaration.

{{Example|
<vip>predicates
pred : (string String) [programPoint].</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the objects of such type. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface

class myClass : myInterface
...
end class myClass</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Attributes

2012-10-25T08:55:03Z

Alexander Doronin: /* sealed */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the objects of such type. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface

class myClass : myInterface
...
end class myClass</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Attributes

2012-10-25T08:53:49Z

Alexander Doronin: /* sealed */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the object of such type. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface

class myClass : myInterface
...
end class myClass</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Attributes

2012-10-25T08:41:41Z

Alexander Doronin: /* retired */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Directives

2012-06-09T09:06:08Z

Alexander Doronin: /* Binary File Inclusion */

{{languageReferenceNavbar|Directives}}

Each compiler directive starts from the <vp>#</vp> character. The following directives are supported:

* <vp>#include</vp>, <vp>#bininclude </vp> - file inclusion.
* <vp>#if</vp>, <vp>#then</vp>, <vp>#else</vp>, <vp>#elseif</vp>, <vp>#endif</vp> - conditional statements.
* <vp>#export</vp>, <vp>#externally</vp> - exporting and importing classes.
* <vp>#message</vp>, <vp>#error</vp>, <vp>#requires</vp>, <vp>#orrequires</vp> - compilation time information.
* <vp>#options</vp> - compiler options.

=== Source File Inclusion ===

The <vp>#include</vp> compiler directive is used to include the contents of another file into your program source code during compilation. It has the following syntax:

<vipbnf><Pp_dir_include> :
#include <String_literal></vipbnf>

The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename.

<vipbnf>#include "pfc\\exception\\exception.ph" % Includes pfc\exception\exception.ph file</vipbnf>

<vipbnf>#include @"pfc\vpi\vpimessage\vpimessage.ph" % Includes pfc\vpi\vpimessage\vpimessage.ph</vipbnf>

This compiler directive uses "include the first file occurrence only" semantics. That is, if a compilation unit contains several include directives for the same file, it will be included only one time with the first include directive.

Each included file must contain several accomplished scopes; an included file cannot contain uncompleted scopes. That is, it should contain several accomplished interface declarations, class declarations, class implementations or/and several compiler directives.

The compiler tries to find the specified include source file in the following way:

#If the filename contains an absolute path, then this file should be included.
#Otherwise, the compiler searches for the specified include filename among the paths that had been defined by the <vp>/Include</vp> command line option. These paths are handled consequently as they are specified in the option. In the IDE you can set these paths in the '''Include Directories''' in the '''Directories''' tab of the '''Project Settings''' dialog.

If the compiler does not find the specified file a compiling time error is generated.

=== Binary File Inclusion ===

The <vp>#bininclude</vp> compiler directive is used to include (during compilation) the contents of a file (specified by the {{lang2|Lexical_Elements|String_Literals|string_literal}} string) as a ::{{lang2|Built-in_entities|binary|binary}} type constant into your program source code. It has the following syntax:

<vipbnf><Pp_dir_bininclude> :
#bininclude ( <String_literal> )</vipbnf>

This directive can be used in any places where {{lang2|Built-in_entities|binary|binary}} constants are allowed. The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename. The syntax is the same as in the <vp>#include</vp> compiler directive described in the previous paragraph {{lang2|Directives|Source_File_Inclusion|Source File Inclusions}}. The compiler tries to find the specified file in the same way as for <vp>#include</vp> compiler directive.

The typical usage is like this:

<vip>constants
myBin : binary = #bininclude("Bin.bin").
% Creates value of binary constant from "Bin.bin" file</vip>
When creating a binary constant the compiler adds the EOS symbol immediately after this constant, which makes safe the directive usages like this:

<vip>constants
text : string = uncheckedConvert(string, #bininclude("text.txt")).
% Here text.txt is a text file, which is normally not text zero terminated</vip>

=== Exporting and Importing Classes ===

Compiler directives <vp>#export</vp> and <vp>#externally</vp> are used to determine lists of exported and imported classes, respectively. They have the following syntax:

<vipbnf><Pp_dir_export> :
#export <ClassNames>-comma-sep-list
<Pp_dir_export> :
#externally <ClassNames>-comma-sep-list</vipbnf>

These compiler directives are applied only to classes {{lang|Classes|classNames}}, which do not construct objects.

They can be used only outside scopes; that is, they cannot be used inside declarations of interfaces and classes and they cannot be used inside implementations of classes.

By default, predicates within one executed module are hidden at runtime for all other executed modules. An <vp>#export</vp> compiler directive makes names of specified classes public outside the module in which they are declared (and implemented). Therefore, all predicates from this module declared in the classes (specified in an <vp>#export</vp> directive) become accessible while runtime from other executed modules.

Usually, an <vp>#export</vp> compiler directives can be used in projects, which target modules are DLLs. It enumerates classes declared in a DLL, which should be accessible to other modules that use this DLL.

If a compilation unit export some class, then this compilation unit should contain this class implementation.

Also an <vp>#export</vp> compiler directives can be used to specify {{lang2|Directives|Conditional_Compilation|condition}} expressions for <vp>#if</vp> compiler directives.

For example, let us suppose that somewhere in the beginning of a compilation unit the compiler has met the <vp>#export</vp> compiler directive like this:

<vip>#export className</vip>

Then the compiler, if in the subsequent code it meets an <vp>#if</vp> compiler directive with the same <vp>#export</vp> compiler directive used as the condition expression, for example like this:

<vip>#if #export className #then ... #endif </vip>

Then the compiler evaluates the <vp>#export</vp> condition expression as <vp>true</vp> and, hence, the compiler executes the <vp>#then</vp> branch of the conditional compilation directive.

For example, the following <vp>#export</vp> compiler directive with the subsequent <vp>#if</vp> conditional compilation compiler directive:

<vip>#export className
...
#if #export className #then #requires "some.pack" #endif</vip>

guaranty that the <vp>"some.pack"</vp> package will be included into the compilation unit.

From the other hand, if an <vp>#export</vp> compiler directive is not met by the compiler (somewhere in the compilation unit before the <vp>#if</vp> compiler directive, which uses the same <vp>#export</vp> compiler directive as the conditional expression), then the compiler evaluates this <vp>#export</vp> condition expression as <vp>false</vp>. Hence, the compiler will not execute the <vp>#then</vp> branch of the <vp>#if</vp> conditional compilation directive. That is, the single <vp>#if</vp> compiler directive without previous <vp>#export</vp> directive

<vip>#if #export className #then #requires "some.pack" #endif</vip>

does not requires to include the <vp>"some.pack"</vp> package.

An <vp>#externally</vp> compiler directive is counterpart to an <vp>#export</vp> compiler directive. An <vp>#externally</vp> compiler directive can be used instead of (and concurrently with) an <vp>IMPORTS</vp> directive in definition files. An <vp>#externally</vp> compiler directive enumerates classes, which are declared in a module but implemented in other modules. Therefore, the compiler will not produce errors when it detects such classes. The referenced classes can be implemented (and exported) in DLLs, which can be linked to the module at runtime.

The <vp>#export</vp> and <vp>#externally</vp> compiler directives can be used as <vpbnf><Condition></vpbnf> boolean expressions in {{lang2|Directives|Compiler_Directives|Conditional Directives}}.

For example, like this:

<vip>#if #export className #then #include "Some package.pack" #endif</vip>

=== Compile Time Information ===

Compiler directives <vp>#message</vp>, <vp>#requires</vp>, <vp>#orrequires</vp>, and <vp>#error</vp> can be used to issue user-defined messages into a listing file while compilation of project modules and to interrupt compilation.

These directives can be used either outside scopes (interface declaration, class declaration or class implementation), or inside scopes but outside sections. They have the following syntax:

<vipbnf><Pp_dir_message>: one of
#message <String_literal>
#error <String_literal>
#requires <String_literal> <Pp_dir_orrequires>-list-opt
#orrequires <String_literal></vipbnf>

When the compiler meets any of these directives, it generates the correspondent warning message and place the directive text into a ''listing file''.

A listing file name can be specified with the compiler directive:

<source lang="text">/listingfile:"FileName"</source>

Notice that no empty spaces can be used between the colon <vp>:</vp> (after <vp>/listinglile</vp>) and <vp>"FileName"</vp>.

By default the compiler does NOT generate informative messages for the <vp>#message</vp>, <vp>#requires</vp>, and <vp>#orrequires</vp> directives. You can switch generation of these informative messages ON specifying the compiler options:

<source lang="text">/listing:message
/listing:requires
/listing:ALL</source>

{{Example| In this case, when the compiler meets a directive like:

<vip>#message "Some message"</vip>

it will place the following text into the listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : information c062: #message "Some message"</source>
}}

The directive <vp>#requires</vp> (<vp>#orrequires</vp>) issues arbitrary user-defined messages about the needed source (object) files into a listing file. The <vp>#orrequires</vp> directive cannot be used alone: the <vp>#requires</vp> directive should immediately (separated with white spaces or comments only) precede it.

The directive <vp>#error</vp> always terminates the compilation and issues the user-defined error message like the following into a listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : error c080: #error "Compilation is interrupted"</source>

You can parse and analyze these messages and accept the required actions. For example, the VDE analyzes information printed by the <vp>#requires</vp> and <vp>#orrequires</vp> directives and automatically adds all needed PFC packages and standard libraries to the compiled project (See also the '''Handling Project Modules''' topic).

{{Example| The directives <vp>#requires</vp> and <vp>#orrequires</vp> can be used like this:

<vip>#requires @"\Common\Sources\CommonTypes.pack"
#orrequires @"\Common\Lib\CommonTypes.lib"
#orrequires @"\Common\Obj\Foreign.obj"
#if someClass::debugLevel > 0 #then
#requires @"\Sources\Debug\Tools.pack"
#orrequires @"\Lib\Debug\Tools.lib"
#else
#requires @"\Sources\Release\Tools.pack"
#orrequires @"\Lib\Release\Tools.lib"
#endif
#orrequires "SomeLibrary.lib"
#requires "SomePackage.pack"
#if someClass::debugLevel > 0 #then
#orrequires @"\Debug\SomePackage.lib"
#else
#orrequires @"\Release\SomePackage.lib"
#endif</vip>
}}

{{Example| The <vp>#message</vp> directive can be used like this:

<vip>#message "Some text"
#if someClass::someConstant > 0 #then
#message "someClass::someConstant > 0"
#else
#message "someClass::someConstant <= 0"
#endif
class someClass
#if ::compiler_version > 600 #then
#message "New compiler"
constants
someConstant = 1.
#else
#message "Old compiler"
constants
someConstant = 0.
#endif
end class someClass</vip>
}}

{{Example| The <vp>#error</vp> can be used like this:

<vip>#if someClass::debugLevel > 0 #then
#error "Debug version is not yet implemented"
#endif</vip>
}}

=== Compiler options directive ===

Compiler directive <vp>#options <string_literal></vp> affects the whole compilation unit. This directive should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates a warning message and ignores the directive.

The <vp><string_literal></vp> can only contain the following compiler options:

<vip>"/Warning"
"/Check"
"/NOCheck"
"/Optimize"
"/DEBug"
"/GOAL"
"/MAXErrors"
"/MAXWarnings"</vip>

Otherwise the compiler generates the error message for invalid option.
If there are several <vp>#options</vp> directives they are handled in the textual order.

=== Conditional Compilation ===

The conditional programming constructions are part of the Visual Prolog language. Only other compiler directives, {{lang2|Compilation_Units|Compilation_Units_and_Items|Compilation Units}}, and {{lang2|Program_Sections|Program_Sections|program sections}} (including empty) can be conditional. The following syntax is used:

<vipbnf><ConditionalItem> :
#if <Condition> #then <CompilationItem>-list-opt <ElseIfItem>-list-opt <ElseItem>-opt #endif</vipbnf>

<vipbnf><ElseIfItem> :
#elseif <Condition> #then <CompilationItem></vipbnf>

<vipbnf><ElseItem> :
#else <CompilationItem></vipbnf>

Here <vpbnf><Condition></vpbnf> can be any expression, which can be evaluated to fail or succeed during compilation time.

Each one conditional compilation statement must be in one file, that is, the compiler directives <vp>#if</vp>, <vp>#then</vp>, <vp>#elseif</vp> and <vp>#else</vp> (if present), <vp>#endif</vp> of the same level of nesting must be in one file.

During compilation the compiler evaluates the conditions, in order to determine which parts to include in the final program. Parts that are excluded from the final program are called the dead branches.

All branches of conditional compilation items are syntax checked and must be syntactically correct. That is, also the dead branches must be syntactically correct.

The compiler only calculates conditions on a need to know basis, i.e. it does not calculate conditions in dead branches.

A condition may not depend on any code, which is located textually inside the conditional statement.

The example below is '''illegal''' because the condition depends on the scope (and constant) which is declared inside the condition branch.

<vip>#if aaa::x > 7 #then % ERROR!
class aaa
constants
x = 3
end class aaa
#else
class aaa
constants
x = 23
end class aaa
#endif</vip>

Language Reference/Directives

2012-06-09T06:58:42Z

Alexander Doronin: /* Binary File Inclusion */

{{languageReferenceNavbar|Directives}}

Each compiler directive starts from the <vp>#</vp> character. The following directives are supported:

* <vp>#include</vp>, <vp>#bininclude </vp> - file inclusion.
* <vp>#if</vp>, <vp>#then</vp>, <vp>#else</vp>, <vp>#elseif</vp>, <vp>#endif</vp> - conditional statements.
* <vp>#export</vp>, <vp>#externally</vp> - exporting and importing classes.
* <vp>#message</vp>, <vp>#error</vp>, <vp>#requires</vp>, <vp>#orrequires</vp> - compilation time information.
* <vp>#options</vp> - compiler options.

=== Source File Inclusion ===

The <vp>#include</vp> compiler directive is used to include the contents of another file into your program source code during compilation. It has the following syntax:

<vipbnf><Pp_dir_include> :
#include <String_literal></vipbnf>

The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename.

<vipbnf>#include "pfc\\exception\\exception.ph" % Includes pfc\exception\exception.ph file</vipbnf>

<vipbnf>#include @"pfc\vpi\vpimessage\vpimessage.ph" % Includes pfc\vpi\vpimessage\vpimessage.ph</vipbnf>

This compiler directive uses "include the first file occurrence only" semantics. That is, if a compilation unit contains several include directives for the same file, it will be included only one time with the first include directive.

Each included file must contain several accomplished scopes; an included file cannot contain uncompleted scopes. That is, it should contain several accomplished interface declarations, class declarations, class implementations or/and several compiler directives.

The compiler tries to find the specified include source file in the following way:

#If the filename contains an absolute path, then this file should be included.
#Otherwise, the compiler searches for the specified include filename among the paths that had been defined by the <vp>/Include</vp> command line option. These paths are handled consequently as they are specified in the option. In the IDE you can set these paths in the '''Include Directories''' in the '''Directories''' tab of the '''Project Settings''' dialog.

If the compiler does not find the specified file a compiling time error is generated.

=== Binary File Inclusion ===

The <vp>#bininclude</vp> compiler directive is used to include (during compilation) the contents of a file (specified by the {{lang2|Lexical_Elements|String_Literals|string_literal}} string) as a ::{{lang2|Built-in_entities|binary|binary}} type constant into your program source code. It has the following syntax:

<vipbnf><Pp_dir_bininclude> :
#bininclude ( <String_literal> )</vipbnf>

This directive can be used in any places where ::{{lang2|Built-in_entities|binary|binary}} constants are allowed. The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename. The syntax is the same as in the <vp>#include</vp> compiler directive described in the previous paragraph {{lang2|Directives|Source_File_Inclusion|Source File Inclusions}}. The compiler tries to find the specified file in the same way as for <vp>#include</vp> compiler directive.

When creating a binary constant the compiler adds the EOS symbol immediately after this constant, which makes safe the directive usages like this:

<vip>constants
text : ::string = uncheckedConvert(string, #bininclude ("text.txt")). % Here text.txt is a text file, which
% is normally not text zero terminated</vip>

The typical usage is like this:

<vip>constants
myBin : ::binary = #bininclude ("Bin.bin"). % Creates value of binary
% constant from "Bin.bin" file
myBin2 = #bininclude ("Bin2.bin"). % Short format of a binary
% constant initialization</vip>

=== Exporting and Importing Classes ===

Compiler directives <vp>#export</vp> and <vp>#externally</vp> are used to determine lists of exported and imported classes, respectively. They have the following syntax:

<vipbnf><Pp_dir_export> :
#export <ClassNames>-comma-sep-list
<Pp_dir_export> :
#externally <ClassNames>-comma-sep-list</vipbnf>

These compiler directives are applied only to classes {{lang|Classes|classNames}}, which do not construct objects.

They can be used only outside scopes; that is, they cannot be used inside declarations of interfaces and classes and they cannot be used inside implementations of classes.

By default, predicates within one executed module are hidden at runtime for all other executed modules. An <vp>#export</vp> compiler directive makes names of specified classes public outside the module in which they are declared (and implemented). Therefore, all predicates from this module declared in the classes (specified in an <vp>#export</vp> directive) become accessible while runtime from other executed modules.

Usually, an <vp>#export</vp> compiler directives can be used in projects, which target modules are DLLs. It enumerates classes declared in a DLL, which should be accessible to other modules that use this DLL.

If a compilation unit export some class, then this compilation unit should contain this class implementation.

Also an <vp>#export</vp> compiler directives can be used to specify {{lang2|Directives|Conditional_Compilation|condition}} expressions for <vp>#if</vp> compiler directives.

For example, let us suppose that somewhere in the beginning of a compilation unit the compiler has met the <vp>#export</vp> compiler directive like this:

<vip>#export className</vip>

Then the compiler, if in the subsequent code it meets an <vp>#if</vp> compiler directive with the same <vp>#export</vp> compiler directive used as the condition expression, for example like this:

<vip>#if #export className #then ... #endif </vip>

Then the compiler evaluates the <vp>#export</vp> condition expression as <vp>true</vp> and, hence, the compiler executes the <vp>#then</vp> branch of the conditional compilation directive.

For example, the following <vp>#export</vp> compiler directive with the subsequent <vp>#if</vp> conditional compilation compiler directive:

<vip>#export className
...
#if #export className #then #requires "some.pack" #endif</vip>

guaranty that the <vp>"some.pack"</vp> package will be included into the compilation unit.

From the other hand, if an <vp>#export</vp> compiler directive is not met by the compiler (somewhere in the compilation unit before the <vp>#if</vp> compiler directive, which uses the same <vp>#export</vp> compiler directive as the conditional expression), then the compiler evaluates this <vp>#export</vp> condition expression as <vp>false</vp>. Hence, the compiler will not execute the <vp>#then</vp> branch of the <vp>#if</vp> conditional compilation directive. That is, the single <vp>#if</vp> compiler directive without previous <vp>#export</vp> directive

<vip>#if #export className #then #requires "some.pack" #endif</vip>

does not requires to include the <vp>"some.pack"</vp> package.

An <vp>#externally</vp> compiler directive is counterpart to an <vp>#export</vp> compiler directive. An <vp>#externally</vp> compiler directive can be used instead of (and concurrently with) an <vp>IMPORTS</vp> directive in definition files. An <vp>#externally</vp> compiler directive enumerates classes, which are declared in a module but implemented in other modules. Therefore, the compiler will not produce errors when it detects such classes. The referenced classes can be implemented (and exported) in DLLs, which can be linked to the module at runtime.

The <vp>#export</vp> and <vp>#externally</vp> compiler directives can be used as <vpbnf><Condition></vpbnf> boolean expressions in {{lang2|Directives|Compiler_Directives|Conditional Directives}}.

For example, like this:

<vip>#if #export className #then #include "Some package.pack" #endif</vip>

=== Compile Time Information ===

Compiler directives <vp>#message</vp>, <vp>#requires</vp>, <vp>#orrequires</vp>, and <vp>#error</vp> can be used to issue user-defined messages into a listing file while compilation of project modules and to interrupt compilation.

These directives can be used either outside scopes (interface declaration, class declaration or class implementation), or inside scopes but outside sections. They have the following syntax:

<vipbnf><Pp_dir_message>: one of
#message <String_literal>
#error <String_literal>
#requires <String_literal> <Pp_dir_orrequires>-list-opt
#orrequires <String_literal></vipbnf>

When the compiler meets any of these directives, it generates the correspondent warning message and place the directive text into a ''listing file''.

A listing file name can be specified with the compiler directive:

<source lang="text">/listingfile:"FileName"</source>

Notice that no empty spaces can be used between the colon <vp>:</vp> (after <vp>/listinglile</vp>) and <vp>"FileName"</vp>.

By default the compiler does NOT generate informative messages for the <vp>#message</vp>, <vp>#requires</vp>, and <vp>#orrequires</vp> directives. You can switch generation of these informative messages ON specifying the compiler options:

<source lang="text">/listing:message
/listing:requires
/listing:ALL</source>

{{Example| In this case, when the compiler meets a directive like:

<vip>#message "Some message"</vip>

it will place the following text into the listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : information c062: #message "Some message"</source>
}}

The directive <vp>#requires</vp> (<vp>#orrequires</vp>) issues arbitrary user-defined messages about the needed source (object) files into a listing file. The <vp>#orrequires</vp> directive cannot be used alone: the <vp>#requires</vp> directive should immediately (separated with white spaces or comments only) precede it.

The directive <vp>#error</vp> always terminates the compilation and issues the user-defined error message like the following into a listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : error c080: #error "Compilation is interrupted"</source>

You can parse and analyze these messages and accept the required actions. For example, the VDE analyzes information printed by the <vp>#requires</vp> and <vp>#orrequires</vp> directives and automatically adds all needed PFC packages and standard libraries to the compiled project (See also the '''Handling Project Modules''' topic).

{{Example| The directives <vp>#requires</vp> and <vp>#orrequires</vp> can be used like this:

<vip>#requires @"\Common\Sources\CommonTypes.pack"
#orrequires @"\Common\Lib\CommonTypes.lib"
#orrequires @"\Common\Obj\Foreign.obj"
#if someClass::debugLevel > 0 #then
#requires @"\Sources\Debug\Tools.pack"
#orrequires @"\Lib\Debug\Tools.lib"
#else
#requires @"\Sources\Release\Tools.pack"
#orrequires @"\Lib\Release\Tools.lib"
#endif
#orrequires "SomeLibrary.lib"
#requires "SomePackage.pack"
#if someClass::debugLevel > 0 #then
#orrequires @"\Debug\SomePackage.lib"
#else
#orrequires @"\Release\SomePackage.lib"
#endif</vip>
}}

{{Example| The <vp>#message</vp> directive can be used like this:

<vip>#message "Some text"
#if someClass::someConstant > 0 #then
#message "someClass::someConstant > 0"
#else
#message "someClass::someConstant <= 0"
#endif
class someClass
#if ::compiler_version > 600 #then
#message "New compiler"
constants
someConstant = 1.
#else
#message "Old compiler"
constants
someConstant = 0.
#endif
end class someClass</vip>
}}

{{Example| The <vp>#error</vp> can be used like this:

<vip>#if someClass::debugLevel > 0 #then
#error "Debug version is not yet implemented"
#endif</vip>
}}

=== Compiler options directive ===

Compiler directive <vp>#options <string_literal></vp> affects the whole compilation unit. This directive should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates a warning message and ignores the directive.

The <vp><string_literal></vp> can only contain the following compiler options:

<vip>"/Warning"
"/Check"
"/NOCheck"
"/Optimize"
"/DEBug"
"/GOAL"
"/MAXErrors"
"/MAXWarnings"</vip>

Otherwise the compiler generates the error message for invalid option.
If there are several <vp>#options</vp> directives they are handled in the textual order.

=== Conditional Compilation ===

The conditional programming constructions are part of the Visual Prolog language. Only other compiler directives, {{lang2|Compilation_Units|Compilation_Units_and_Items|Compilation Units}}, and {{lang2|Program_Sections|Program_Sections|program sections}} (including empty) can be conditional. The following syntax is used:

<vipbnf><ConditionalItem> :
#if <Condition> #then <CompilationItem>-list-opt <ElseIfItem>-list-opt <ElseItem>-opt #endif</vipbnf>

<vipbnf><ElseIfItem> :
#elseif <Condition> #then <CompilationItem></vipbnf>

<vipbnf><ElseItem> :
#else <CompilationItem></vipbnf>

Here <vpbnf><Condition></vpbnf> can be any expression, which can be evaluated to fail or succeed during compilation time.

Each one conditional compilation statement must be in one file, that is, the compiler directives <vp>#if</vp>, <vp>#then</vp>, <vp>#elseif</vp> and <vp>#else</vp> (if present), <vp>#endif</vp> of the same level of nesting must be in one file.

During compilation the compiler evaluates the conditions, in order to determine which parts to include in the final program. Parts that are excluded from the final program are called the dead branches.

All branches of conditional compilation items are syntax checked and must be syntactically correct. That is, also the dead branches must be syntactically correct.

The compiler only calculates conditions on a need to know basis, i.e. it does not calculate conditions in dead branches.

A condition may not depend on any code, which is located textually inside the conditional statement.

The example below is '''illegal''' because the condition depends on the scope (and constant) which is declared inside the condition branch.

<vip>#if aaa::x > 7 #then % ERROR!
class aaa
constants
x = 3
end class aaa
#else
class aaa
constants
x = 23
end class aaa
#endif</vip>

Language Reference/Directives

2012-06-09T06:08:04Z

Alexander Doronin: /* Binary File Inclusion */

{{languageReferenceNavbar|Directives}}

Each compiler directive starts from the <vp>#</vp> character. The following directives are supported:

* <vp>#include</vp>, <vp>#bininclude </vp> - file inclusion.
* <vp>#if</vp>, <vp>#then</vp>, <vp>#else</vp>, <vp>#elseif</vp>, <vp>#endif</vp> - conditional statements.
* <vp>#export</vp>, <vp>#externally</vp> - exporting and importing classes.
* <vp>#message</vp>, <vp>#error</vp>, <vp>#requires</vp>, <vp>#orrequires</vp> - compilation time information.
* <vp>#options</vp> - compiler options.

=== Source File Inclusion ===

The <vp>#include</vp> compiler directive is used to include the contents of another file into your program source code during compilation. It has the following syntax:

<vipbnf><Pp_dir_include> :
#include <String_literal></vipbnf>

The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename.

<vipbnf>#include "pfc\\exception\\exception.ph" % Includes pfc\exception\exception.ph file</vipbnf>

<vipbnf>#include @"pfc\vpi\vpimessage\vpimessage.ph" % Includes pfc\vpi\vpimessage\vpimessage.ph</vipbnf>

This compiler directive uses "include the first file occurrence only" semantics. That is, if a compilation unit contains several include directives for the same file, it will be included only one time with the first include directive.

Each included file must contain several accomplished scopes; an included file cannot contain uncompleted scopes. That is, it should contain several accomplished interface declarations, class declarations, class implementations or/and several compiler directives.

The compiler tries to find the specified include source file in the following way:

#If the filename contains an absolute path, then this file should be included.
#Otherwise, the compiler searches for the specified include filename among the paths that had been defined by the <vp>/Include</vp> command line option. These paths are handled consequently as they are specified in the option. In the IDE you can set these paths in the '''Include Directories''' in the '''Directories''' tab of the '''Project Settings''' dialog.

If the compiler does not find the specified file a compiling time error is generated.

=== Binary File Inclusion ===

The <vp>#bininclude</vp> compiler directive is used to include (during compilation) the contents of a file (specified by the {{lang2|Lexical_Elements|String_Literals|string_literal}} string) as a ::{{lang2|Built-in_entities|binary|binary}} type constant into your program source code. It has the following syntax:

<vipbnf><Pp_dir_bininclude> :
#bininclude ( <String_literal> )</vipbnf>

This directive can be used in any places where ::{{lang2|Built-in_entities|binary|binary}} constants are allowed. The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename. The syntax is the same as in the <vp>#include</vp> compiler directive described in the previous paragraph {{lang2|Directives|Source_File_Inclusion|Source File Inclusions}}. The compiler tries to find the specified file in the same way as for <vp>#include</vp> compiler directive.

The typical usage is like this:

<vip>constants
myBin : ::binary = #bininclude ("Bin.bin"). % Creates value of binary
% constant from "Bin.bin" file
myBin2 = #bininclude ("Bin2.bin"). % Short format of a binary
% constant initialization</vip>

In this example. Parsing the first constant <vp>myBin</vp> declaration, the compiler meets the <vp>#bininclude ("Bin.bin")</vp> directive. It checks whether the '''"Bin.bin"''' file exists in the directory where the source file containing this <vp>#bininclude ("Bin.bin")</vp> directive is placed or whether the '''"Bin.bin"''' file exists in one of directories specified in the '''Include Directories''' list box in the '''Project Settings''' dialog (in directories defined by the <vp>/Include</vp> command line option). If the compiler finds the '''"Bin.bin"''' file, then it reads it. From the file contents the compiler forms correct data of the ::{{lang2|Built-in_entities|binary|binary}} domain and place it as the <vp>myBin</vp> constant value. For example, if the '''"Bin.bin"''' file contains only one <vp>A</vp> character, then the <vp>myBin</vp> constant obtains the following value:

<vip>myBin = $[0x41] % Here 0x41 is the hexadecimal ASCII value of 'A'</vip>

=== Exporting and Importing Classes ===

Compiler directives <vp>#export</vp> and <vp>#externally</vp> are used to determine lists of exported and imported classes, respectively. They have the following syntax:

<vipbnf><Pp_dir_export> :
#export <ClassNames>-comma-sep-list
<Pp_dir_export> :
#externally <ClassNames>-comma-sep-list</vipbnf>

These compiler directives are applied only to classes {{lang|Classes|classNames}}, which do not construct objects.

They can be used only outside scopes; that is, they cannot be used inside declarations of interfaces and classes and they cannot be used inside implementations of classes.

By default, predicates within one executed module are hidden at runtime for all other executed modules. An <vp>#export</vp> compiler directive makes names of specified classes public outside the module in which they are declared (and implemented). Therefore, all predicates from this module declared in the classes (specified in an <vp>#export</vp> directive) become accessible while runtime from other executed modules.

Usually, an <vp>#export</vp> compiler directives can be used in projects, which target modules are DLLs. It enumerates classes declared in a DLL, which should be accessible to other modules that use this DLL.

If a compilation unit export some class, then this compilation unit should contain this class implementation.

Also an <vp>#export</vp> compiler directives can be used to specify {{lang2|Directives|Conditional_Compilation|condition}} expressions for <vp>#if</vp> compiler directives.

For example, let us suppose that somewhere in the beginning of a compilation unit the compiler has met the <vp>#export</vp> compiler directive like this:

<vip>#export className</vip>

Then the compiler, if in the subsequent code it meets an <vp>#if</vp> compiler directive with the same <vp>#export</vp> compiler directive used as the condition expression, for example like this:

<vip>#if #export className #then ... #endif </vip>

Then the compiler evaluates the <vp>#export</vp> condition expression as <vp>true</vp> and, hence, the compiler executes the <vp>#then</vp> branch of the conditional compilation directive.

For example, the following <vp>#export</vp> compiler directive with the subsequent <vp>#if</vp> conditional compilation compiler directive:

<vip>#export className
...
#if #export className #then #requires "some.pack" #endif</vip>

guaranty that the <vp>"some.pack"</vp> package will be included into the compilation unit.

From the other hand, if an <vp>#export</vp> compiler directive is not met by the compiler (somewhere in the compilation unit before the <vp>#if</vp> compiler directive, which uses the same <vp>#export</vp> compiler directive as the conditional expression), then the compiler evaluates this <vp>#export</vp> condition expression as <vp>false</vp>. Hence, the compiler will not execute the <vp>#then</vp> branch of the <vp>#if</vp> conditional compilation directive. That is, the single <vp>#if</vp> compiler directive without previous <vp>#export</vp> directive

<vip>#if #export className #then #requires "some.pack" #endif</vip>

does not requires to include the <vp>"some.pack"</vp> package.

An <vp>#externally</vp> compiler directive is counterpart to an <vp>#export</vp> compiler directive. An <vp>#externally</vp> compiler directive can be used instead of (and concurrently with) an <vp>IMPORTS</vp> directive in definition files. An <vp>#externally</vp> compiler directive enumerates classes, which are declared in a module but implemented in other modules. Therefore, the compiler will not produce errors when it detects such classes. The referenced classes can be implemented (and exported) in DLLs, which can be linked to the module at runtime.

The <vp>#export</vp> and <vp>#externally</vp> compiler directives can be used as <vpbnf><Condition></vpbnf> boolean expressions in {{lang2|Directives|Compiler_Directives|Conditional Directives}}.

For example, like this:

<vip>#if #export className #then #include "Some package.pack" #endif</vip>

=== Compile Time Information ===

Compiler directives <vp>#message</vp>, <vp>#requires</vp>, <vp>#orrequires</vp>, and <vp>#error</vp> can be used to issue user-defined messages into a listing file while compilation of project modules and to interrupt compilation.

These directives can be used either outside scopes (interface declaration, class declaration or class implementation), or inside scopes but outside sections. They have the following syntax:

<vipbnf><Pp_dir_message>: one of
#message <String_literal>
#error <String_literal>
#requires <String_literal> <Pp_dir_orrequires>-list-opt
#orrequires <String_literal></vipbnf>

When the compiler meets any of these directives, it generates the correspondent warning message and place the directive text into a ''listing file''.

A listing file name can be specified with the compiler directive:

<source lang="text">/listingfile:"FileName"</source>

Notice that no empty spaces can be used between the colon <vp>:</vp> (after <vp>/listinglile</vp>) and <vp>"FileName"</vp>.

By default the compiler does NOT generate informative messages for the <vp>#message</vp>, <vp>#requires</vp>, and <vp>#orrequires</vp> directives. You can switch generation of these informative messages ON specifying the compiler options:

<source lang="text">/listing:message
/listing:requires
/listing:ALL</source>

{{Example| In this case, when the compiler meets a directive like:

<vip>#message "Some message"</vip>

it will place the following text into the listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : information c062: #message "Some message"</source>
}}

The directive <vp>#requires</vp> (<vp>#orrequires</vp>) issues arbitrary user-defined messages about the needed source (object) files into a listing file. The <vp>#orrequires</vp> directive cannot be used alone: the <vp>#requires</vp> directive should immediately (separated with white spaces or comments only) precede it.

The directive <vp>#error</vp> always terminates the compilation and issues the user-defined error message like the following into a listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : error c080: #error "Compilation is interrupted"</source>

You can parse and analyze these messages and accept the required actions. For example, the VDE analyzes information printed by the <vp>#requires</vp> and <vp>#orrequires</vp> directives and automatically adds all needed PFC packages and standard libraries to the compiled project (See also the '''Handling Project Modules''' topic).

{{Example| The directives <vp>#requires</vp> and <vp>#orrequires</vp> can be used like this:

<vip>#requires @"\Common\Sources\CommonTypes.pack"
#orrequires @"\Common\Lib\CommonTypes.lib"
#orrequires @"\Common\Obj\Foreign.obj"
#if someClass::debugLevel > 0 #then
#requires @"\Sources\Debug\Tools.pack"
#orrequires @"\Lib\Debug\Tools.lib"
#else
#requires @"\Sources\Release\Tools.pack"
#orrequires @"\Lib\Release\Tools.lib"
#endif
#orrequires "SomeLibrary.lib"
#requires "SomePackage.pack"
#if someClass::debugLevel > 0 #then
#orrequires @"\Debug\SomePackage.lib"
#else
#orrequires @"\Release\SomePackage.lib"
#endif</vip>
}}

{{Example| The <vp>#message</vp> directive can be used like this:

<vip>#message "Some text"
#if someClass::someConstant > 0 #then
#message "someClass::someConstant > 0"
#else
#message "someClass::someConstant <= 0"
#endif
class someClass
#if ::compiler_version > 600 #then
#message "New compiler"
constants
someConstant = 1.
#else
#message "Old compiler"
constants
someConstant = 0.
#endif
end class someClass</vip>
}}

{{Example| The <vp>#error</vp> can be used like this:

<vip>#if someClass::debugLevel > 0 #then
#error "Debug version is not yet implemented"
#endif</vip>
}}

=== Compiler options directive ===

Compiler directive <vp>#options <string_literal></vp> affects the whole compilation unit. This directive should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates a warning message and ignores the directive.

The <vp><string_literal></vp> can only contain the following compiler options:

<vip>"/Warning"
"/Check"
"/NOCheck"
"/Optimize"
"/DEBug"
"/GOAL"
"/MAXErrors"
"/MAXWarnings"</vip>

Otherwise the compiler generates the error message for invalid option.
If there are several <vp>#options</vp> directives they are handled in the textual order.

=== Conditional Compilation ===

The conditional programming constructions are part of the Visual Prolog language. Only other compiler directives, {{lang2|Compilation_Units|Compilation_Units_and_Items|Compilation Units}}, and {{lang2|Program_Sections|Program_Sections|program sections}} (including empty) can be conditional. The following syntax is used:

<vipbnf><ConditionalItem> :
#if <Condition> #then <CompilationItem>-list-opt <ElseIfItem>-list-opt <ElseItem>-opt #endif</vipbnf>

<vipbnf><ElseIfItem> :
#elseif <Condition> #then <CompilationItem></vipbnf>

<vipbnf><ElseItem> :
#else <CompilationItem></vipbnf>

Here <vpbnf><Condition></vpbnf> can be any expression, which can be evaluated to fail or succeed during compilation time.

Each one conditional compilation statement must be in one file, that is, the compiler directives <vp>#if</vp>, <vp>#then</vp>, <vp>#elseif</vp> and <vp>#else</vp> (if present), <vp>#endif</vp> of the same level of nesting must be in one file.

During compilation the compiler evaluates the conditions, in order to determine which parts to include in the final program. Parts that are excluded from the final program are called the dead branches.

All branches of conditional compilation items are syntax checked and must be syntactically correct. That is, also the dead branches must be syntactically correct.

The compiler only calculates conditions on a need to know basis, i.e. it does not calculate conditions in dead branches.

A condition may not depend on any code, which is located textually inside the conditional statement.

The example below is '''illegal''' because the condition depends on the scope (and constant) which is declared inside the condition branch.

<vip>#if aaa::x > 7 #then % ERROR!
class aaa
constants
x = 3
end class aaa
#else
class aaa
constants
x = 23
end class aaa
#endif</vip>

Language Reference/Directives

2012-06-09T06:05:34Z

Alexander Doronin: /* Source File Inclusion */

{{languageReferenceNavbar|Directives}}

Each compiler directive starts from the <vp>#</vp> character. The following directives are supported:

* <vp>#include</vp>, <vp>#bininclude </vp> - file inclusion.
* <vp>#if</vp>, <vp>#then</vp>, <vp>#else</vp>, <vp>#elseif</vp>, <vp>#endif</vp> - conditional statements.
* <vp>#export</vp>, <vp>#externally</vp> - exporting and importing classes.
* <vp>#message</vp>, <vp>#error</vp>, <vp>#requires</vp>, <vp>#orrequires</vp> - compilation time information.
* <vp>#options</vp> - compiler options.

=== Source File Inclusion ===

The <vp>#include</vp> compiler directive is used to include the contents of another file into your program source code during compilation. It has the following syntax:

<vipbnf><Pp_dir_include> :
#include <String_literal></vipbnf>

The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename.

<vipbnf>#include "pfc\\exception\\exception.ph" % Includes pfc\exception\exception.ph file</vipbnf>

<vipbnf>#include @"pfc\vpi\vpimessage\vpimessage.ph" % Includes pfc\vpi\vpimessage\vpimessage.ph</vipbnf>

This compiler directive uses "include the first file occurrence only" semantics. That is, if a compilation unit contains several include directives for the same file, it will be included only one time with the first include directive.

Each included file must contain several accomplished scopes; an included file cannot contain uncompleted scopes. That is, it should contain several accomplished interface declarations, class declarations, class implementations or/and several compiler directives.

The compiler tries to find the specified include source file in the following way:

#If the filename contains an absolute path, then this file should be included.
#Otherwise, the compiler searches for the specified include filename among the paths that had been defined by the <vp>/Include</vp> command line option. These paths are handled consequently as they are specified in the option. In the IDE you can set these paths in the '''Include Directories''' in the '''Directories''' tab of the '''Project Settings''' dialog.

If the compiler does not find the specified file a compiling time error is generated.

=== Binary File Inclusion ===

The <vp>#bininclude</vp> compiler directive is used to include (during compilation) the contents of a file (specified by the {{lang2|Lexical_Elements|String_Literals|string_literal}} string) as a ::{{lang2|Built-in_entities|binary|binary}} type constant into your program source code. It has the following syntax:

<vipbnf><Pp_dir_bininclude> :
#bininclude ( <String_literal> )</vipbnf>

The <vp>#bininclude</vp> compiler directive instructs the compiler to insert the contents of the specified file as the value of a ::{{lang2|Built-in_entities|binary|binary}} constant. This directive can be used in any places where ::{{lang2|Built-in_entities|binary|binary}} constants are allowed.

The typical usage is like this:

<vip>constants
myBin : ::binary = #bininclude ("Bin.bin"). % Creates value of binary
% constant from "Bin.bin" file
myBin2 = #bininclude ("Bin2.bin"). % Short format of a binary
% constant initialization</vip>

In this example. Parsing the first constant <vp>myBin</vp> declaration, the compiler meets the <vp>#bininclude ("Bin.bin")</vp> directive. It checks whether the '''"Bin.bin"''' file exists in the directory where the source file containing this <vp>#bininclude ("Bin.bin")</vp> directive is placed or whether the '''"Bin.bin"''' file exists in one of directories specified in the '''Include Directories''' list box in the '''Project Settings''' dialog (in directories defined by the <vp>/Include</vp> command line option). If the compiler finds the '''"Bin.bin"''' file, then it reads it. From the file contents the compiler forms correct data of the ::{{lang2|Built-in_entities|binary|binary}} domain and place it as the <vp>myBin</vp> constant value. For example, if the '''"Bin.bin"''' file contains only one <vp>A</vp> character, then the <vp>myBin</vp> constant obtains the following value:

<vip>myBin = $[0x41] % Here 0x41 is the hexadecimal ASCII value of 'A'</vip>

The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename. The syntax is the same as in the <vp>#include</vp> compiler directive described in the previous paragraph {{lang2|Directives|Source_File_Inclusion|Source File Inclusions}}. The compiler tries to find the specified file in the same way as for <vp>#include</vp> compiler directive.

=== Exporting and Importing Classes ===

Compiler directives <vp>#export</vp> and <vp>#externally</vp> are used to determine lists of exported and imported classes, respectively. They have the following syntax:

<vipbnf><Pp_dir_export> :
#export <ClassNames>-comma-sep-list
<Pp_dir_export> :
#externally <ClassNames>-comma-sep-list</vipbnf>

These compiler directives are applied only to classes {{lang|Classes|classNames}}, which do not construct objects.

They can be used only outside scopes; that is, they cannot be used inside declarations of interfaces and classes and they cannot be used inside implementations of classes.

By default, predicates within one executed module are hidden at runtime for all other executed modules. An <vp>#export</vp> compiler directive makes names of specified classes public outside the module in which they are declared (and implemented). Therefore, all predicates from this module declared in the classes (specified in an <vp>#export</vp> directive) become accessible while runtime from other executed modules.

Usually, an <vp>#export</vp> compiler directives can be used in projects, which target modules are DLLs. It enumerates classes declared in a DLL, which should be accessible to other modules that use this DLL.

If a compilation unit export some class, then this compilation unit should contain this class implementation.

Also an <vp>#export</vp> compiler directives can be used to specify {{lang2|Directives|Conditional_Compilation|condition}} expressions for <vp>#if</vp> compiler directives.

For example, let us suppose that somewhere in the beginning of a compilation unit the compiler has met the <vp>#export</vp> compiler directive like this:

<vip>#export className</vip>

Then the compiler, if in the subsequent code it meets an <vp>#if</vp> compiler directive with the same <vp>#export</vp> compiler directive used as the condition expression, for example like this:

<vip>#if #export className #then ... #endif </vip>

Then the compiler evaluates the <vp>#export</vp> condition expression as <vp>true</vp> and, hence, the compiler executes the <vp>#then</vp> branch of the conditional compilation directive.

For example, the following <vp>#export</vp> compiler directive with the subsequent <vp>#if</vp> conditional compilation compiler directive:

<vip>#export className
...
#if #export className #then #requires "some.pack" #endif</vip>

guaranty that the <vp>"some.pack"</vp> package will be included into the compilation unit.

From the other hand, if an <vp>#export</vp> compiler directive is not met by the compiler (somewhere in the compilation unit before the <vp>#if</vp> compiler directive, which uses the same <vp>#export</vp> compiler directive as the conditional expression), then the compiler evaluates this <vp>#export</vp> condition expression as <vp>false</vp>. Hence, the compiler will not execute the <vp>#then</vp> branch of the <vp>#if</vp> conditional compilation directive. That is, the single <vp>#if</vp> compiler directive without previous <vp>#export</vp> directive

<vip>#if #export className #then #requires "some.pack" #endif</vip>

does not requires to include the <vp>"some.pack"</vp> package.

An <vp>#externally</vp> compiler directive is counterpart to an <vp>#export</vp> compiler directive. An <vp>#externally</vp> compiler directive can be used instead of (and concurrently with) an <vp>IMPORTS</vp> directive in definition files. An <vp>#externally</vp> compiler directive enumerates classes, which are declared in a module but implemented in other modules. Therefore, the compiler will not produce errors when it detects such classes. The referenced classes can be implemented (and exported) in DLLs, which can be linked to the module at runtime.

The <vp>#export</vp> and <vp>#externally</vp> compiler directives can be used as <vpbnf><Condition></vpbnf> boolean expressions in {{lang2|Directives|Compiler_Directives|Conditional Directives}}.

For example, like this:

<vip>#if #export className #then #include "Some package.pack" #endif</vip>

=== Compile Time Information ===

Compiler directives <vp>#message</vp>, <vp>#requires</vp>, <vp>#orrequires</vp>, and <vp>#error</vp> can be used to issue user-defined messages into a listing file while compilation of project modules and to interrupt compilation.

These directives can be used either outside scopes (interface declaration, class declaration or class implementation), or inside scopes but outside sections. They have the following syntax:

<vipbnf><Pp_dir_message>: one of
#message <String_literal>
#error <String_literal>
#requires <String_literal> <Pp_dir_orrequires>-list-opt
#orrequires <String_literal></vipbnf>

When the compiler meets any of these directives, it generates the correspondent warning message and place the directive text into a ''listing file''.

A listing file name can be specified with the compiler directive:

<source lang="text">/listingfile:"FileName"</source>

Notice that no empty spaces can be used between the colon <vp>:</vp> (after <vp>/listinglile</vp>) and <vp>"FileName"</vp>.

By default the compiler does NOT generate informative messages for the <vp>#message</vp>, <vp>#requires</vp>, and <vp>#orrequires</vp> directives. You can switch generation of these informative messages ON specifying the compiler options:

<source lang="text">/listing:message
/listing:requires
/listing:ALL</source>

{{Example| In this case, when the compiler meets a directive like:

<vip>#message "Some message"</vip>

it will place the following text into the listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : information c062: #message "Some message"</source>
}}

The directive <vp>#requires</vp> (<vp>#orrequires</vp>) issues arbitrary user-defined messages about the needed source (object) files into a listing file. The <vp>#orrequires</vp> directive cannot be used alone: the <vp>#requires</vp> directive should immediately (separated with white spaces or comments only) precede it.

The directive <vp>#error</vp> always terminates the compilation and issues the user-defined error message like the following into a listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : error c080: #error "Compilation is interrupted"</source>

You can parse and analyze these messages and accept the required actions. For example, the VDE analyzes information printed by the <vp>#requires</vp> and <vp>#orrequires</vp> directives and automatically adds all needed PFC packages and standard libraries to the compiled project (See also the '''Handling Project Modules''' topic).

{{Example| The directives <vp>#requires</vp> and <vp>#orrequires</vp> can be used like this:

<vip>#requires @"\Common\Sources\CommonTypes.pack"
#orrequires @"\Common\Lib\CommonTypes.lib"
#orrequires @"\Common\Obj\Foreign.obj"
#if someClass::debugLevel > 0 #then
#requires @"\Sources\Debug\Tools.pack"
#orrequires @"\Lib\Debug\Tools.lib"
#else
#requires @"\Sources\Release\Tools.pack"
#orrequires @"\Lib\Release\Tools.lib"
#endif
#orrequires "SomeLibrary.lib"
#requires "SomePackage.pack"
#if someClass::debugLevel > 0 #then
#orrequires @"\Debug\SomePackage.lib"
#else
#orrequires @"\Release\SomePackage.lib"
#endif</vip>
}}

{{Example| The <vp>#message</vp> directive can be used like this:

<vip>#message "Some text"
#if someClass::someConstant > 0 #then
#message "someClass::someConstant > 0"
#else
#message "someClass::someConstant <= 0"
#endif
class someClass
#if ::compiler_version > 600 #then
#message "New compiler"
constants
someConstant = 1.
#else
#message "Old compiler"
constants
someConstant = 0.
#endif
end class someClass</vip>
}}

{{Example| The <vp>#error</vp> can be used like this:

<vip>#if someClass::debugLevel > 0 #then
#error "Debug version is not yet implemented"
#endif</vip>
}}

=== Compiler options directive ===

Compiler directive <vp>#options <string_literal></vp> affects the whole compilation unit. This directive should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates a warning message and ignores the directive.

The <vp><string_literal></vp> can only contain the following compiler options:

<vip>"/Warning"
"/Check"
"/NOCheck"
"/Optimize"
"/DEBug"
"/GOAL"
"/MAXErrors"
"/MAXWarnings"</vip>

Otherwise the compiler generates the error message for invalid option.
If there are several <vp>#options</vp> directives they are handled in the textual order.

=== Conditional Compilation ===

The conditional programming constructions are part of the Visual Prolog language. Only other compiler directives, {{lang2|Compilation_Units|Compilation_Units_and_Items|Compilation Units}}, and {{lang2|Program_Sections|Program_Sections|program sections}} (including empty) can be conditional. The following syntax is used:

<vipbnf><ConditionalItem> :
#if <Condition> #then <CompilationItem>-list-opt <ElseIfItem>-list-opt <ElseItem>-opt #endif</vipbnf>

<vipbnf><ElseIfItem> :
#elseif <Condition> #then <CompilationItem></vipbnf>

<vipbnf><ElseItem> :
#else <CompilationItem></vipbnf>

Here <vpbnf><Condition></vpbnf> can be any expression, which can be evaluated to fail or succeed during compilation time.

Each one conditional compilation statement must be in one file, that is, the compiler directives <vp>#if</vp>, <vp>#then</vp>, <vp>#elseif</vp> and <vp>#else</vp> (if present), <vp>#endif</vp> of the same level of nesting must be in one file.

During compilation the compiler evaluates the conditions, in order to determine which parts to include in the final program. Parts that are excluded from the final program are called the dead branches.

All branches of conditional compilation items are syntax checked and must be syntactically correct. That is, also the dead branches must be syntactically correct.

The compiler only calculates conditions on a need to know basis, i.e. it does not calculate conditions in dead branches.

A condition may not depend on any code, which is located textually inside the conditional statement.

The example below is '''illegal''' because the condition depends on the scope (and constant) which is declared inside the condition branch.

<vip>#if aaa::x > 7 #then % ERROR!
class aaa
constants
x = 3
end class aaa
#else
class aaa
constants
x = 23
end class aaa
#endif</vip>

Language Reference/Directives

2012-06-09T06:04:00Z

Alexander Doronin: /* Source File Inclusion */

{{languageReferenceNavbar|Directives}}

Each compiler directive starts from the <vp>#</vp> character. The following directives are supported:

* <vp>#include</vp>, <vp>#bininclude </vp> - file inclusion.
* <vp>#if</vp>, <vp>#then</vp>, <vp>#else</vp>, <vp>#elseif</vp>, <vp>#endif</vp> - conditional statements.
* <vp>#export</vp>, <vp>#externally</vp> - exporting and importing classes.
* <vp>#message</vp>, <vp>#error</vp>, <vp>#requires</vp>, <vp>#orrequires</vp> - compilation time information.
* <vp>#options</vp> - compiler options.

=== Source File Inclusion ===

The <vp>#include</vp> compiler directive is used to include the contents of another file into your program source code during compilation. It has the following syntax:

<vipbnf><Pp_dir_include> :
#include <String_literal></vipbnf>

The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename.

<vipbnf>#include "pfc\\exception\\exception.ph" % Includes pfc\exception\exception.ph file</vipbnf>

or prefix the filename with the <vp>@</vp> character, like this

<vipbnf>#include @"pfc\vpi\vpimessage\vpimessage.ph" % Includes pfc\vpi\vpimessage\vpimessage.ph</vipbnf>

This compiler directive uses "include the first file occurrence only" semantics. That is, if a compilation unit contains several include directives for the same file, it will be included only one time with the first include directive.

Each included file must contain several accomplished scopes; an included file cannot contain uncompleted scopes. That is, it should contain several accomplished interface declarations, class declarations, class implementations or/and several compiler directives.

The compiler tries to find the specified include source file in the following way:

#If the filename contains an absolute path, then this file should be included.
#Otherwise, the compiler searches for the specified include filename among the paths that had been defined by the <vp>/Include</vp> command line option. These paths are handled consequently as they are specified in the option. In the IDE you can set these paths in the '''Include Directories''' in the '''Directories''' tab of the '''Project Settings''' dialog.

If the compiler does not find the specified file a compiling time error is generated.

=== Binary File Inclusion ===

The <vp>#bininclude</vp> compiler directive is used to include (during compilation) the contents of a file (specified by the {{lang2|Lexical_Elements|String_Literals|string_literal}} string) as a ::{{lang2|Built-in_entities|binary|binary}} type constant into your program source code. It has the following syntax:

<vipbnf><Pp_dir_bininclude> :
#bininclude ( <String_literal> )</vipbnf>

The <vp>#bininclude</vp> compiler directive instructs the compiler to insert the contents of the specified file as the value of a ::{{lang2|Built-in_entities|binary|binary}} constant. This directive can be used in any places where ::{{lang2|Built-in_entities|binary|binary}} constants are allowed.

The typical usage is like this:

<vip>constants
myBin : ::binary = #bininclude ("Bin.bin"). % Creates value of binary
% constant from "Bin.bin" file
myBin2 = #bininclude ("Bin2.bin"). % Short format of a binary
% constant initialization</vip>

In this example. Parsing the first constant <vp>myBin</vp> declaration, the compiler meets the <vp>#bininclude ("Bin.bin")</vp> directive. It checks whether the '''"Bin.bin"''' file exists in the directory where the source file containing this <vp>#bininclude ("Bin.bin")</vp> directive is placed or whether the '''"Bin.bin"''' file exists in one of directories specified in the '''Include Directories''' list box in the '''Project Settings''' dialog (in directories defined by the <vp>/Include</vp> command line option). If the compiler finds the '''"Bin.bin"''' file, then it reads it. From the file contents the compiler forms correct data of the ::{{lang2|Built-in_entities|binary|binary}} domain and place it as the <vp>myBin</vp> constant value. For example, if the '''"Bin.bin"''' file contains only one <vp>A</vp> character, then the <vp>myBin</vp> constant obtains the following value:

<vip>myBin = $[0x41] % Here 0x41 is the hexadecimal ASCII value of 'A'</vip>

The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename. The syntax is the same as in the <vp>#include</vp> compiler directive described in the previous paragraph {{lang2|Directives|Source_File_Inclusion|Source File Inclusions}}. The compiler tries to find the specified file in the same way as for <vp>#include</vp> compiler directive.

=== Exporting and Importing Classes ===

Compiler directives <vp>#export</vp> and <vp>#externally</vp> are used to determine lists of exported and imported classes, respectively. They have the following syntax:

<vipbnf><Pp_dir_export> :
#export <ClassNames>-comma-sep-list
<Pp_dir_export> :
#externally <ClassNames>-comma-sep-list</vipbnf>

These compiler directives are applied only to classes {{lang|Classes|classNames}}, which do not construct objects.

They can be used only outside scopes; that is, they cannot be used inside declarations of interfaces and classes and they cannot be used inside implementations of classes.

By default, predicates within one executed module are hidden at runtime for all other executed modules. An <vp>#export</vp> compiler directive makes names of specified classes public outside the module in which they are declared (and implemented). Therefore, all predicates from this module declared in the classes (specified in an <vp>#export</vp> directive) become accessible while runtime from other executed modules.

Usually, an <vp>#export</vp> compiler directives can be used in projects, which target modules are DLLs. It enumerates classes declared in a DLL, which should be accessible to other modules that use this DLL.

If a compilation unit export some class, then this compilation unit should contain this class implementation.

Also an <vp>#export</vp> compiler directives can be used to specify {{lang2|Directives|Conditional_Compilation|condition}} expressions for <vp>#if</vp> compiler directives.

For example, let us suppose that somewhere in the beginning of a compilation unit the compiler has met the <vp>#export</vp> compiler directive like this:

<vip>#export className</vip>

Then the compiler, if in the subsequent code it meets an <vp>#if</vp> compiler directive with the same <vp>#export</vp> compiler directive used as the condition expression, for example like this:

<vip>#if #export className #then ... #endif </vip>

Then the compiler evaluates the <vp>#export</vp> condition expression as <vp>true</vp> and, hence, the compiler executes the <vp>#then</vp> branch of the conditional compilation directive.

For example, the following <vp>#export</vp> compiler directive with the subsequent <vp>#if</vp> conditional compilation compiler directive:

<vip>#export className
...
#if #export className #then #requires "some.pack" #endif</vip>

guaranty that the <vp>"some.pack"</vp> package will be included into the compilation unit.

From the other hand, if an <vp>#export</vp> compiler directive is not met by the compiler (somewhere in the compilation unit before the <vp>#if</vp> compiler directive, which uses the same <vp>#export</vp> compiler directive as the conditional expression), then the compiler evaluates this <vp>#export</vp> condition expression as <vp>false</vp>. Hence, the compiler will not execute the <vp>#then</vp> branch of the <vp>#if</vp> conditional compilation directive. That is, the single <vp>#if</vp> compiler directive without previous <vp>#export</vp> directive

<vip>#if #export className #then #requires "some.pack" #endif</vip>

does not requires to include the <vp>"some.pack"</vp> package.

An <vp>#externally</vp> compiler directive is counterpart to an <vp>#export</vp> compiler directive. An <vp>#externally</vp> compiler directive can be used instead of (and concurrently with) an <vp>IMPORTS</vp> directive in definition files. An <vp>#externally</vp> compiler directive enumerates classes, which are declared in a module but implemented in other modules. Therefore, the compiler will not produce errors when it detects such classes. The referenced classes can be implemented (and exported) in DLLs, which can be linked to the module at runtime.

The <vp>#export</vp> and <vp>#externally</vp> compiler directives can be used as <vpbnf><Condition></vpbnf> boolean expressions in {{lang2|Directives|Compiler_Directives|Conditional Directives}}.

For example, like this:

<vip>#if #export className #then #include "Some package.pack" #endif</vip>

=== Compile Time Information ===

Compiler directives <vp>#message</vp>, <vp>#requires</vp>, <vp>#orrequires</vp>, and <vp>#error</vp> can be used to issue user-defined messages into a listing file while compilation of project modules and to interrupt compilation.

These directives can be used either outside scopes (interface declaration, class declaration or class implementation), or inside scopes but outside sections. They have the following syntax:

<vipbnf><Pp_dir_message>: one of
#message <String_literal>
#error <String_literal>
#requires <String_literal> <Pp_dir_orrequires>-list-opt
#orrequires <String_literal></vipbnf>

When the compiler meets any of these directives, it generates the correspondent warning message and place the directive text into a ''listing file''.

A listing file name can be specified with the compiler directive:

<source lang="text">/listingfile:"FileName"</source>

Notice that no empty spaces can be used between the colon <vp>:</vp> (after <vp>/listinglile</vp>) and <vp>"FileName"</vp>.

By default the compiler does NOT generate informative messages for the <vp>#message</vp>, <vp>#requires</vp>, and <vp>#orrequires</vp> directives. You can switch generation of these informative messages ON specifying the compiler options:

<source lang="text">/listing:message
/listing:requires
/listing:ALL</source>

{{Example| In this case, when the compiler meets a directive like:

<vip>#message "Some message"</vip>

it will place the following text into the listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : information c062: #message "Some message"</source>
}}

The directive <vp>#requires</vp> (<vp>#orrequires</vp>) issues arbitrary user-defined messages about the needed source (object) files into a listing file. The <vp>#orrequires</vp> directive cannot be used alone: the <vp>#requires</vp> directive should immediately (separated with white spaces or comments only) precede it.

The directive <vp>#error</vp> always terminates the compilation and issues the user-defined error message like the following into a listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : error c080: #error "Compilation is interrupted"</source>

You can parse and analyze these messages and accept the required actions. For example, the VDE analyzes information printed by the <vp>#requires</vp> and <vp>#orrequires</vp> directives and automatically adds all needed PFC packages and standard libraries to the compiled project (See also the '''Handling Project Modules''' topic).

{{Example| The directives <vp>#requires</vp> and <vp>#orrequires</vp> can be used like this:

<vip>#requires @"\Common\Sources\CommonTypes.pack"
#orrequires @"\Common\Lib\CommonTypes.lib"
#orrequires @"\Common\Obj\Foreign.obj"
#if someClass::debugLevel > 0 #then
#requires @"\Sources\Debug\Tools.pack"
#orrequires @"\Lib\Debug\Tools.lib"
#else
#requires @"\Sources\Release\Tools.pack"
#orrequires @"\Lib\Release\Tools.lib"
#endif
#orrequires "SomeLibrary.lib"
#requires "SomePackage.pack"
#if someClass::debugLevel > 0 #then
#orrequires @"\Debug\SomePackage.lib"
#else
#orrequires @"\Release\SomePackage.lib"
#endif</vip>
}}

{{Example| The <vp>#message</vp> directive can be used like this:

<vip>#message "Some text"
#if someClass::someConstant > 0 #then
#message "someClass::someConstant > 0"
#else
#message "someClass::someConstant <= 0"
#endif
class someClass
#if ::compiler_version > 600 #then
#message "New compiler"
constants
someConstant = 1.
#else
#message "Old compiler"
constants
someConstant = 0.
#endif
end class someClass</vip>
}}

{{Example| The <vp>#error</vp> can be used like this:

<vip>#if someClass::debugLevel > 0 #then
#error "Debug version is not yet implemented"
#endif</vip>
}}

=== Compiler options directive ===

Compiler directive <vp>#options <string_literal></vp> affects the whole compilation unit. This directive should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates a warning message and ignores the directive.

The <vp><string_literal></vp> can only contain the following compiler options:

<vip>"/Warning"
"/Check"
"/NOCheck"
"/Optimize"
"/DEBug"
"/GOAL"
"/MAXErrors"
"/MAXWarnings"</vip>

Otherwise the compiler generates the error message for invalid option.
If there are several <vp>#options</vp> directives they are handled in the textual order.

=== Conditional Compilation ===

The conditional programming constructions are part of the Visual Prolog language. Only other compiler directives, {{lang2|Compilation_Units|Compilation_Units_and_Items|Compilation Units}}, and {{lang2|Program_Sections|Program_Sections|program sections}} (including empty) can be conditional. The following syntax is used:

<vipbnf><ConditionalItem> :
#if <Condition> #then <CompilationItem>-list-opt <ElseIfItem>-list-opt <ElseItem>-opt #endif</vipbnf>

<vipbnf><ElseIfItem> :
#elseif <Condition> #then <CompilationItem></vipbnf>

<vipbnf><ElseItem> :
#else <CompilationItem></vipbnf>

Here <vpbnf><Condition></vpbnf> can be any expression, which can be evaluated to fail or succeed during compilation time.

Each one conditional compilation statement must be in one file, that is, the compiler directives <vp>#if</vp>, <vp>#then</vp>, <vp>#elseif</vp> and <vp>#else</vp> (if present), <vp>#endif</vp> of the same level of nesting must be in one file.

During compilation the compiler evaluates the conditions, in order to determine which parts to include in the final program. Parts that are excluded from the final program are called the dead branches.

All branches of conditional compilation items are syntax checked and must be syntactically correct. That is, also the dead branches must be syntactically correct.

The compiler only calculates conditions on a need to know basis, i.e. it does not calculate conditions in dead branches.

A condition may not depend on any code, which is located textually inside the conditional statement.

The example below is '''illegal''' because the condition depends on the scope (and constant) which is declared inside the condition branch.

<vip>#if aaa::x > 7 #then % ERROR!
class aaa
constants
x = 3
end class aaa
#else
class aaa
constants
x = 23
end class aaa
#endif</vip>

Language Reference/Predicates

2012-05-29T03:20:33Z

Alexander Doronin: /* programPoint */

{{languageReferenceNavbar|Predicates}}

=== Predicates Sections ===

A predicates section declares a set of object or class predicates in the current scope.

<vipbnf><PredicatesSection> :
class-opt predicates <PredicateDeclaration>-dot-term-list-opt</vipbnf>

The keyword <vp>class</vp> can be used only inside class implementations, as predicates, declared in an interface, are always object predicates and predicates, declared in a class declaration, are always class predicates already.

The keyword <vp>class</vp> can be used only inside class implementations, since:
* predicates declared in an interface are always object predicates and
* predicates declared in a class declaration are always class predicates.

=== Predicate Declarations ===

The predicate declaration is used to declare the predicate in scopes in which the predicate declaration can be seen. When predicates are declared in an interface definition, this means that objects of the corresponding type must support these predicates. When predicates are declared in a class declaration, this means that the class publicly provides the declared predicates. And if predicates are declared in a class implementation, this means that the predicates are available locally. In all cases a corresponding definitions of the predicates must exist.

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt</vipbnf>

<vipbnf><LinkName> :
as <StringLiteral></vipbnf>

<vipbnf><PredicateName> :
<LowerCaseIdentifier></vipbnf>

Here {{lang2|Domains|Predicate Domains|predicateDomainName}} is the name of a predicate domain declared in the domains section.

A predicate declaration states the name of the predicate, its type, mode, flow (see {{lang2|Domains|Flow Pattern|predicate domains}}), and optionally a {{lang2|Domains|Calling Convention|link name}}.

Only class predicates can have link names. If the link name is not stated then a link name is derived from the predicate name, the way this name is derived depends on the calling convention.

If the calling convention is {{lang2|Domains|Calling Convention|apicall}} then the link name stated in the <vp>as</vp> clause is decorated anyway. If this decoration is unintended, use {{lang2|Domains|Calling Convention|stdcall}} instead.

==== Decorated ====

Sometimes a name must have the _...@N decoration, but the default from apicall is wrong. In such cases decorated, decoratedA and decoratedW can be used to control the decoration:

<vip>predicates
myPredicate : (string X) language stdcall as decorated.</vip>

In this case the link name will be "<vp>_MyPredicate@4</vp>", where apicall would make it "<vp>_MyPredicate</vp><vpbnf>W</vpbnf><vp>@4</vp>".

<vip>predicates
myPredicate : (pointer X) language stdcall as decoratedA.</vip>

In this case the link name will be "<vp>_MyPredicate</vp><vpbnf>A</vpbnf><vp>@4</vp>", where apicall would make it "<vp>_MyPredicate@4</vp>".

<vip>predicates
myPredicate : (pointer X) language stdcall as decoratedW.</vip>

In this case the link name will be "<vp>_MyPredicate</vp><vpbnf>W</vpbnf><vp>@4</vp>", where apicall would make it "<vp>_MyPredicate@4</vp>".

All of them change the start of the name from xxxx to _Xxxx and all of them put @N behind. The first never uses a suffix; the second always uses A and the third always uses W. This means that the programmer is responsible for deciding which suffix is needed. But he needs not to worry about calculating argument size and initial "_X".

=== Constructors Sections ===

A <vp>constructors</vp> section declares a set of constructors. The constructors belong to the scope in which the <vp>constructors</vp> section occurs (see {{lang2|Classes|Class Declarations|class declaration}} and {{lang2|Implementations|Class Implementations|class implementation}}).

<vipbnf><ConstructorsSection> :
constructors <ConstructorDeclaration>-dot-term-list-opt</vipbnf>

Constructor sections can only occur in declarations and implementations of classes that construct objects.

=== Constructor Declarations ===

A constructor declaration declares a named constructor of a class.

A constructor actually has two associated predicates:

*A class function, which returns a new constructed object.
*An object predicate, which is used when initializing inherited objects.

An associated constructor object predicate is used to perform an object initialization. This predicate can only be called from the constructor in the class itself and from a constructor in a class that inherits from the class (i.e. base class initialization).

<vipbnf><ConstructorDeclaration> :
<ConstructorName> : <PredicateDomain></vipbnf>

It is illegal to state a predicate mode for constructors, constructors always have <vp>procedure</vp> mode.

{{Example| Consider the following class:

<vip>class test_class : test
constructors
new : (integer Argument).
end class test_class</vip>

The associated class level predicate has the following signature:

<vip>class predicates
new : (integer) -> test.</vip>

Whereas the associated object level predicate has the following signature:

<vip>predicates
new : (integer).</vip>

Also consider the following implementation:

<vip>implement test2_class inherits test_class
clauses
new() :-
test_class::new(7), % invoke the base class constructor on "This"
p(test_class::new(8)). % create a new object of the base class and pass it to p(...)
...</vip>

The first call to <vp>test_class::new</vp> does '''''not''''' return a value, therefore it is a call to the non-function '''''object''''' version of the constructor. I.e. it is an invocation of the base class constructor on "<vp>This</vp>".

The second call on the other hand '''''does''''' return a value, therefore it is a call to the '''''class''''' function version of the constructor. I.e. we are creating a new object.
}}

=== Predicates from Interface ===

An interface can support a subset of another interface by stating the predicates in a predicates from section. The <vp>predicates</vp> <vp>from</vp> section names the interface and all supported predicates. The predicates are stated by name or by name and arity.

If an interface supports a subset of another interface it is neither subtype or super-type related to the other interface.

The important thing about the <vp>predicates</vp> <vp>from</vp> section is that the mentioned predicates retain their origin interface. Therefore:

*there will be no support conflict with any predicates from the origin interface;
*they can be inherited as the predicates from the origin interface.

<vipbnf><PredicatesFromInterface> :
predicates from <InterfaceName> <PredicateNameWithArity>-comma-sep-list-opt</vipbnf>

<vpbnf><PredicatesFromInterface></vpbnf> can only be used in interface definitions.

{{Example|
<vip>interface aaa
predicates
ppp : ().
qqq : ().
end interface aaa

interface bbb
predicates from aaa
ppp
predicates
rrr : ().
end interface bbb

interface ccc supports aaa, bbb
end interface ccc</vip>

Even though <vp>aaa</vp> and <vp>bbb</vp> both declare a predicate <vp>ppp</vp>, <vp>ccc</vp> can support them both without any conflicts, because <vp>ppp</vp> has <vp>aaa</vp> as an origin interface in all cases.
}}

{{Example|
<vip>interface aaa
predicates
ppp : ().
qqq : ().
end interface aaa

interface bbb
predicates from aaa
ppp
predicates
rrr : ().
end interface bbb

class aaa_class : aaa
end class aaa_class

class bbb_class : bbb
end class bbb_class

implement aaa_class inherits bbb_class
clauses
qqq().
end implement aaa_class</vip>

<vp>aaa_class</vp> can inherit <vp>ppp</vp> from <vp>bbb_class</vp>, because <vp>ppp</vp> in both classes has <vp>aaa</vp> as origin interface.
}}

=== Arity ===

A predicate that takes ''N'' arguments are said to be ''N-ary'', or to have arity ''N''. Predicates with different arity are always different predicates, even if they have the same name.

In most situations the arity of a predicate is obvious from the context in which the predicate is mentioned. But in, for example, {{lang2|Predicates|Predicates from Interface|predicatesFromInterface}} sections and {{lang2|Implementations|Resolve Qualification|resolve qualifications}} the arity is not obvious.

In order to distinguish between different arities of predicates in <vp>predicates from</vp> sections and in {{lang2|Implementations|Resolve Qualification|resolve qualifications}}, predicate names can (optionally) be stated with arity.

The following arities are possible:
*'''''Name/N''''' meaning an ordinary predicate (i.e. not a function) ''Name'' of arity ''N.''
*'''''Name/N->''''' meaning a function ''Name'' of arity ''N''.
*'''''Name/N...''''' meaning an ordinary predicate ''Name'' with ''N'' arguments followed by an <vpbnf><Ellipsis></vpbnf> argument (i.e. a varying number of arguments). (<vpbnf><Ellipsis></vpbnf> "..." can be used in predicate and predicate domain declarations as the last formal argument. In this case it means that the declared predicate (predicate domain) can have a variable number of arguments. Ellipsis flow must match an ellipsis argument and can therefore be only the last flow in the flow pattern.)
*'''''Name/N...->''''' meaning a function ''Name'' with ''N'' arguments followed by an ellipsis argument.

<vipbnf><PredicateNameWithArity> :
<PredicateName> <Arity>-opt</vipbnf>

<vipbnf><Arity> : one of
/ <IntegerLiteral> <Ellipsis>-opt
/ <IntegerLiteral> <Ellipsis>-opt -></vipbnf>

In ''Name/0...'' and ''Name/0...->.'' the zero is optional and can thus be written as ''Name/...'' and ''Name/...->'', respectively.

=== programPoint ===

{{Preliminary Documentation}}

A <vp>programPoint</vp> is a value that represents a specific point in a clause. The <vp>programPoint</vp> contains the class name, the predicate name, the source cursor (file, line and character number), the <vp>programPoint</vp> is defined in the <vp>core</vp> class

<vp>programPoint</vp>'s are used by the exception mechanism to indicate where exceptions are raised and continued, but the usage is not limited to that purpose.

The compiler suppors <vp>programPoint</vp>'s in a special way by means of the attribute <vp>programPoint</vp>, which can be added to a predicate declaration like this:

<vip>predicates
raiseAnException : (integer X) [programPoint].</vip>

Adding this attribute actually means that two predicates are declared, the one you have mentioned and an another one with name <vp>raiseAnException_explicit</vp> which in addition to the arguemnts of <vp>raiseAnException</vp> takes a <vp>programPoint</vp> as first argument:

<vip>predicates
raiseAnException : (integer X).

predicates
raiseAnException_explicit : (programPoint ProgramPoint, integer X).</vip>

When you call raiseAnException the compiler will actually create a program point ans call raiseAnException_explicit instead.

{{example|
<vip>clauses
test() :-
raiseAnException(17).</vip>
will actually correspond to:
<vip>clauses
test() :-
raiseAnException_explicit(programPoint(...), 17).
</vip>
where the program point corresponds to the point where <vp>raiseAnException</vp> is called in the <vp>test</vp> predicate.}}

If you have a programPoint you can directly call the explicit predicate with it.

{{example|
<vip>clauses
raiseAnExceptio17_explicit(ProgramPoint) :-
raiseAnException_explicit(ProgramPoint, 17).
</vip>
Typically, as in this example, explicit predicates will call other explicit predicates with the programPoint they receive in order to use an "original" call point in a nested explicit predicate.}}

Such code is treated in the usual way. I.e. when calling <vp>raiseAnException</vp> or <vp>raiseAnException_explicit</vp> will in both cases result in calling <vp>raiseAnException_explicit</vp>, so this is the only predicate that needs an implementation. In fact, it is illegal to state clauses for the non-explicit predicate that will never be called.

To summarize:
* A predicate declaration with programPoint attribute actually declares two predicates. A non-explicit and an explicit predicate.
* Calling the non-explicite predicate actually results in calling the explicit predicate with the call point as aditina argument.
* Only the explicit predicate should be implemented.

The introduction of the the programPoint feature simplifies the exception mechanism as known in Visual Prolog 7.3 and before. For example <vp>classInfo</vp> predicates are no longer needed (though they in Visual Prolog 7.4 are still legal but deprecated to ease transition).

Language Reference/Attributes

2011-10-28T10:57:49Z

Alexander Doronin:

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Attributes

2011-10-28T10:56:38Z

Alexander Doronin: /* Syntax */

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right before the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName> <ScopeQualifications> <Attributes>-opt <Sections> end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt <ScopeQualifications> <Attributes>-opt <Sections> end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>predicates
externalP : (point Point [byVal]) language apicall.</vip>
}}

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exist, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}

==== formatString ====

The argument is a {{lang2|Domains|Format Strings|format string}} for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).</vip>
}}

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The corresponding field is inlined instead of being pointed to.

{{Example|
<vip>domains
point = align 4
p(integer X, integer Y).

domains
rectangle = align 4
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
}}

It is also possible to inline fixed size string and string8 fields in structs:

{{Example|
<vip>domains
device = align 4
device(
integer Id,
string DeviceName [inline(32)]
).</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for local members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Built-in entities/Predicates

2011-07-06T07:09:03Z

Alexander Doronin: /* toAny */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]]
|Checks whether the variable ''VariableName'' has the domain ''domainName''.
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope's name.
|-
|[[#predicate_name|predicate_name/0->]]
|This compile time predicate returns the string ''PredicateName'' that represents the name of the predicate in which clause body <vp>predicate_name</vp> is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use <vp>try ... finally ... end try</vp> instead.
|-
| findall/3
| Use list comprehension <vp>[ ... || ... ]</vp> instead
|-
| trap/3 <vp>determ</vp>
| Use <vp>try ... catch V do ... end try</vp> instead
|}

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]]

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#Try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vip>hasDomain : (<type> Type, <variable> Variable) procedure.</vip>

<vp>hasDomain</vp> is not really a predicate, but more a declaration: It states that the variable <vp>Variable</vp> must have the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

<vip>not : (<term> SubGoal) determ.</vip>

Succeds if the <vp>SubGoal</vp> fails, and vice versa.

Call-template for this predicate is:

<vip>not(SubGoal)</vip>

The <vp>not</vp> succeeds if <vp>SubGoal</vp> fails when evaluated. Notice that SubGoal cannot bind any variables, because <vp>not(SubGoal)</vp> only succeeds if SubGoal fails (and a failing goal does not bind anything).

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock )</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> performs preliminary evaluation of <vp>InputTerm</vp> (if it is an expression), change current type to ''returnDomain'' type and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.

<noinclude>[[Category:Language Reference Subarticle]]</noinclude>

Visual Prolog 7.3 New Features

2010-10-16T04:03:12Z

Alexander Doronin: /* Build 7302 */

== Language ==

=== Generic Interfaces and Classes ===

See {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}.

=== Conversion to Generic Type ===

=== Monitors ===

{{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}

=== Must Unify Operator ===

New operator == (must-unify)

=== Universal term type ===

<vp>any</vp> and the predicate <vp>toAny/1-></vp>

=== 64 bit preparation ===

Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>

=== Foreign language interfacing ===

Native interfaces support (attributes):
* {{lang2|Attributes|inline|inline}}: Inline structures and strings.
* {{lang2|Attributes|union|union}}: Functor-less unions.
* {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.

External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
* They cannot have clauses
* explicit externally resolution is only legal when a DLL is stated

=== Other language features ===

* The precedence of unary minus is changed (so that power operator has higher precedence)
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed

New attributes
* {{lang2|Attributes|retired|retired}}
* {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}
* {{lang2|Attributes|used|used}}

Warnings:
* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm</vp>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

== IDE ==

=== Project tree ===

The project tree is redesigned and reimplemented. The functionality is more or less unchanged, but the performance is improved.

The '''IncludedIn''' and '''Includes''' windows has been moved to preview pane of project window.

It is now possible to have several packages with same name in a project (which can make much sense when using namespaces).

=== Browse dialog ===

The '''Browse''' dialog is improved in several smaller respects, including:
* It automatically jump to the 1st occurrence of search entity on locate
* The last dialog position is saved for next appearence

=== Find In Files ===

The '''Find In Files''' dialog is improved in several respects, including:
* result window is reused for subsequent searches
* F8 button for next match (Shift+F8 - previous)
* Prolog case sensitive search mode
* state is saved for next appearence

=== Namespace support ===

The '''Namespaces support''' is improved, so that forms, dialogs, etc can be places in namespaces when created.

=== IntelliSense ===

The '''IntelliSense''' feature is improved for better overview, speed typing and convenience of work.

=== Tab navigation dialog ===

The '''tab navigation''' dialog functionality has been extended:
* use ALT button for filtering [ReadOnly] windows
* use Del for closing windows

=== Go to Position on Clipboard ===

The '''Go to Position on Clipboard''' (Shift+F2) has been extended to accept a complete exception dump. F8 will go to the next stack entry.

=== Sorting in various windows ===

The Errors Window, the Break points Window, etc. has been extended with sorting capabilities (clicking on the top banner).
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

== Debugger ==

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

== PFC ==

=== New entities ===

* [[Collection library]]
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

=== Extensions and improvements ===

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq</vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

== Others ==

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore <vp>#requires</vp> directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

== Updates ==

=== Build 7301 ===

'''Visual Prolog 7.3, Build 7301''' fixes [http://kb.visual-prolog.com/fixes/fixes7300.htm#7301 several minor bugs].

The following new feature has been implemented:

* Built-in predicate <vp>toEllipsis : (any* Terms) -> ...</vp>
* The PFC '''treeControl''' has been extended with key down and drag-and-drop handling
* The set of examples for '''Personal Edition''' was extended
* The following GUI controls have been added to the Personal Edition: listViewControl, tabControl, and treeViewControl.

=== Build 7302 ===

'''Visual Prolog 7.3, Build 7302''' fixes [http://kb.visual-prolog.com/fixes/fixes7300.htm#7302 several minor bugs].

=== Build 7303 ===

'''Visual Prolog 7.3, Build 7303''' fixes several minor bugs.

== See also ==
[http://kb.visual-prolog.com/fixes/fixes7300.htm Bugs Fixed in Visual Prolog 7.3]

[[Visual Prolog 7.3 Upgrade Notes]]

[[Category:Release Notes]]

Visual Prolog 7.3 New Features

2010-06-16T09:26:56Z

Alexander Doronin: /* Build 7301 */

== Language ==

=== Generic Interfaces and Classes ===

See {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}.

=== Conversion to Generic Type ===

=== Monitors ===

{{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}

=== Must Unify Operator ===

New operator == (must-unify)

=== Universal term type ===

<vp>any</vp> and the predicate <vp>toAny/1-></vp>

=== 64 bit preparation ===

Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>

=== Foreign language interfacing ===

Native interfaces support (attributes):
* {{lang2|Attributes|inline|inline}}: Inline structures and strings.
* {{lang2|Attributes|union|union}}: Functor-less unions.
* {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.

External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
* They cannot have clauses
* explicit externally resolution is only legal when a DLL is stated

=== Other language features ===

* The precedence of unary minus is changed (so that power operator has higher precedence)
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed

New attributes
* {{lang2|Attributes|retired|retired}}
* {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}
* {{lang2|Attributes|used|used}}

Warnings:
* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm</vp>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

== IDE ==

=== Project tree ===

The project tree is redesigned and reimplemented. The functionality is more or less unchanged, but the performance is improved.

The '''IncludedIn''' and '''Includes''' windows has been moved to preview pane of project window.

It is now possible to have several packages with same name in a project (which can make much sense when using namespaces).

=== Browse dialog ===

The '''Browse''' dialog is improved in several smaller respects, including:
* It automatically jump to the 1st occurrence of search entity on locate
* The last dialog position is saved for next appearence

=== Find In Files ===

The '''Find In Files''' dialog is improved in several respects, including:
* result window is reused for subsequent searches
* F8 button for next match (Shift+F8 - previous)
* Prolog case sensitive search mode
* state is saved for next appearence

=== Namespace support ===

The '''Namespaces support''' is improved, so that forms, dialogs, etc can be places in namespaces when created.

=== IntelliSense ===

The '''IntelliSense''' feature is improved for better overview, speed typing and convenience of work.

=== Tab navigation dialog ===

The '''tab navigation''' dialog functionality has been extended:
* use ALT button for filtering [ReadOnly] windows
* use Del for closing windows

=== Go to Position on Clipboard ===

The '''Go to Position on Clipboard''' (Shift+F2) has been extended to accept a complete exception dump. F8 will go to the next stack entry.

=== Sorting in various windows ===

The Errors Window, the Break points Window, etc. has been extended with sorting capabilities (clicking on the top banner).
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

== Debugger ==

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

== PFC ==

=== New entities ===

* [[Collection library]]
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

=== Extensions and improvements ===

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq</vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

== Others ==

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore <vp>#requires</vp> directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

== Updates ==

=== Build 7301 ===

'''Visual Prolog 7.3, Build 7301''' fixes [http://kb.visual-prolog.com/fixes/fixes7300.htm#7301 several minor bugs].

The following new feature has been implemented:

* Built-in predicate <vp>toEllipsis : (any* Terms) -> ...</vp>
* The PFC '''treeControl''' has been extended with key down and drag-and-drop handling
* The set of examples for '''Personal Edition''' was extended
* The following GUI controls have been added to the Personal Edition: listViewControl, tabControl, and treeViewControl.

=== Build 7302 ===

'''Visual Prolog 7.3, Build 7302''' fixes several minor bugs.

== See also ==
[http://kb.visual-prolog.com/fixes/fixes7300.htm Bugs Fixed in Visual Prolog 7.3]

[[Visual Prolog 7.3 Upgrade Notes]]

[[Category:Release Notes]]

Visual Prolog 7.3 Upgrade Notes

2010-05-22T07:01:37Z

Alexander Doronin: /* apicall */

This document describes how to upgrade Visual Prolog 7.2 projects to Visual Prolog 7.3, for older projects you should also read [[Visual Prolog 7.2 Upgrade Notes]].

If you have problems with upgrading your projects and need additional information, you are welcome to ask questions in [http://discuss.visual-prolog.com/viewforum.php?f=2 Visual Prolog Discussion Forum].

By default, the installation of Visual Prolog 7.3 will not replace any previously installed versions. It is possible to work with several versions on a single computer.
* The Commercial Edition will by default be installed in '''C:\Program Files\Visual Prolog 7.3'''.
* The Personal Edition will by default be installed to '''C:\Program Files\Visual Prolog 7.3PE'''.

Visual Prolog 7.3 projects are backward-compatible with Visual Prolog 7.2 projects.
If you are going to use different versions of Visual Prolog installed at one computer, avoid opening projects by double-clicking on prj6 files.
Some changes might require automatic updates in Visual Prolog 7.2 projects. Therefore, it is recommended to make the project file (PRJ6) writable before the first build. Also, it is recommended to make copies for all project files first.

When your open a project in the Visual Prolog 7.3 IDE, it will automatically perform necessary updates of the project file. After this, it is recommended that you rebuild the entire project with the help of the '''Build | Rebuild All command''' and answer "Yes to All" to the messages suggesting adding or removing packages / modules.

== Manual updates ==

This section describes things that may need manual updates.

=== apicall ===

Predicates with <vp>apicall</vp> calling convention should not longer have <vp>resolve xxxx externally</vp> (but it is still legal to resolve such predicates from a DLL, i.e. they can have <vp>resolve xxxx externally from dll_name</vp>). The resolves that gives a compilation error should simply be deleted. Also, such predicates cannot anymore have clauses (therefore, the declared <vp>apicall</vp> calling convention should be changed).

=== Ambiguous null ===

Autogenerated COM code from older versions may give ambuguity errors for constructions like: <vp>uncheckedConvert(iXxxx_native, null)</vp> the ambiguity will disappear by gualifying <vp>null</vp> with <vp>::</vp>

<vip>uncheckedConvert(iXxxx_native, ::null)</vip>

== See also ==

* [[New Features in Visual Prolog 7.3]]
* [[Visual Prolog 7.2 Upgrade Notes]]

[[Category:Release Notes]]

Visual Prolog 7.3 New Features

2010-05-22T06:48:31Z

Alexander Doronin: /* Build 7301 */

== Language ==

=== Generic Interfaces and Classes ===

See {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}.

=== Conversion to Generic Type ===

=== Monitors ===

{{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}

=== Must Unify Operator ===

New operator == (must-unify)

=== Universal term type ===

<vp>any</vp> and the predicate <vp>toAny/1-></vp>

=== 64 bit preparation ===

Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>

=== Foreign language interfacing ===

Native interfaces support (attributes):
* {{lang2|Attributes|inline|inline}}: Inline structures and strings.
* {{lang2|Attributes|union|union}}: Functor-less unions.
* {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.

External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
* They cannot have clauses
* explicit externally resolution is only legal when a DLL is stated

=== Other language features ===

* The precedence of unary minus is changed (so that power operator has higher precedence)
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed

New attributes
* {{lang2|Attributes|retired|retired}}
* {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}
* {{lang2|Attributes|used|used}}

Warnings:
* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm</vp>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

== IDE ==

=== Project tree ===

The project tree is redesigned and reimplemented. The functionality is more or less unchanged, but the performance is improved.

The '''IncludedIn''' and '''Includes''' windows has been moved to preview pane of project window.

It is now possible to have several packages with same name in a project (which can make much sense when using namespaces).

=== Browse dialog ===

The '''Browse''' dialog is improved in several smaller respects, including:
* It automatically jump to the 1st occurrence of search entity on locate
* The last dialog position is saved for next appearence

=== Find In Files ===

The '''Find In Files''' dialog is improved in several respects, including:
* result window is reused for subsequent searches
* F8 button for next match (Shift+F8 - previous)
* Prolog case sensitive search mode
* state is saved for next appearence

=== Namespace support ===

The '''Namespaces support''' is improved, so that forms, dialogs, etc can be places in namespaces when created.

=== IntelliSense ===

The '''IntelliSense''' feature is improved for better overview, speed typing and convenience of work.

=== Tab navigation dialog ===

The '''tab navigation''' dialog functionality has been extended:
* use ALT button for filtering [ReadOnly] windows
* use Del for closing windows

=== Go to Position on Clipboard ===

The '''Go to Position on Clipboard''' (Shift+F2) has been extended to accept a complete exception dump. F8 will go to the next stack entry.

=== Sorting in various windows ===

The Errors Window, the Break points Window, etc. has been extended with sorting capabilities (clicking on the top banner).
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

== Debugger ==

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

== PFC ==

=== New entities ===

* [[Collection library]]
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

=== Extensions and improvements ===

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq</vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

== Others ==

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore <vp>#requires</vp> directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

== Updates ==

=== Build 7301 ===

'''Visual Prolog 7.3, Build 7301''' fixes several minor bugs.

The following new feature has been implemented:

* Built-in predicate <vp>toEllipsis : (any* Terms) -> ...</vp>
* The PFC '''treeControl''' has been extended with key down and drag-and-drop handling
* The set of examples for '''Personal Edition''' was extended

== See also ==
[http://kb.visual-prolog.com/fixes/fixes7300.htm Bugs Fixed in Visual Prolog 7.3]

[[Visual Prolog 7.3 Upgrade Notes]]

[[Category:Release Notes]]

Language Reference/Built-in entities/Predicates

2010-05-22T06:47:37Z

Alexander Doronin: /* toEllipsis */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_Name|class_Name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]]
|Checks whether the variable ''VariableName'' has the domain ''domainName''.
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope's name.
|-
|[[#predicate_name|predicate_name/0->]]
|This compile time predicate returns the string ''PredicateName'' that represents the name of the predicate in which clause body <vp>predicate_name</vp> is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use <vp>try ... finally ... end try</vp> instead.
|-
| findall/3
| Use list comprehension <vp>[ ... || ... ]</vp> instead
|-
| trap/3 <vp>determ</vp>
| Use <vp>try ... catch V do ... end try</vp> instead
|}

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]]

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_Name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#Try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vip>hasDomain : (<type> Type, <variable> Variable) procedure.</vip>

<vp>hasDomain</vp> is not really a predicate, but more a declaration: It states that the variable <vp>Variable</vp> must have the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

<vip>not : (<term> SubGoal) determ.</vip>

Succeds if the <vp>SubGoal</vp> fails, and vice versa.

Call-template for this predicate is:

<vip>not(SubGoal)</vip>

The <vp>not</vp> succeeds if <vp>SubGoal</vp> fails when evaluated. Notice that SubGoal cannot bind any variables, because <vp>not(SubGoal)</vp> only succeeds if SubGoal fails (and a failing goal does not bind anything).

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

This call equals to the call to built-in predicate [[#convert|convert/2->]]:

<vip>UniversalTypeValue = convert(any, Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock )</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> performs preliminary evaluation of <vp>InputTerm</vp> (if it is an expression), change current type to ''returnDomain'' type and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.

<noinclude>[[Category:Language Reference Subarticle]]</noinclude>

Language Reference/Built-in entities/Predicates

2010-05-22T06:46:21Z

Alexander Doronin: /* fromEllipsis */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_Name|class_Name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]]
|Checks whether the variable ''VariableName'' has the domain ''domainName''.
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope's name.
|-
|[[#predicate_name|predicate_name/0->]]
|This compile time predicate returns the string ''PredicateName'' that represents the name of the predicate in which clause body <vp>predicate_name</vp> is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use <vp>try ... finally ... end try</vp> instead.
|-
| findall/3
| Use list comprehension <vp>[ ... || ... ]</vp> instead
|-
| trap/3 <vp>determ</vp>
| Use <vp>try ... catch V do ... end try</vp> instead
|}

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]]

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_Name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#Try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vip>hasDomain : (<type> Type, <variable> Variable) procedure.</vip>

<vp>hasDomain</vp> is not really a predicate, but more a declaration: It states that the variable <vp>Variable</vp> must have the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

<vip>not : (<term> SubGoal) determ.</vip>

Succeds if the <vp>SubGoal</vp> fails, and vice versa.

Call-template for this predicate is:

<vip>not(SubGoal)</vip>

The <vp>not</vp> succeeds if <vp>SubGoal</vp> fails when evaluated. Notice that SubGoal cannot bind any variables, because <vp>not(SubGoal)</vp> only succeeds if SubGoal fails (and a failing goal does not bind anything).

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

This call equals to the call to built-in predicate [[#convert|convert/2->]]:

<vip>UniversalTypeValue = convert(any, Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ... EllipsisBlock.</vip>

This predicate creates ''EllipsisBlock'' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock )</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> performs preliminary evaluation of <vp>InputTerm</vp> (if it is an expression), change current type to ''returnDomain'' type and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.

<noinclude>[[Category:Language Reference Subarticle]]</noinclude>

Visual Prolog 7.3 New Features

2010-05-22T06:42:37Z

Alexander Doronin: /* Build 7301 */

== Language ==

=== Generic Interfaces and Classes ===

See {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}.

=== Conversion to Generic Type ===

=== Monitors ===

{{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}

=== Must Unify Operator ===

New operator == (must-unify)

=== Universal term type ===

<vp>any</vp> and the predicate <vp>toAny/1-></vp>

=== 64 bit preparation ===

Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>

=== Foreign language interfacing ===

Native interfaces support (attributes):
* {{lang2|Attributes|inline|inline}}: Inline structures and strings.
* {{lang2|Attributes|union|union}}: Functor-less unions.
* {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.

External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
* They cannot have clauses
* explicit externally resolution is only legal when a DLL is stated

=== Other language features ===

* The precedence of unary minus is changed (so that power operator has higher precedence)
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed

New attributes
* {{lang2|Attributes|retired|retired}}
* {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}
* {{lang2|Attributes|used|used}}

Warnings:
* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm</vp>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

== IDE ==

=== Project tree ===

The project tree is redesigned and reimplemented. The functionality is more or less unchanged, but the performance is improved.

The '''IncludedIn''' and '''Includes''' windows has been moved to preview pane of project window.

It is now possible to have several packages with same name in a project (which can make much sense when using namespaces).

=== Browse dialog ===

The '''Browse''' dialog is improved in several smaller respects, including:
* It automatically jump to the 1st occurrence of search entity on locate
* The last dialog position is saved for next appearence

=== Find In Files ===

The '''Find In Files''' dialog is improved in several respects, including:
* result window is reused for subsequent searches
* F8 button for next match (Shift+F8 - previous)
* Prolog case sensitive search mode
* state is saved for next appearence

=== Namespace support ===

The '''Namespaces support''' is improved, so that forms, dialogs, etc can be places in namespaces when created.

=== IntelliSense ===

The '''IntelliSense''' feature is improved for better overview, speed typing and convenience of work.

=== Tab navigation dialog ===

The '''tab navigation''' dialog functionality has been extended:
* use ALT button for filtering [ReadOnly] windows
* use Del for closing windows

=== Go to Position on Clipboard ===

The '''Go to Position on Clipboard''' (Shift+F2) has been extended to accept a complete exception dump. F8 will go to the next stack entry.

=== Sorting in various windows ===

The Errors Window, the Break points Window, etc. has been extended with sorting capabilities (clicking on the top banner).
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

== Debugger ==

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

== PFC ==

=== New entities ===

* [[Collection library]]
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

=== Extensions and improvements ===

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq</vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

== Others ==

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore <vp>#requires</vp> directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

== Updates ==

=== Build 7301 ===

'''Visual Prolog 7.3, Build 7301''' fixes several minor bugs.

The following new feature has been implemented:

* New built-in predicate <vp>toEllipsis : (any* Terms) -> ...</vp>
* The PFC '''treeControl''' has been extended with key down and drag-and-drop handling
* The set of examples for '''Personal Edition''' was extended

== See also ==
[http://kb.visual-prolog.com/fixes/fixes7300.htm Bugs Fixed in Visual Prolog 7.3]

[[Visual Prolog 7.3 Upgrade Notes]]

[[Category:Release Notes]]

Visual Prolog 7.3 New Features

2010-05-22T06:40:07Z

Alexander Doronin: /* Build 7301 */

== Language ==

=== Generic Interfaces and Classes ===

See {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}.

=== Conversion to Generic Type ===

=== Monitors ===

{{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}

=== Must Unify Operator ===

New operator == (must-unify)

=== Universal term type ===

<vp>any</vp> and the predicate <vp>toAny/1-></vp>

=== 64 bit preparation ===

Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>

=== Foreign language interfacing ===

Native interfaces support (attributes):
* {{lang2|Attributes|inline|inline}}: Inline structures and strings.
* {{lang2|Attributes|union|union}}: Functor-less unions.
* {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.

External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
* They cannot have clauses
* explicit externally resolution is only legal when a DLL is stated

=== Other language features ===

* The precedence of unary minus is changed (so that power operator has higher precedence)
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed

New attributes
* {{lang2|Attributes|retired|retired}}
* {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}
* {{lang2|Attributes|used|used}}

Warnings:
* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm</vp>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

== IDE ==

=== Project tree ===

The project tree is redesigned and reimplemented. The functionality is more or less unchanged, but the performance is improved.

The '''IncludedIn''' and '''Includes''' windows has been moved to preview pane of project window.

It is now possible to have several packages with same name in a project (which can make much sense when using namespaces).

=== Browse dialog ===

The '''Browse''' dialog is improved in several smaller respects, including:
* It automatically jump to the 1st occurrence of search entity on locate
* The last dialog position is saved for next appearence

=== Find In Files ===

The '''Find In Files''' dialog is improved in several respects, including:
* result window is reused for subsequent searches
* F8 button for next match (Shift+F8 - previous)
* Prolog case sensitive search mode
* state is saved for next appearence

=== Namespace support ===

The '''Namespaces support''' is improved, so that forms, dialogs, etc can be places in namespaces when created.

=== IntelliSense ===

The '''IntelliSense''' feature is improved for better overview, speed typing and convenience of work.

=== Tab navigation dialog ===

The '''tab navigation''' dialog functionality has been extended:
* use ALT button for filtering [ReadOnly] windows
* use Del for closing windows

=== Go to Position on Clipboard ===

The '''Go to Position on Clipboard''' (Shift+F2) has been extended to accept a complete exception dump. F8 will go to the next stack entry.

=== Sorting in various windows ===

The Errors Window, the Break points Window, etc. has been extended with sorting capabilities (clicking on the top banner).
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

== Debugger ==

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

== PFC ==

=== New entities ===

* [[Collection library]]
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

=== Extensions and improvements ===

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq</vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

== Others ==

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore <vp>#requires</vp> directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

== Updates ==

=== Build 7301 ===

'''Visual Prolog 7.3, Build 7301''' fixes several minor bugs.

The following new feature has been implemented:

* Built-in predicate toEllipsis/1->
* The PFC ''treeControl'' has been extended with key down and drag-and-drop handling
* The set of examples for ''Personal Edition'' was extended

== See also ==
[http://kb.visual-prolog.com/fixes/fixes7300.htm Bugs Fixed in Visual Prolog 7.3]

[[Visual Prolog 7.3 Upgrade Notes]]

[[Category:Release Notes]]

Language Reference/Built-in entities/Predicates

2010-05-22T05:45:00Z

Alexander Doronin:

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_Name|class_Name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]]
|Checks whether the variable ''VariableName'' has the domain ''domainName''.
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope's name.
|-
|[[#predicate_name|predicate_name/0->]]
|This compile time predicate returns the string ''PredicateName'' that represents the name of the predicate in which clause body <vp>predicate_name</vp> is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use <vp>try ... finally ... end try</vp> instead.
|-
| findall/3
| Use list comprehension <vp>[ ... || ... ]</vp> instead
|-
| trap/3 <vp>determ</vp>
| Use <vp>try ... catch V do ... end try</vp> instead
|}

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]]

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_Name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#Try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (... EllipsisBlock) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vip>hasDomain : (<type> Type, <variable> Variable) procedure.</vip>

<vp>hasDomain</vp> is not really a predicate, but more a declaration: It states that the variable <vp>Variable</vp> must have the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

<vip>not : (<term> SubGoal) determ.</vip>

Succeds if the <vp>SubGoal</vp> fails, and vice versa.

Call-template for this predicate is:

<vip>not(SubGoal)</vip>

The <vp>not</vp> succeeds if <vp>SubGoal</vp> fails when evaluated. Notice that SubGoal cannot bind any variables, because <vp>not(SubGoal)</vp> only succeeds if SubGoal fails (and a failing goal does not bind anything).

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

This call equals to the call to built-in predicate [[#convert|convert/2->]]:

<vip>UniversalTypeValue = convert(any, Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ... EllipsisBlock.</vip>

This predicate creates ''EllipsisBlock'' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock )</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> performs preliminary evaluation of <vp>InputTerm</vp> (if it is an expression), change current type to ''returnDomain'' type and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.

<noinclude>[[Category:Language Reference Subarticle]]</noinclude>

Language Reference/Built-in entities/Predicates

2010-05-22T05:12:03Z

Alexander Doronin: /* toAny */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_Name|class_Name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#hasDomain|hasDomain/2]]
|Checks whether the variable ''VariableName'' has the domain ''domainName''.
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope's name.
|-
|[[#predicate_name|predicate_name/0->]]
|This compile time predicate returns the string ''PredicateName'' that represents the name of the predicate in which clause body <vp>predicate_name</vp> is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use <vp>try ... finally ... end try</vp> instead.
|-
| findall/3
| Use list comprehension <vp>[ ... || ... ]</vp> instead
|-
| trap/3 <vp>determ</vp>
| Use <vp>try ... catch V do ... end try</vp> instead
|}

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]]

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_Name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#Try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== hasDomain ====

<vip>hasDomain : (<type> Type, <variable> Variable) procedure.</vip>

<vp>hasDomain</vp> is not really a predicate, but more a declaration: It states that the variable <vp>Variable</vp> must have the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

<vip>not : (<term> SubGoal) determ.</vip>

Succeds if the <vp>SubGoal</vp> fails, and vice versa.

Call-template for this predicate is:

<vip>not(SubGoal)</vip>

The <vp>not</vp> succeeds if <vp>SubGoal</vp> fails when evaluated. Notice that SubGoal cannot bind any variables, because <vp>not(SubGoal)</vp> only succeeds if SubGoal fails (and a failing goal does not bind anything).

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

This call equals to the call to built-in predicate [[#convert|convert/2->]]:

<vip>UniversalTypeValue = convert(any, Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> performs preliminary evaluation of <vp>InputTerm</vp> (if it is an expression), change current type to ''returnDomain'' type and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.

<noinclude>[[Category:Language Reference Subarticle]]</noinclude>

Language Reference/Built-in entities/Predicates

2010-05-22T05:09:22Z

Alexander Doronin:

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_Name|class_Name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#hasDomain|hasDomain/2]]
|Checks whether the variable ''VariableName'' has the domain ''domainName''.
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope's name.
|-
|[[#predicate_name|predicate_name/0->]]
|This compile time predicate returns the string ''PredicateName'' that represents the name of the predicate in which clause body <vp>predicate_name</vp> is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use <vp>try ... finally ... end try</vp> instead.
|-
| findall/3
| Use list comprehension <vp>[ ... || ... ]</vp> instead
|-
| trap/3 <vp>determ</vp>
| Use <vp>try ... catch V do ... end try</vp> instead
|}

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]]

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_Name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#Try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== hasDomain ====

<vip>hasDomain : (<type> Type, <variable> Variable) procedure.</vip>

<vp>hasDomain</vp> is not really a predicate, but more a declaration: It states that the variable <vp>Variable</vp> must have the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

<vip>not : (<term> SubGoal) determ.</vip>

Succeds if the <vp>SubGoal</vp> fails, and vice versa.

Call-template for this predicate is:

<vip>not(SubGoal)</vip>

The <vp>not</vp> succeeds if <vp>SubGoal</vp> fails when evaluated. Notice that SubGoal cannot bind any variables, because <vp>not(SubGoal)</vp> only succeeds if SubGoal fails (and a failing goal does not bind anything).

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type [[#any|any]].

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

This call equals to the call to built-in predicate [[#convert|convert]]:

<vip>UniversalTypeValue = convert(any, Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.</vip>

Converts the string/binary representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> performs preliminary evaluation of <vp>InputTerm</vp> (if it is an expression), change current type to ''returnDomain'' type and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.

<noinclude>[[Category:Language Reference Subarticle]]</noinclude>

Language Reference/Built-in entities/Domains

2010-05-22T04:38:50Z

Alexander Doronin:

{|{{prettytable}}
|-
|[[#any|any]]
|Universal term type.
|-
|[[#char|char]]
|Wide (two-bytes) character.
|-
|[[#string|string]]
|Wide zero-terminated sequence of wide characters.
|-
|[[#string8|string8]]
|Zero-terminated sequence of ASCII (one-byte) characters.
|-
|[[#symbol|symbol]]
|Wide zero-terminated sequence of wide characters.
|-
|[[#binary|binary]]
|Sequence of bytes.
|-
|[[#binaryNonAtomic|binaryNonAtomic]]
|Sequence of bytes.
|-
|[[#integer|integer]]
|Integral signed integer number.
|-
|[[#integer64|integer64]]
|Integral signed integer number.
|-
|[[#unsigned|unsigned]]
|Integral unsigned integer number.
|-
|[[#unsigned64|unsigned64]]
|Integral unsigned integer number.
|-
|[[#real|real]]
|Float-pointing number.
|-
|[[#real32|real32]]
|Float-pointing number.
|-
|[[#pointer|pointer]]
|4-bytes pointer to a memory address.
|-
|[[#handle|handle]]
|4-bytes pointer to a memory address.
|-
|[[#boolean|boolean]]
|Boolean values.
|-
|[[#factDB|factDB]]
|Descriptors of named internal databases.
|-
|[[#compareResult|compareResult]]
|Values of comparison result.
|}

==== any ====

Universal term type.

<vip>any</vip>

The values of this domain are any terms. Such a value contains the reference to the term type library and a term itself.

==== char ====

Wide character.

<vip>char</vip>

The values of this domain are UNICODE characters. Implemented as 2 unsigned bytes.

Only assignment and comparison (in the lexicographical sense) operations are applied to the values of this domain. The image of a character has the following syntax:

<vipbnf><Char_image> :
' Char_value '
<Char_value> :
<Letter>
<Digit>
<Graphical_symbol>
\ <Escape_seq>
<Escape_seq>:
t
n
r
\
'
"
u HHHH</vipbnf>

In the syntax above <vpbnf><HHHH></vpbnf> correspond to 4 hexadecimal digits. Also, the backslash symbol and the single quote can be represented by an escape-sequence only.

==== compareResult ====

The compareResult is a built-in domain. It is used to define a comparison result. The built-in [[#compare/2->|compare]] predicate's result is compareResult domain.
<vip>domains
compareResult = less; equal; greater.
</vip>

==== string ====

Wide zero terminated sequence of wide characters.

<vip>string</vip>

A string is a sequence of UNICODE characters. It's implemented as a pointer to the wide zero-terminated array of wide characters. Only assignment and comparison (in the lexicographical sense) operations are applied to values of this domain.

In source code a string literal can be specified as a set of sequences of characters surrounded by the double quotes.

<vipbnf><StringLiteral>:
<StringLiteralPart>-list</vipbnf>

<vipbnf><StringLiteralPart> :
@" AnyCharacter-list-opt "
" CharacterValue-list-opt "</vipbnf>

A string literal consists of one or more <vpbnf><StringLiteralPart></vpbnf>'s, which are concatenated. <vpbnf><StringLiteralPart></vpbnf>'s starting with <vp>@</vp> does not use escape sequences, whereas <vpbnf><StringLiteralPart></vpbnf>'s without <vp>@</vp> uses the following escape sequences:

*<vp>\\</vp> representing <vp>\</vp>
*<vp>\t</vp> representing Tab-character
*<vp>\n</vp> representing newline-character
*<vp>\r</vp> representing carriage return
*<vp>\'</vp> representing single quote
*<vp>\"</vp> representing double quote
*<vp>\u</vp> followed by exactly four <vpbnf><HexadecimalDigit></vpbnf>'s representing the Unicode character corresponding to the digits.

The double quotes in the string can be represented by the escape-sequence only (the single quote can be represented both with an escape-sequence and a graphical symbol).

==== string8 ====

A term of the built-in <vp>string8</vp> domain is a sequence of ASCII (one-byte) characters. It is implemented as a pointer to the zero terminated array of ASCII characters. Only assignment and comparison for equality (in the lexicographical sense) operations are applied to the values of this domain. Currently no literals are allowed for this domain.

==== symbol ====

Wide zero terminated sequence of wide characters.

<vip>symbol</vip>

Similar to a string, a symbol is also a sequence of the UNICODE characters. It's implemented as a pointer to an entry in a symbol table that contains strings. The operations that can be applied to symbols are the same as for strings.

The image of a symbol is represented with a ''<string_literal>'' (any string surrounded by the double quotes).

Symbols and strings are largely interchangeable but they are stored differently. Symbols are kept in a look-up table and their addresses, rather than the symbols themselves, are stored to represent objects. This means that symbols can be matched very quickly and, if a symbol occurs repeatedly in a program, it can be stored very compactly. Strings are not kept in a look-up table. Visual Prolog examines strings character-by-character whenever they are to be matched.

==== binary ====

Sequence of N bytes.

<vip>binary</vip>

Values of this domain are used for holding binary data. A binary value is implemented as a pointer to the sequence of bytes that represents the contents of a binary term.

The length of a binary term is situated in the '''4 bytes''' immediately preceding this sequence of bytes. The 4 bytes contains:

<vip>TotalNumberOfBytesOccupiedByBinary = ByteLen + 4 </vip>

where <vp>ByteLen</vp> - is the length of the binary term and 4 is number of bytes occupied by size field.

Only assignment and comparison operations are applied to values of '''binary domain'''.

Two binary terms are compared in the following way:

*If they are of different sizes, the bigger is considered larger.
*Otherwise, they are compared byte by byte, as unsigned values. Comparison stops when two differing bytes are found and the result of their comparison is the result of the comparison of the binary terms. Two binary terms are equal if they have the same sizes and all bytes are equal.

The text syntax for binary images is determined by the <vpbnf><Binary></vpbnf> rules:

<vipbnf><Binary> :
$ [ <Byte_value>-comma-sep-list-opt ]
<Byte_value> :
<Expression></vipbnf>

Each ''expression'' should be calculate on compiling time and its value should be in the range from <vp>0</vp> to <vp>255</vp>.

==== binaryNonAtomic ====

Sequence of N bytes.

<vip>binaryNonAtomic</vip>

Same as [[#binary|binary]], but can contain pointer.

==== integer ====

Integral signed number.

<vip>integer</vip>

Values of this domain occupy 4 bytes. Arithmetic operations (<vp>+</vp>, <vp>-</vp>, <vp>/</vp>, <vp>*</vp>, <vp>^</vp>), comparison, assignment, [[#div/2->|div]], [[#mod/2->|mod]], [[#quot/2->|quot]], and [[#rem/2->|rem]] operations are applied to values of this domain.

The permitted number range is from <vp>-2147483648</vp> to <vp>2147483647</vp>.

The syntax for the <vp>integer</vp> literal is determined by the <vpbnf><Integer></vpbnf> rule:

<vipbnf><Integer> :
<Add_operation>-opt 0o <Oct_number>
<Add_operation>-opt <Dec_number>
<Add_operation>-opt 0x <Hex_number>
<Add_operation> :
+
-
<Oct_number> :
<Oct_digit>-list
<Oct_digit> : one of
0 1 2 3 4 5 6 7
<Dec_number> :
<Dec_digit>-list
<Dec_digit> : one of
<Oct_digit> 8 9
<Hex_number> :
<Hex_digit>-list
<Hex_digit> : one of
<Dec_digit> a b c d e f A B C D E F</vipbnf>

==== integer64 ====

Integral signed number.

<vip>integer64</vip>

Values of this domain occupy 8 bytes.

The permitted number range is from <vp>-2^63 = -9,223,372,036,854,775,808</vp> to <vp>2^63-1 = 9,223,372,036,854,775,807</vp>.

The syntax for <vp>integer64</vp> literal is the same as <vpbnf><Integer></vpbnf> rule.

The set of operations for <vp>integer64</vp> is similar to the one for <vpbnf><Integer></vpbnf>.

==== unsigned ====

Integral unsigned number.

<vip>unsigned</vip>

Values of this domain occupy 4 bytes. Arithmetic operations (<vp>+</vp>, <vp>-</vp>, <vp>/</vp>, <vp>*</vp>, <vp>^</vp>), comparison, assignment, {{lang2|Built-in entities|operators|div/2->}}, {{lang2|Built-in entities|operators|mod/2->}}, {{lang2|Built-in entities|operators|rem/2->}}, and {{lang2|Built-in entities|operators|quot/2->}} operations are applied to values of this domain.

The permitted number range is from <vp>0</vp> to <vp>4294967295</vp>.

The syntax for <vp>unsigned</vp> number images is the same as for <vp>integer</vp> numbers. The usage of minus sign (<vpbnf><UnaryMinus></vpbnf>) is not allowed for an image of an <vp>unsigned</vp> number.

==== unsigned64 ====

Integral unsigned number.

<vip>unsigned64</vip>

Values of this domain occupy 8 bytes.

The permitted number range is from <vp>0</vp> to <vp>2^64-1 = 18,446,744,073,709,551,615</vp>.

The syntax for <vp>unsigned64</vp> number images is the same as for <vp>integer64</vp> numbers. The usage of minus sign (<vpbnf><UnaryMinus></vpbnf>) is not allowed for an image of an <vp>unsigned64</vp> number.

The set of operations for <vp>unsigned64</vp> is similar to the one for <vpbnf><Unsigned></vpbnf>.

==== real ====

Float-pointing number.

<vip>real</vip>

Values of this domain occupy 8 bytes. This numerical real domain is introduced for the user's convenience only. All arithmetic, comparison, and assignment operations are applied to values of <vp>real</vp> domain.

The permitted number range is <vp>-1.7e+308</vp> to <vp>1.7e+308</vp>. Values from integral domains are automatically converted to real numbers when necessary.

The syntax for the floating-point number literal is determined by the <vpbnf><Real></vpbnf> rule:

<vipbnf><Real> :
<Add_operation>-opt <Fraction> <Exponent>-opt
<Fraction> :
<Dec_number> <Fractional_part>-opt
<Fractional_part> :
. <Dec_number>
<Exponent> :
<Exp> <Add_operation>-opt <Dec_number>
<Exp> :
e
E
<Add_operation> :
+
-
<Dec_number> :
<Dec_digit>-list
<Dec_digit> : one of
0 1 2 3 4 5 6 7 8 9</vipbnf>

==== real32 ====

Float-pointing number.

<vip>real32</vip>

Values of this domain occupy 4 bytes. This numerical <vp>real32</vp> domain is introduced for the user's convenience only. All arithmetic, comparison, and assignment operations can be applied to values of <vp>real32</vp> domain.

The permitted number range is <vp>-3.4e+38</vp> to <vp>3.4e+38</vp>.

The syntax of real32 literals is the same as <vp>real</vp> lietrals.

==== pointer ====

A pointer to a memory address.

<vip>pointer</vip>

A pointer directly corresponds to memory addresses. Only the equality operation can be applied to the values of this domain. There is a built-in '''null''' constant for this type

==== handle ====

A handle is used for Windows API function call. Values of this domain occupy 4 bytes.

There are no operations for this domain and cannot be converted (except uncheckedConvert) to/from other domains.

There is a built-in [[#nullHandle|nullHandle]] and [[#invalidHandle|invalidHandle]] constant for this type

==== boolean ====

Boolean values.

<vip>boolean</vip>

This domain is introduced for the user convenience only. It is treated as usual compound domain with the following definition:

<vip>domains
boolean = false(); true().</vip>

==== factDB ====

Descriptors of named internal databases.

<vip>factDB</vip>

This domain has the following hidden meta-declaration:

<vip>domains
factDB = struct @factdb( named_internal_database_domain, object ).</vip>

All user-defined names of facts sections are the constants of this domain. The compiler automatically builds the corresponding compound terms from such constants whenever it's in need. At the runtime the 1st field of this structure contains the address of the corresponding domain descriptor and the 2nd field contains either zero (for class facts sections) or pointer to an object (i.e. <vp>This</vp>, for object facts sections).

<noinclude>[[Category:Language Reference Subarticle]]</noinclude>

Language Reference/Domains

2010-05-22T04:15:41Z

Alexander Doronin:

{{languageReferenceNavbar|Domains}}

=== Domains Sections ===

A domain section defines a set of domains in the current scope (see {{lang|Interfaces|Interface}}, {{lang2|Classes|Class Declarations|Class Declaration}}, and {{lang2|Implementations|Class_Implementations|Class Implementation}}).

<vipbnf><DomainsSection>:
domains <DomainDefinition>-dot-term-list-opt</vipbnf>

=== Domain Definitions ===

A domain definition defines a named domain in the current scope.

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression></vipbnf>

If the domain on the right hand side denotes an interface or a compound domain, then the defined domain is synonym (i.e. identical) to the type expression. Otherwise the defined domain becomes a subtype of the domain denoted by the type expression. Here a domain name <vpbnf><DomainName></vpbnf> should be a {{lang2|Lexical_Elements|Identifiers|lower case identifier}}.

There are certain places where you must use a domain name rather than a type expression:

*as a declaration of a formal argument type;
*as a type of a constant or a fact variable;
*as a type in a list domain.

=== Type Expressions ===

A type expression denotes a type.

<vipbnf><TypeExpression>:
<TypeName>
<CompoundDomain>
<ListDomain>
<PredicateDomain>
<IntegralDomain>
<RealDomain>
<TypeVariable>
<TypeApplication></vipbnf>

==== Type Names ====

A type name is either an ''interface'' name or the name of a ''value domain''. We use the term ''value domain'' to specify domains whose elements are {{lang2|Basic_Concepts|Types|immutable}} (unchangeable). Here we can say that objects, belonging to domains correspondent to ''interface'' names, have mutable state and terms of any other domains are immutable. So actually value types are everything except object types. A type name (obviously) denotes the type corresponding to the name of an existing domain.

<vipbnf><TypeName>:
<InterfaceName>
<DomainName>
<ClassQualifiedDomainName></vipbnf>

<vipbnf><InterfaceName>:
<LowercaseIdentifier></vipbnf>

<vipbnf><DomainName>:
<LowercaseIdentifier></vipbnf>

<vipbnf><ClassQualifiedDomainName>:
<ClassName>::<DomainName></vipbnf>

<vipbnf><ClassName>:
<LowercaseIdentifier></vipbnf>

Here <vpbnf><InterfaceName></vpbnf> is an interface name, <vpbnf><DomainName></vpbnf> is a value domain name, and <vpbnf><ClassName></vpbnf> is a class name.

{{Example|
<vip>domains newDomain1 = existingDomain. newDomain2 = myInterface.</vip>

In this example the domain name <vp>existingDomain</vp> and the interface name <vp>myInterface</vp> are used to define new domains.
}}

==== Compound Domains ====

Compound domains (also known as algebraic data types) are used to represent lists, trees, and other tree structured values. In its simple forms compound domains are used to represent structures and enumeration values. Compound domains can have a recursive definition. They can also be mutually/indirectly recursive.

<vipbnf><CompoundDomain>:
<Alignment>-opt <FunctorAlternative>-semicolon-sep-list></vipbnf>

<vipbnf><Alignment>:
align <IntegralConstantExpression></vipbnf>

Here <vpbnf><IntegralConstantExpression></vpbnf> is an expression, which must be compile time evaluated to an integral value.

A compound domain declaration declares a list of functor alternatives with optional alignment. Alignment must be <vp>1</vp>, <vp>2</vp> or <vp>4</vp>.

If a compound domain consists of one functor alternative, then it is considered as structure and has representation, which is binary compatible with the appropriate structure in language C.

<vipbnf><FunctorAlternative>:
<FunctorName> <FunctorName> ( <FormalArgument>-comma-sep-list-opt )</vipbnf>

Here <vpbnf><FunctorName></vpbnf> is the name of a functor alternative it should be a {{lang2|Lexical_Elements|Identifiers|lower case identifier}}.

<vipbnf><FormalArgument>:
<TypeExpression> <ArgumentName>-opt</vipbnf>

Here <vpbnf><ArgumentName></vpbnf> can be any {{lang2|Lexical_Elements|Identifiers|upper case identifier}}. The compiler ignores it.

Compound domains have no subtype relations to any other domains.

If a domain is defined as being equal to a compound domain, then these two domains are synonym types rather than subtypes. Meaning that they are just two different names for the same type.

{{Example|
<vip>domains
t1 = ff(); gg(integer, t1).</vip>

<vp>t1</vp> is a compound domain with two alternatives. The first alternative is the null-ary functor <vp>ff</vp>, while the second alternative is the two-ary functor <vp>gg</vp>, which takes an {{lang2|Built-in_entities|integer|integer}} and a term of the domain <vp>t1</vp> itself as arguments. So the domain <vp>t1</vp> is recursively defined.

The following expressions are terms of the domain <vp>t1</vp>:

<vip>ff()
gg(77, ff())
gg(33, gg(44, gg(55, ff())))</vip>
}}

{{Example|
<vip>domains
t1 = ff(); gg(t2).
t2 = hh(t1, t1).</vip>

<vp>t1</vp> is a compound domain with two alternatives. The first alternative is the null-ary functor <vp>ff</vp>, while the second alternative is the unary functor <vp>gg</vp>, which takes a term of the domain <vp>t2</vp> as argument. <vp>t2</vp> is a compound domain with one alternative the functor <vp>hh</vp>, which takes two <vp>t1</vp> terms as argument. So the domains <vp>t1</vp> and <vp>t2</vp> are mutually recursive.

The following are terms in the domain <vp>t1</vp>:

<vip>ff()
gg(hh(ff(), ff()))
gg(hh(gg(hh(ff(), ff())), ff()))
ggg(hh(ff(), g(hh(ff(), ff()))))
gg(hh(gg(hh(ff(), ff())), gg(hh(ff(), ff()))))</vip>
}}

{{Example|

In this example <vp>t1</vp> and <vp>t2</vp> are synonym types.

<vip>domains
t1 = f(); g(integer).
t2 = t1.</vip>
}}

Normally, it is not necessary to use empty parenthesis after null-ary functors. But in a domain definition consisting only of a single null-ary functor, empty parenthesis are required to distinguish it from a synonym/subtype definition.

{{Example|
<vp>t1</vp> is a compound domain with a single null-ary functor, whereas <vp>t2</vp> is defined to be synonym to <vp>t1</vp>.

<vip>domains
t1 = f().
t2 = t1.</vip>
}}

==== List Domains ====

List domains represent sequences of values of a certain domain. Thus, all elements in a <vp>T</vp> list must be of type <vp>T</vp>.

<vipbnf><ListDomain>:
<TypeName> *</vipbnf>

<vp>T*</vp> is the type of lists of <vp>T</vp> elements.

The following syntax is used for lists:

<vipbnf><ListExpression>:
[ <Term>-comma-sep-list-opt ]
[ <Term>-comma-sep-list | <Tail> ]</vipbnf>

<vipbnf><Tail>:
<Term></vipbnf>

Here <vpbnf><Tail></vpbnf> is a term which should have a value of the <vpbnf><ListDomain></vpbnf> type. Each <vpbnf><Term></vpbnf> should be of {{lang2|Domains|Type_Names|typeName}} type.

Actually, lists are just compound domains with two functors: <vp>[]</vp> denoting the empty list and the mix-fix functor <vp>[HD|TL]</vp> denoting the list with head <vp>HD</vp> and tail <vp>TL</vp>. The head must be of the underlying element type, whereas the tail must be a list of relevant type.

Lists are however syntactically sugared.

<vp>[E1, E2, E3, ..., En | L ]</vp> is shorthand for <vp>[E1 |[ E2 |[ ...[ En | L ]...}}]</vp>

<vp>[E1, E2, E3, ..., En]</vp> is shorthand for <vp>[E1, E2, E3, ..., En |[}}</vp>, which in turn is shorthand for <vp>[E1 |[ E2 |[ ...[ En | [] ]...}}]</vp>

==== Predicate Domains ====

Values of a predicate domain are predicates with the same "signature", i.e. the same argument and return types, the same flow pattern and the same (or stronger) predicate mode.

A predicate that returns a value is called a '''''function''''', whereas a predicate that does not return a value is sometimes called an '''''ordinary''''' predicate, to stress that it is not a function.

<vipbnf><PredicateDomain>:
( <FormalArgument>-comma-sep-list-opt ) <ReturnArgument>-opt
<PredicateModeAndFlow>-list-opt <CallingConvention>-opt</vipbnf>

<vipbnf><FormalArgument>:
<PredicateArgumentType> <VariableName>-opt
<Ellipsis></vipbnf>

<vipbnf><ReturnArgument>:
-> <FormalArgument></vipbnf>

<vipbnf><PredicateArgumentType>:
<TypeName>
<AnonymousIdentifier></vipbnf>

<vipbnf><VariableName>:
<UpperCaseIdentifier></vipbnf>

Predicate domains can have <vpbnf><Ellipsis></vpbnf> argument as the last <vpbnf><FormalArgument></vpbnf> in the <vpbnf><FormalArgument>-comma-sep-list</vpbnf>.

Predicate domains can have <vpbnf><AnonymousIdentifier></vpbnf> as a {{lang2|Domains|Type_Expressions|predicateArgumentType}} to specify that the argument can be of any type.

Currently, predicate domains with ellipsis can only be used in predicate declarations.

Predicate domains that are used in domain definitions can at most state one flow.

<vipbnf><PredicateModeAndFlow>:
<PredicateMode>-opt
<FlowPattern>-list-opt</vipbnf>

===== Predicate Mode =====

The specified predicate mode applies for each member of a flow pattern list following it.

<vipbnf><PredicateMode>: one of
erroneous
failure
procedure
determ
multi
nondeterm</vipbnf>

Predicate modes can be described by the following sets:

<vip>erroneous = {}
failure = {Fail}
procedure = {Succeed}
determ = {Fail, Succeed}
multi = {Succeed, BacktrackPoint}
nondeterm = {Fail, Succeed, BacktrackPoint}</vip>

If ''Fail'' is in the set it means that the predicate can fail. If ''succeed'' is in the set it means that the predicate can succeed. If ''BacktrackPoint'' is in the set it means that the predicate can return with an active backtrack point in it.

If such a set, say <vp>failure</vp>, is a subset of another set, say <vp>nondeterm</vp>, then we say that the mode is stronger than the other, i.e. <vp>failure</vp> is stronger than <vp>nondeterm</vp>.

A predicate domain actually contain all predicates (with correct type and flow), which have the mode specified or a '''''stronger''''' mode.

It is illegal to state a predicate mode for constructors, they always have the <vp>procedure</vp> mode.

Omitting of a predicate mode means <vp>procedure</vp>.

Omitting of flows means that all arguments are input.

Notice that, in difference to Visual Prolog v. 5.x, inside implementations (i.e. for a local predicates) the needed flows and modes '''are NOT derived from the usages of the predicate'''. Now in declarations of for local predicates omitting the predicate mode means <vp>procedure</vp> and omitting flows means that all arguments are input.

If inside an implementation you do not want to specify all possible flows of a predicate usage explicitly, you still can deliver this duty to the compiler. For this task inside class implementations you can use the special flow pattern <vp>anyflow</vp>. In this case the compiler during the compilation will derive the needed flows from usages of the predicate. But if the optional preceding predicate mode is omitted before the <vp>anyflow</vp> flow pattern, then the <vp>procedure mode</vp> is always assumed.

===== Flow Pattern =====

The flow pattern defines the input/output direction of the arguments, which in combination with functor domains can be structures with parts of a single argument being input and other parts of the same argument being output.

A flow pattern consists of a sequence of flows, each flow corresponds to an argument (fist flow to first argument, etc).

<vipbnf><FlowPattern>:
( <Flow>-comma-sep-list-opt ) AnyFlow</vipbnf>

<vipbnf><Flow>: one of
i
o
<FunctorFlow>
<ListFlow>
<Ellipsis></vipbnf>

Ellipsis flow must match an ellipsis argument and can therefore be only the last flow in the flow pattern.

<vipbnf><Ellipsis>:
...</vipbnf>

A functor flow <vpbnf><FunctorFlow></vpbnf> states a functor and flows of each of the components of that flow. The functor must of course be in the domain of the corresponding argument.

<vipbnf><FunctorFlow>:
<FunctorName> ( <Flow>-comma-sep-list-opt )</vipbnf>

A functor flow declaration cannot contain ellipsis flow.

List flows are just like functor flows, but with the same syntactic sugaring as the list domain.

<vipbnf><ListFlow>:
[ <Flow>-comma-sep-list-opt <ListFlowTail>-opt]</vipbnf>

<vipbnf><ListFlowTail>:
| <Flow></vipbnf>

A list flow cannot contain ellipsis flow.

When declaring a predicate the flow can be omitted. Inside an implementation (i.e. for a local predicate) the needed flows are derived from the usages of the predicate. Inside an interface or a class declaration (i.e. for a public predicate) omitting flows means that all arguments are input.

Special flow pattern <vp>anyflow</vp> can be stated only in declarations of local predicates (i.e. in predicate declarations inside the implementation of a class). It means that the exact flow pattern will be evaluated during the compilation. If the optional preceding predicate mode is omitted for this flow pattern, then it assumes to be a <vp>procedure</vp>.

{{Example|
<vip>domains
pp1 = (integer Argument1).</vip>

<vp>pp1</vp> is a predicate domain. The predicates that have type <vp>pp1</vp> takes one {{lang2|Built-in_entities|integer|integer}} argument. Since no flow-pattern is stated the argument is input, and since no predicate mode is mentioned the predicates are <vp>procedure</vp>.
}}

{{Example|
<vip>domains
pp2 = (integer Argument1) -> integer ReturnType.</vip>

Predicates of type <vp>pp2</vp> take one {{lang2|Built-in_entities|integer|integer}} argument and returns a value of type {{lang2|Built-in_entities|integer|integer}}. Therefore, <vp>pp2</vp> is actually a function domain and the predicates that have type <vp>pp2</vp> are actually functions. Since no flow-pattern is stated the argument is input and since no predicate mode is mentioned the predicates are <vp>procedure</vp>.
}}

{{Example|
<vip>predicates
ppp : (integer Argument1, integer Argument2) determ (o,i) (i,o) nondeterm (o,o).</vip>

The predicate <vp>ppp</vp> takes two {{lang2|Built-in_entities|integer|integer}} arguments. It exists in three flow variants: <vp>(o,i)</vp> and <vp>(i,o)</vp>, which are <vp>determ</vp>, and <vp>(o,o)</vp>, which is <vp>nondeterm</vp>.
}}

===== Calling Convention =====

The calling convention determines how arguments, etc. are passed to the predicate, it also determines how the link name is derived from a predicate name.

<vipbnf><CallingConvention>:
language <CallingConventionKind></vipbnf>

<vipbnf><CallingConventionKind>: one of
c stdcall apicall prolog</vipbnf>

If a calling convention is not stated, then the <vp>prolog</vp> convention is assumed. The <vp>prolog</vp> calling convention is the standard convention used for Prolog predicates.

The calling convention <vp>c</vp> follows the C/C++ standard calling convention. The link name of a predicate is created from the predicate name by adding a leading underscore (<vp>_</vp>).

The calling convention <vp>stdcall</vp> uses the <vp>c</vp> link name strategy but it uses the different argument and stack handling rules. The following table shows the implementation of <vp>stdcall</vp> calling convention:

{|{{prettytable}}
|-
!Feature
!Implementation
|-
|Argument-passing order
|Right to left.
|-
|Argument-passing convention
|By value, unless a compound domain term is passed. So it cannot be used to predicates with variable number of arguments.
|-
|Stack-maintenance responsibility
|Called predicate pops its own arguments from the stack.
|-
|Name-decoration convention
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|Case-translation convention
|No case translation of the predicate name is performed.
|}

The calling convention <vp>apicall</vp> uses the same argument and stack handling rules as <vp>stdcall</vp>, but for convenience to call MS Windows API functions <vp>apicall</vp> uses the naming conventions that are used by most MS Windows API functions. According to <vp>apicall</vp> naming conventions the link name of a predicate is constructed as follows:

*an leading underscore (<vp>_</vp>) is prefixed to the predicate name;
*the predicate name in which the first letter is changed in to a capital letter;
*the '<vp>A</vp>', the '<vp>W</vp>' or nothing is suffixed, if the arguments and the return type indicate an ANSI, Unicode or neutral predicate, respectively;
*the '<vp>@</vp>' is suffixed;
*the number of bytes pushed on the call stack is suffixed.

{{Example|
<vip>predicates
predicateName : (integer, string) language apicall</vip>

The argument types of this predicate indicates that it is a Unicode predicate (as {{lang2|Built-in_entities|string|string}} is the domain of Unicode strings). An {{lang2|Built-in_entities|integer|integer}} and a {{lang2|Built-in_entities|string|string}} each occupies 4 bytes on the call stack and, therefore, the link name becomes:

<source lang="text">_PredicateNameW@8</source>
}}

If <vp>apicall</vp> is used together with the "<vp>as</vp>" construction the name stated in the "<vp>as</vp>" construction is decorated in the same manner.

<vp>apicall</vp> can only be used directly in a predicate declaration, not in a predicate domain definition. In predicate domain definitions <vp>stdcall</vp>, must be used instead. A predicate declared with <vp>apicall</vp> calling convention cannot have clause(s) and it also cannot be resolved externally without explicit DLL name.

The following table compares implementations of <vp>c</vp>, <vp>apicall</vp>, and <vp>stdcall</vp> calling conventions (the <vp>prolog</vp> calling convention has the special implementation, which is not discussed here):

{|{{prettytable}}
|-
!Keyword
!Stack cleanup
!Predicate name case-translation
!Link predicate name decoration convention
|-
|<vp>c</vp>
|'''Calling''' predicate pops the arguments from the stack.
|None.
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|<vp>stdcall</vp>
|'''Called''' predicate pops its own arguments from the stack.
|None.
|An underscore (<vp>_</vp>) is prefixed to the predicate name.
|-
|<vp>apicall</vp>
|'''Called''' predicate pops its own arguments from the stack.
|The first letter of the predicate name is changed to the capital letter.
|An underscore (<vp>_</vp>) is prefixed to the name. The first letter is changed to the upper case. The '<vp>A</vp>', the '<vp>W</vp>' or nothing is suffixed. The sign <vp>@</vp> is suffixed. The (decimal) number of bytes in the argument list is suffixed.
|}

Visual Prolog notion of predicate domains covers both class and object members. Class members are handled straight forward, but the handling of object members requires attention. The invocation of an object predicate will get "back" in the context of the object to which the member belongs.

{{Example| Assume the following declarations:

<vip>interface actionEventSource
domains
actionListener = (actionEventSource Source) procedure (i).
predicates
addActionListener : (actionListener Listener) procedure (i).
... end interface</vip>

Also assume a class <vp>button_class</vp> which supports the <vp>actionEventSource</vp>. The event is sent when the button is pressed. In <vp>myDialog_class</vp> class, which implements a dialog, I create a button and I want to listen to its action events, so that I can react on button presses:

<vip>implement myDialog_class
clauses
new() :-
OkButton = button_class::new(...),
OkButton:addActionListener(onOk),
...
facts
okPressed : () determ.
predicates
onOk : actionListener.
clauses
onOk(Source) :-
assert(okPressed()).
end implement</vip>

The important thing about the example is that <vp>onOk</vp> is an object member and that, when the button is pressed, the invocation of the registered <vp>onOk</vp> will bring us back in the object that owns <vp>onOk</vp>. This means that we have access to the object fact <vp>okPressed</vp>, so that we can assert it.
}}

===== Format Strings =====

A formal parameter to a predicate can be marked as format string using the attribute {{lang2|Attributes|formatString|formatString}}. The format string can contain ordinary characters which are printed without modification, and format fields, that % begins with the percent '%' sign. If the percent sign is followed % by some unknown character (not the format specifier) - then % this character will be printed without modifications.

<vip>predicates
writef : (string Format [formatstring], ...) procedure (i,...).</vip>

The format fields specification is:

[-][0][width][.precision][type]

All fields are optional.

[-] Hyphen indicates that the field is to be left justified; right justified is the default. Having no effect when width value is not set, or the number of characters in the actual value is greater than width value.

[0] Zero before width means for values that zeros will be added until the minimum width is reached. If 0(zero) and -(hyphen) appear, the 0 is ignored

[width] Positive decimal number specifying a minimum field size. If the number of characters in the actual value is less than width value - then the required number of space ' ' characters will be added before the value (or after it, if '-' field was set). No changes occurs if number of characters in the actual value is greater than the width value.

[.precision] The point '.' with the following unsigned decimal number can specify either the precision of a floating-point image or the maximum number of characters to be printed from a string.

[type] Specifies other format then the default for the given. For example, in the type field, you can give a specifier that says an integer will be formatted as an unsigned. The possible values are:

:{|{{prettytable}}
|-
| f || Format real's in fixed-decimal notation (such as 123.4 or 0.004321). This is the default for real's.
|-
| e || Format real's in exponential notation (such as 1.234e+002 or 4.321e-003).
|-
| g || Format real's in the shortest of f and e format, but always in e format if exponent of the value is less than -4 or greater than or equal to the precision. Trailing zeros are truncated.
|-
| d or D || Format as a signed decimal number.
|-
| u or U || Format as an unsigned integer.
|-
| x or X || Format as a hexadecimal number.
|-
| o or O || Format as an octal number.
|-
| c || Format as a char.
|-
| B || Format as the Visual Prolog binary type.
|-
| R || Format as a database reference number.
|-
| P || Format as a procedure parameter.
|-
| s || Format as a string.
|}

==== Integral Domains ====

Integral domains are used for representing integral numbers. They are divided in two main categories for signed and unsigned numbers. Integral domains can also have different representation size. The predefined domains {{lang2|Built-in_entities|integer|integer}} and {{lang2|Built-in_entities|unsigned|unsigned}} represent signed and unsigned numbers with natural representation length for the processor architecture (i.e. 32bit on a 32bit machine, etc).

<vipbnf><IntegralDomain>:
<DomainName>-opt <IntegralDomainProperties></vipbnf>

If a <vpbnf><DomainName></vpbnf> is stated in front of the <vpbnf><IntegralDomainProperties></vpbnf>, then this domain must itself be an integral domain and the resulting domain will be child-type (i.e. subtype) of this domain. In that case <vpbnf><IntegralDomainProperties></vpbnf> may not violate the possibility of being a subtype, i.e. the range cannot be extended and the size cannot be changed.

<vipbnf><IntegralDomainProperties>:
<IntegralSizeDescription> <IntegralRangeDescription>-opt
<IntegralRangeDescription> <IntegralSizeDescription>-opt

<IntegralSizeDescription>:
bitsize <DomainSize>

<DomainSize>:
<IntegralConstantExpression></vipbnf>

An integral size description declares the size <vpbnf><DomainSize></vpbnf> of the integral domain, measured in bits. The compiler implement such representation to the integral domain, which has no less than the specified number of bits. The value of <vpbnf><DomainSize></vpbnf> should be positive and no greater than the maximal value supported by the compiler.

If integral size description is omitted, then it will become the same as the parent domain. If there is no parent domain, it will become the natural size for the processor.

<vipbnf><IntegralRangeDescription>:
[ <MinimalBoundary>-opt .. <MaximalBoundary>-opt ]

<MinimalBoundary>:
<IntegralConstantExpression>

<MaximalBoundary>:
<IntegralConstantExpression></vipbnf>

An integral range description declares the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits for the integral domain. If a limit is omitted, then the range of the parent domain is used. If there is no parent domain, then the <vpbnf><DomainSize></vpbnf> is used to determine respectively maximum or minimum value.

Notice that the specified minimum value should not exceed the specified maximum value. That is:

<vipbnf><MinimalBoundary> <= <MaximalBoundary></vipbnf>

Also the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits should satisfy the limits implied by the specified bit size <vp>bitsize</vp>.

The domain bit size <vpbnf><DomainSize></vpbnf> value and values of the minimal <vpbnf><MinimalBoundary></vpbnf> and the maximal <vpbnf><MaximalBoundary></vpbnf> limits must be calculated while compiling time.

==== Real Domains ====

Real domains are used to represent numbers with fractional parts (i.e. floating point numbers). Real domains can be used to represent very large and very small numbers. The built-in domain ''real'' have the natural precision for the processor architecture (or the precision given by the compiler).

<vipbnf><RealDomain>:
<DomainName>-opt <RealDomainProperties></vipbnf>

If a <vpbnf><DomainName></vpbnf> is stated in front of the <vpbnf><RealDomainProperties></vpbnf>, then this domain must itself be a real domain and the resulting domain will be a subtype of this domain. In that case <vpbnf><RealDomainProperties></vpbnf> may not violate the possibility of being a subtype, i.e. the range cannot be extended and the precision cannot be increased.

<vipbnf><RealDomainProperties>: one of
<RealPrecisionDescription> <RealRangeDescription>-opt
<RealRangeDescription> <RealPrecisionDescription></vipbnf>

<vipbnf><RealPrecisionDescription>:
digits <IntegralConstantExpression></vipbnf>

The real precision description declares precision of the real domain, measured in number of decimal digits. If precision is omitted then it will become the same as for the parent domain. If there is no parent domain, then it will be the natural precision for the processor or given by the compiler (in Visual Prolog v.6 the compiler limit is 15 digits). Precision have an upper and a lower limits given by the compiler, if the precisions larger than that limit is used the numbers will only obtain the processor (compiler) specified precision anyway.

<vipbnf><RealRangeDescription>:
[ <MinimalRealBoundary>-opt .. <MaximalRealBoundary>-opt ]

<MinimalRealBoundary>:
<RealConstantExpression>

<MaximalRealBoundary>:
<RealConstantExpression></vipbnf>

Here <vpbnf><RealConstantExpression></vpbnf> is an expression, which must be compile time evaluated to a floating point value. That is the real domain precision and limits must be calculated while compiling time.

The real range description declares minimal and maximal limits for the real domain. If a limit is omitted then it will be the same as for the parent domain. If there is no parent domain then the largest possible range for the precision will be used.

Notice that the specified minimum value should not exceed the specified maximum value. That is:

<vipbnf><MinimalBoundary> <= <MaximalBoundary></vipbnf>

==== Generic Domains ====

This section contains the formal syntax for generic domains, for a more complete introduction to generics please see the section ''''' Generics'''''.

<vipbnf><FormalTypeParameterList>:
<TypeVariable>-comma-sep-list-opt</vipbnf>

A formalTypeParameterList is a list of typeVariables

<vipbnf><TypeVariable>:
<UpperCaseIdentifier></vipbnf>

A <vpbnf><TypeVariable></vpbnf> is an upper case identifier. In a domain declaration the type variable must be bound in the <vpbnf><FormalTypeParameterList></vpbnf> on the left hand side of the domain definition. In a predicate declaration all free type variables are implicitly bound and scoped to that predicate declaration.

<vipbnf><TypeApplication>:
<TypeName> {<TypeExpression>-comma-sep-list-opt }</vipbnf>

A <vpbnf><TypeApplication></vpbnf> is the application of a {{lang2|Domains|Type_Names|typeName}} to a list of types. The type name must be generic and the number of formal type parameters must match the number of type expressions.

=== Universal and Root Types ===

Visual Prolog uses some internal types, called ''root'' types and ''universal'' types.

==== Universal Types ====

A number literal like <vp>1</vp> does not have any particular type, it can be used as a value of any type that contains <vp>1</vp>, including real types.

We say that <vp>1</vp> have a universal type. Having a universal type means that it have any type, which can represent its value.

Arithmetic operations also return universal types.

==== Root Types ====

Arithmetic operations are very liberal with their operand requirements: You can add integers of any integer domain with each other.

We say that arithmetic operands takes root types as arguments. The integer root type is super-type of any integer type (regardless that it is not mentioned in their declarations). Hence any integer type can be converted to the integer root type, and, since the arithmetic operations exist for the root types, it means one of them will work on any integer domains.

The actual number of root types and which operands exist is a matter of library facilities, and outside the scope of this document to describe.

Language Reference/Generic Interfaces and Classes

2010-04-06T04:49:11Z

Alexander Doronin: /* Example: Queue */

{{Preliminary Documentation}}

{{languageReferenceNavbar|Generic Interfaces and Classes}}

{{lang|Interfaces|Interfaces}} and {{lang|Classes|classes}} can be parametrized with type parameters so that they can be used in different instantiations in different contexts.

This section must be considered as an extension to the individual sections about:
* {{lang|Interfaces|Interfaces}}
* {{lang|Classes|Classes}}
* {{lang|Implementations|Implementations}}

The pragmatic reason to use generic classes and interfaces is to declare '''parametrized object facts''' and implement operations on these facts. As illustrated in the Queue example below.

=== Example: Queue ===

Consider this interface

<vip>interface queue_integer
predicates
insert : (integer Value).
tryGet : () -> integer Value.
end interface queue_integer</vip>

An object of this type is a queue of integers, if you replace "integer" with "string" you would have a type describing queues of strings.

A generic interface can be used to describe all such interfaces in a single interface definition:

<vip>interface queue{@Elem}
predicates
insert : (@Elem Value).
tryGet : () -> @Elem Value determ.
end interface queue</vip>

<vp>@Elem</vp> is a ''scope type variable'' (distinguished from local type variables by the <vp>@</vp>).

<vp>queue{integer}</vp> represents integer-queues; <vp>queue{string}</vp> represents string-queues; and so forth.

We can declare a generic queue class like this:

<vip>class queueClass{@Elem} : queue{@Elem}
end class queueClass</vip>

<vp>queueClass{@Elem}</vp> constructs objects type <vp>queue{@Elem}</vp> for any instantiation of <vp>@Elem</vp>.

The implementation can look like this:

<vip>implement queueClass{@Elem}
facts
queue_fact : (@Elem Value).
clauses
insert(Value) :-
assert(queue_fact(Value)).
clauses
tryGet() = Value :-
retract(queue_fact(Value)),
!.
end implement queueClass</vip>

This piece of code illustrates how to create an integer queue and insert an element in it:

<vip>..., Q = queueClass{integer}::new(), Q:insert(17), ...</vip>

It is not necessary to apply the type explicitly, instead the compiler can infer it from the context:

<vip>..., Q = queueClass::new(), Q:insert(17), ...</vip>

The compiler sees that <vp>Q</vp> must be an integer queue, because we insert 17 into it.

=== Generic Interfaces ===

==== Syntax ====

Generic interfaces have a list of type parameters:

<vipbnf><InterfaceDeclaration> :
interface <InterfaceName> { <ScopeTypeVariable>-comma-sep-list-opt } <ScopeQualifications> <Sections> end interface <InterfaceName>-opt
...

<ScopeTypeParameter> :
@ <UppercaseName></vipbnf>

The scope type parameters can be used in any declaration/definition in the interface.

==== Semantics ====

A generic interface defines all the interfaces that can be obtained by instantiating the type parameters with actual types. The scope type parameters from the opening are bound in the entire interface.

==== Restrictions ====

Then closing name should not have parameters:

<vip>interface xxx{@A}
...
end interface xxx % no parameters here</vip>

It is illegal to use same interface name for interfaces with different arity (in the same namespace):

<vip>interface xxx % xxx/0
...
end interface xxx

interface xxx{@A, @B} % error: Several classes, interfaces and/or namespaces have the same name 'xxx'
...
end interface xxx</vip>

Parameters can be used in supported interfaces:

<vip>interface xxx{@P} supports yyy{@P} % legal: @P is bound
...
end interface xxx

interface xxx supports yyy{@P} % illegal: @P must be bound
...
end interface xxx</vip>

Supported interfaces can be instantiated with any type expressions (as long as parameters are bound):

<vip>interface xxx{@A} supports yyy{integer, @A*}
...</vip>

=== Generic Classes ===

==== Syntax ====

Generic classes have a list of type parameters, and constructs objects of an interface type uses the these parameters.

<vipbnf><ClassDeclaration> :
class <ClassName> { <ScopeTypeVariable>-comma-sep-list-opt } <ConstructionType> <ScopeQualifications> <Sections> end class <ClassName>-opt
...

<ScopeTypeParameter> :
@ <UppercaseName>

<ConstructionType> :
: <TypeExpression></vipbnf>

The construction type must be generic (i.e. a generic interface).

==== Semantics ====

A generic class declares a class with a generic constructor. The type of the constructed object will be inferred from the usage of the constructor.

==== Restrictions ====

Then closing name should not have parameters:

<vip>class xxx{@A} : xxx{@AAA}
...
end class xxx % no parameters here</vip>

It is illegal to use same class name for class with different arity (in the same namespace):

<vip>class xxx % xxx/0
...
end class xxx

class xxx{@A} : yyy{@A} % error: Several classes, interfaces and/or namespaces have the same name 'xxx'
...
end class xxx</vip>

If a class and interface can have the same name, the class must construct objects of that interface.

<vip>interface xxx{@A}
...
end interface xxx

class xxx{@Q, @P} : object % error: Several classes, interfaces and/or namespaces have the same name 'xxx'
...
end class xxx</vip>

Parameters in the construction type, etc must be bound:

<vip>class bbb : xxx{@Q} % error: Free parameter '@Q' is used in type expression
...</vip>

All the parameters from the class must be used in the construction type:

<vip>class xxx{@P} : object % error: Unused type parameter '@P'
...</vip>

In class declarations scope parameter can only be used in constructors, domains and constants.

<vip>class xxx{@P} : xxx{@P}
domains
list = @P*. % legal
constants
empty : @P* = []. % legal
constructors
new : (@P Init). % legal
predicates
p : (@P X). % error: Scope parameter '@P' used in a class entity
end class xxx</vip>

=== Generic Implmentations ===

==== Syntax ====

Generic implementations have a list of type parameters.

<vipbnf><ClassImplementation> :
implement <ClassName> { <ScopeTypeVariable>-comma-sep-list-opt } <ScopeQualifications> <Sections> end implement <ClassName>-opt
...

<ScopeTypeParameter> :
@ <UppercaseName></vipbnf>

==== Semantics ====

A generic class declares a class with a generic constructor. The type of the constructed object will be inferred from the usage of the constructor.

==== Restrictions ====

Then closing name should not have parameters:

<vip>implement xxx{@A}
...
end implement xxx % no parameters here</vip>

The parameters must be the same as in the corresponding class declaration and have same order.

<vip>class xxx{@A} : aaa{@A}
...
end class xxx

implement xxx{@B} % error: The parameter '@B' is not the same as in the declaration '@A'
...
end implement xxx</vip>

In class implementations scope parameter can be used in constructors, domains, constants and in object entities (i.e. object facts, object predicates and object properties).

<vip>implement xxx{@P}
domains
list = @P*. % legal
constants
empty : @P* = []. % legal
constructors
new : (@P Init). % legal
predicates
op : (@P X). % legal
class predicates
cp : (@P X). % error: Scope parameter '@P' used in a class entity
facts
ofct : (@P). % legal
class facts
cfct : (@P). % error: Scope parameter '@P' used in a class entity
...
end implement xxx</vip>

Visual Prolog 7.3 New Features

2010-03-23T14:02:31Z

Alexander Doronin: /* Extensions and improvements */

{{Preliminary Documentation}}

__NOTOC__

=== Language ===

* {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}
** Conversion to generic type
* {{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}
* New operator == (must-unify)
* Universal term type <vp>any</vp> and the predicate <vp>toAny/1-></vp>
* The precedence of unary minus is changed (so that power operator has higher precedence)
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed
* Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* Native interfaces support (attributes):
** {{lang2|Attributes|inline|inline}}: Inline structures and strings.
** {{lang2|Attributes|union|union}}: Functor-less unions.
** {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.
* Other new attributes {{lang2|Attributes|retired|retired}}, {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}{{lang2|Attributes|used|used}}
* External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
** They cannot have clauses
** explicit externally resolution is only legal when a DLL is stated

==== New warnings ====

* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm</vp>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

=== IDE ===

* '''Project tree''' is redesigned and reimplemented
* '''IncludedIn''' and '''Includes''' windows is moved to preview pane of project window
* '''Browse''' dialog is improved (automatically jump to the 1st occurrence of search entity on locate, save the last dialog position, etc.)
* '''Find In Files''' dialog is improved (one result window, F8 for next, mixed case sensitive search mode, state is saved, etc.)
* '''Namespaces support''' is improved (it’s possible to put forms, etc. in a namespace)
* '''IntelliSense''' feature is strongly improved for typing speed and convenience of work
* Improved '''tab navigation''' dialog, use ALT button for filtering [ReadOnly] windows and Del for closing windows
* Simplify '''project creation''': Project Kinds (Console application, GUI application and DLL) instead of UI Strategy and Target Type
* '''Dump view''' improvements (Shift+F2)
* '''Sorting''' feature in Errors Window, Break points Window, etc
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

=== Debugger ===

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

=== PFC ===

==== New entities ====

* '''Collection library'''
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

==== Extensions and improvements ====

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq</vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

=== Others ===

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore #requires directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

[[Category:Release Notes]]

Visual Prolog 7.3 New Features

2010-03-23T14:01:52Z

Alexander Doronin: /* New warnings */

{{Preliminary Documentation}}

__NOTOC__

=== Language ===

* {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}
** Conversion to generic type
* {{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}
* New operator == (must-unify)
* Universal term type <vp>any</vp> and the predicate <vp>toAny/1-></vp>
* The precedence of unary minus is changed (so that power operator has higher precedence)
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed
* Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* Native interfaces support (attributes):
** {{lang2|Attributes|inline|inline}}: Inline structures and strings.
** {{lang2|Attributes|union|union}}: Functor-less unions.
** {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.
* Other new attributes {{lang2|Attributes|retired|retired}}, {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}{{lang2|Attributes|used|used}}
* External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
** They cannot have clauses
** explicit externally resolution is only legal when a DLL is stated

==== New warnings ====

* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm</vp>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

=== IDE ===

* '''Project tree''' is redesigned and reimplemented
* '''IncludedIn''' and '''Includes''' windows is moved to preview pane of project window
* '''Browse''' dialog is improved (automatically jump to the 1st occurrence of search entity on locate, save the last dialog position, etc.)
* '''Find In Files''' dialog is improved (one result window, F8 for next, mixed case sensitive search mode, state is saved, etc.)
* '''Namespaces support''' is improved (it’s possible to put forms, etc. in a namespace)
* '''IntelliSense''' feature is strongly improved for typing speed and convenience of work
* Improved '''tab navigation''' dialog, use ALT button for filtering [ReadOnly] windows and Del for closing windows
* Simplify '''project creation''': Project Kinds (Console application, GUI application and DLL) instead of UI Strategy and Target Type
* '''Dump view''' improvements (Shift+F2)
* '''Sorting''' feature in Errors Window, Break points Window, etc
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

=== Debugger ===

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

=== PFC ===

==== New entities ====

* '''Collection library'''
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

==== Extensions and improvements ====

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq<vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

=== Others ===

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore #requires directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

[[Category:Release Notes]]

Visual Prolog 7.3 New Features

2010-03-23T14:01:22Z

Alexander Doronin: /* New warnings */

{{Preliminary Documentation}}

__NOTOC__

=== Language ===

* {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}}
** Conversion to generic type
* {{lang|Monitors|Monitors}} with {{lang2|Monitors|Guards|guards}}
* New operator == (must-unify)
* Universal term type <vp>any</vp> and the predicate <vp>toAny/1-></vp>
* The precedence of unary minus is changed (so that power operator has higher precedence)
* New built-in predicate <vp>fromEllipsis : (...) -> any* Terms</vp>
* Runtime distinction between privately and publicly supported interfaces is removed
* Preparations for supporting 64bit systems: built-in types <vp>integerNative</vp> and <vp>unsignedNative</vp>
* Extended versions of built-in predicates <vp>toTerm/2-></vp> and <vp>tryToTerm/2-></vp> (type as the first parameter).
* Native interfaces support (attributes):
** {{lang2|Attributes|inline|inline}}: Inline structures and strings.
** {{lang2|Attributes|union|union}}: Functor-less unions.
** {{lang2|Attributes|byVal|byVal}}: Passing parameters by value.
* Other new attributes {{lang2|Attributes|retired|retired}}, {{lang2|Attributes|noDefaultConstructor|noDefaultConstructor}}{{lang2|Attributes|used|used}}
* External resolution is default for predicates declared with <vp>apicall</vp> calling convention.
** They cannot have clauses
** explicit externally resolution is only legal when a DLL is stated

==== New warnings ====

* Local object predicates which do not use <vp>This</vp> (and therefore can be declared as class predicates)
* Unused local constants
* Condition of foreach statement which has no backtrack point (i.e. mode is not <vp>multi</vp> or <vp>nondeterm<vp/>)
* <vp>unheckedConversion</vp>'s that would be illegal on 64 bit platforms (e.g. <vp>pointer</vp> -> <vp>integer</vp>)

=== IDE ===

* '''Project tree''' is redesigned and reimplemented
* '''IncludedIn''' and '''Includes''' windows is moved to preview pane of project window
* '''Browse''' dialog is improved (automatically jump to the 1st occurrence of search entity on locate, save the last dialog position, etc.)
* '''Find In Files''' dialog is improved (one result window, F8 for next, mixed case sensitive search mode, state is saved, etc.)
* '''Namespaces support''' is improved (it’s possible to put forms, etc. in a namespace)
* '''IntelliSense''' feature is strongly improved for typing speed and convenience of work
* Improved '''tab navigation''' dialog, use ALT button for filtering [ReadOnly] windows and Del for closing windows
* Simplify '''project creation''': Project Kinds (Console application, GUI application and DLL) instead of UI Strategy and Target Type
* '''Dump view''' improvements (Shift+F2)
* '''Sorting''' feature in Errors Window, Break points Window, etc
* '''Optimal Set of Includes improved''' (output, local scopes, etc.)

=== Debugger ===

* '''Highlighting''' changed values in variable window
* View of '''long lists''' improvement
* '''Speed''' of restarting is improved
* '''Memory break points''' and fact access (for some types)
* '''Multi-threaded''' application debugging is improved (thread names, break points handling)
* Multi-line '''tool tips'''

=== PFC ===

==== New entities ====

* '''Collection library'''
** Algebraic: <vp>redBlackSet</vp>, <vp>leftistPriorityQueue</vp>
** Modifiable: <vp>mapM_redBlack</vp>, <vp>priorityQueueM_leftist</vp>, <vp>queueM_fact</vp>, <vp>setM_redBlack</vp>
** Persistent: <vp>mapP_redBlack</vp>, <vp>priorityQueueP_leftist</vp>, <vp>queueP_fact</vp>, <vp>setP_redBlack</vp>
* <vp>varM</vp> modifiable variable
* <vp>linkControl</vp> PFC version of the Link common control
* <vp>richEditControl</vp> PFC version of the RichEdit common control
* <vp>treeControl</vp> PFC model based version of the TreeView common control
* <vp>gdiplus</vp> PFC version of GDI+
* <vp>cryptography</vp> hash, sha1, md5 & base64
* <vp>eventSource</vp> generalization of event notification/listening
* <vp>monitorQueue</vp> thread safe queue class based on the monitor facility
* <vp>reflection</vp> basic functionalty for code reflection
* <vp>inputStream_null</vp> & <vp>outputStream_null</vp> media-less streams (input is exhausted; outpt throws away)
* <vp>lZ_fileSystem_native</vp> Interface to Lempel-Ziv Decompression API functionality
* <vp>shell_api</vp> Api level interface to the Windows Shell
* <vp>winsock2_native</vp> native bindings to Windows Sockets 2

==== Extensions and improvements ====

* <vp>list</vp> package:
** speed: <vp>sort</vp>, <vp>removeDuplicate</vp>, <vp>drop</vp>, <vp>min</vp>/<vp>max</vp>, etc.)
** functionality: <vp>isMemberEq<vp> (and similar predicates) that uses a <vp>determ</vp> predicate as test
* <vp>listControl</vp> with owner-drawing capabilities
* <vp>uxTheme_native</vp> extended with the rest of the functions and the constants from vsStyle.h, etc.
* Add moving listener/responder to <vp>splitTwoControl</vp>
* Add the fraction handling from <vp>format</vp> to <vp>formatTime</vp>
* '''Speed''' improvements for:
** <vp>string</vp>
** <vp>fileName</vp>
** <vp>listViewControl</vp>
* <vp>string::rear/2-></vp> returns the rear part of a string
* '''Math''' package: predicates <vp>roundToInteger64/1-></vp> and <vp>roundToUnsigned64/1-></vp>
* Better handling of '''default button size'''
* <vp>msXLM_api</vp> update to version 6.0 of various COMponent classes

=== Others ===

* More efficient '''memory handling'''; using typed memory allocation for compound terms and internal facts chains
* Various optimizations for speed and size of generated code
* New Demo Examples (Commercial Edition only):
** Parser Generator
** LZDecompression
** TreeControlDemo
* Help on built-in entities
* VipBuilder: extra option to ignore #requires directives
* Extend '''Win32''' library (with more names from MS libraries).
* More context to consult exceptions
* Linker speed improvement
* Vault Integration updated to version 5.0.1

[[Category:Release Notes]]

Visual Prolog 7.2 Upgrade Notes

2008-10-21T07:15:15Z

Alexander Doronin: /* Upgrading Projects from Visual Prolog 7.1 to Visual Prolog 7.2 */

==Upgrading Projects from Visual Prolog 7.1 to Visual Prolog 7.2==
# By default, the installation of Visual Prolog 7.2 will not replace any previously installed versions. The new version will be installed by default to C:\Program Files\Visual Prolog 7.2. You can remove the previous version at any time you want or continue working with both. 
# Visual Prolog 7.2 projects are backward-compatible with Visual Prolog 7.1 projects. 
# If you are going to use different versions of Visual Prolog installed at one computer, avoid opening projects by double-clicking on prj6 files. 
# Some changes might require automatic updates in Visual Prolog 7.1 projects. Therefore, it is recommended to make the project file (PRJ6) writable before the first build. Also, it is recommended to make copies for all project files first. 
# After you open your project in Visual prolog 7.2 IDE, the IDE will automatically perform necessary updates. After this, it is recommended you rebuild the project with the help of the Build | Rebuild All command and answer "Yes to All" to the message "The new module is required to be added into the project". 

==Upgrading Projects from Visual Prolog 7.0 and Visual Prolog 6.x to Visual Prolog 7.2==

Depending on Visual Prolog version, you are upgrading your projects from, some additional actions might be required.

# Visual Prolog 7.2 projects are not fully backward-compatible with Visual Prolog 7.0 and Visual Prolog 6.x projects. Visual Prolog 7.0 and earlier IDE will not allow opening projects modified by Visual Prolog 7.1 IDE. It is recommended to create a backup copy of your project before opening it by the Visual Prolog 7.2 IDE. 
# If you are going to use Visual Prolog 7.2 simultaneously with Visual Prolog 7.0 or an earlier version at the same computer, it is recommended to switch the IDE setting "Open Project at Startup" in the previous version OFF, to prevent opening Visual Prolog 7.1 projects in the earlier IDE. Note that beginning with Visual Prolog 7.1, projects are not opened at startup, and, hence, the setting "Open Project at Startup" is not used anymore. 
# The following keywords were introduced: 
#* In Visual Prolog 7.1: '''properties, try, catch, finally, elseif.'''
#* In Visual Prolog 7.0:''' then''' '''else''' '''foreach''' ''' do'''That means that they can no longer be used as identifiers.
# Stronger treatment of types introduced in Visual Prolog 7.0 might require some changes in your program: typically change of declarations or insertions of explicit conversions might be necessary. 
# Reference domains are not supported since Visual Prolog 7.0. If your project uses reference domains, we recommend to read the "[http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project How To Erase Reference Domains from a Project]" tutorial. 
# G-stack is not used anymore since Visual Prolog 7.0. Hence, all G-stack related predicates have been removed. 
# Beginning with Visual Prolog 7.0 some accelerator keys have been changed to comply with Microsoft standards. 
# Predicates div and mod have changed their sense.In Visual Prolog 6.1
<vip>
-1 = -5 div 3
-2 = -5 mod 3
</vip>
Since Visual Prolog 6.2
<vip>
-2 = -5 div 3
+1 = -5 mod 3
</vip>
So, each file that contains div or mod in the projects created in Visual Prolog 6.1 should be checked, whether it works correctly.The simplest solution is to replace: div => quot
mod => remfor ALL source files.
## The format of specifying a fully-qualified (i.e. with an arity) predicate with a return value in resolve/delegate predicates from qualifications has been changed since Visual Prolog 6.2:: predicateName//N => predicateName/N->This might cause error messages while building your project in the latest version of Visual Prolog. Fix these errors to develop you project in the current version of Visual Prolog.

==Upgrading Projects from Visual Prolog 5.x==
Prolog Development Center provides the [http://www.visual-prolog.com/vip6/Product/migration.htm Migration Tool] that will assist you to migrate your Visual Prolog 5.x projects into Visual Prolog 6.x projects.

After migrating your projects into Visual Prolog 6.x, follow the recommendations above to upgrade your projects into the latest version of Visual Prolog.

Visual Prolog 7.2 New Features

2008-10-20T11:27:01Z

Alexander Doronin: /* vipBuilder */

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

<vp>integer64</vp> and <vp>unsigned64</vp> are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use <vp>integer64</vp> and <vp>unsigned64</vp> instead of <vp>core::integer64</vp> and <vp>core::unsigned64</vp>. So now (as example) file positions are <vp>unsigned64</vp>. The same is the case with <vp>gmtTimeValue</vp>, <vp>localTimeValue</vp> and <vp>timeIntervalValue</vp>.

=== Namespaces ===

Interfaces and classes can be put into namespaces (like <vp>pfc\pie</vp>). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So, now it is possible (for example) to have a class called <vp>file</vp> in the namespace <vp>documentManager</vp> even though there is also a class named <vp>file</vp> in PFC. It is planned in a future version of Visual Prolog to put PFC classes in namespaces <vp>pfc</vp>, <vp>pfc\vip5x</vp> and <vp>pfc\gui</vp>. Also there are new <vp>pie</vp> packages (described below) in the namespace <vp>pfc\pie</vp>.

=== binaryNonAtomic domain ===

A new built-in domain <vp>binaryNonAtomic</vp> is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary <vp>binary</vp> domain is no longer scanned for pointers.

=== real32 ===

A domain <vp>real32</vp> is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain <vp>handle</vp> which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: <vp>nullHandle</vp> and <vp>invalidHandle</vp>.

=== Compiler directive #options ===

A new compiler directive <vp>#options</vp> is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:

<vipbnf><OptionsDirective>:
#options <StringLiteral></vipbnf>

This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where <vp>qqq</vp> is declared like this:

<vip>predicates
qqq : (positive V). </vip>

The code above might seem reasonable, we only want to call <vp>qqq</vp> if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation <vp>X - 23</vp> gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:

<vip>clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).</vip>

If <vp>X - 23</vp> gives a negative number, the <vp>tryConvert</vp> will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types <vp>string</vp>, <vp>object</vp>, <vp>string8</vp> and <vp>symbol</vp> are not sub-types of type <vp>pointer</vp> any more.

=== Restrictions for delegate- sections order were removed ===

Now <vp>delegate</vp>- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to windows starting with the letters you have pressed. Also Ctrl-Del closes the open window.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

The dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file as well.

=== Welcome Page ===

The '''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

=== TODO Window ===

It is now possible to view all '''TODO comments''' (i.e. the comments like % TODO) in source files which can be rather convenient for developers. This feature is available via the Main menu: View | TODO

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate <vp>postAction</vp> on the <vp>window</vp> class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class <vp>popupWindow</vp> makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from <vp>pointer</vp> to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like <vp>object</vp> and <vp>symbol</vp>).

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate <vp>getFactChainLength_nd</vp> (in the <vp>profileMemory</vp> class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a <vp>determ</vp> predicate.

So in short a weak pointer is a pointer that will not keep memory alive. 

=== 5xChainDB8 ===

This package is introduced for compatibility support in order to handle old external databases (where strings are not in Unicode).

== Tools ==

=== vipBuilder ===

Some extra options has been added to '''vipBuilder''':
/genresource - also generate resourceIdentifiers.i
/compile <file_name> - compile the file <file_name>

=== coverageAnalysis ===

The '''coverage analysis''' gives information about which predicates that have been called during execution of the program. The coverage analysis program reads the '.deb' files to get information about the set of classes and predicates in the program and the coverage files to get information about which predicates that have been called during execution of the program. The program must be compiled with options '''/profile:min''' and '''/debug:full''' to use this new tool.

Visual Prolog 7.2 New Features

2008-10-20T07:20:47Z

Alexander Doronin: /* Window Navigation Dialog */

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

<vp>integer64</vp> and <vp>unsigned64</vp> are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use <vp>integer64</vp> and <vp>unsigned64</vp> instead of <vp>core::integer64</vp> and <vp>core::unsigned64</vp>. So now (as example) file positions are <vp>unsigned64</vp>. The same is the case with <vp>gmtTimeValue</vp>, <vp>localTimeValue</vp> and <vp>timeIntervalValue</vp>.

=== Namespaces ===

Interfaces and classes can be put into namespaces (like <vp>pfc\pie</vp>). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called <vp>file</vp> in the namespace <vp>documentManager</vp> even though there is also a class named <vp>file</vp> in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces <vp>pfc</vp>, <vp>pfc\vip5x</vp> and <vp>pfc\gui</vp>. Also the new <vp>pie</vp> packages (described below) are in the name space <vp>pfc\pie</vp>.

=== binaryNonAtomic domain ===

A new built-in domain <vp>binaryNonAtomic</vp> is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary <vp>binary</vp> domain is no longer scanned for pointers.

=== real32 ===

A domain <vp>real32</vp> is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain <vp>handle</vp> which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: <vp>nullHandle</vp> and <vp>invalidHandle</vp>.

=== Compiler directive #options ===

A new compiler directive <vp>#options</vp> is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:

<vipbnf><OptionsDirective>:
#options <StringLiteral></vipbnf>

This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where <vp>qqq</vp> is declared like this:

<vip>predicates
qqq : (positive V). </vip>

The code above might seem reasonable, we only want to call <vp>qqq</vp> if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation <vp>X - 23</vp> gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:

<vip>clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).</vip>

If <vp>X - 23</vp> gives a negative number, the <vp>tryConvert</vp> will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types <vp>string</vp>, <vp>object</vp>, <vp>string8</vp> and <vp>symbol</vp> are not sub-types of type <vp>pointer</vp> any more.

=== Restrictions for delegate- sections order were removed ===

Now <vp>delegate</vp>- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to windows starting with the letters you have pressed. Also Ctrl-Del closes the open window.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

The dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file as well.

=== Welcome Page ===

The '''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

=== TODO Window ===

It is now possible to view all '''TODO comments''' (i.e. the comments like % TODO) in source files which can be rather convenient for developers. This feature is available via the Main menu: View | TODO

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate <vp>postAction</vp> on the <vp>window</vp> class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class <vp>popupWindow</vp> makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from <vp>pointer</vp> to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like <vp>object</vp> and <vp>symbol</vp>).

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate <vp>getFactChainLength_nd</vp> (in the <vp>profileMemory</vp> class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a <vp>determ</vp> predicate.

So in short a weak pointer is a pointer that will not keep memory alive. 

=== 5xChainDB8 ===

This package is introduced for compatibility support in order to handle old external databases (where strings are not in Unicode).

== Tools ==

=== vipBuilder ===

Some extra options has been added to '''vipBuilder''':
/genresource - also generate resourceIdentifiers.i
/compile <file_name> - compile the file <file_name>

Visual Prolog 7.2 New Features

2008-10-20T07:19:26Z

Alexander Doronin: /* Window Navigation Dialog */

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

<vp>integer64</vp> and <vp>unsigned64</vp> are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use <vp>integer64</vp> and <vp>unsigned64</vp> instead of <vp>core::integer64</vp> and <vp>core::unsigned64</vp>. So now (as example) file positions are <vp>unsigned64</vp>. The same is the case with <vp>gmtTimeValue</vp>, <vp>localTimeValue</vp> and <vp>timeIntervalValue</vp>.

=== Namespaces ===

Interfaces and classes can be put into namespaces (like <vp>pfc\pie</vp>). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called <vp>file</vp> in the namespace <vp>documentManager</vp> even though there is also a class named <vp>file</vp> in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces <vp>pfc</vp>, <vp>pfc\vip5x</vp> and <vp>pfc\gui</vp>. Also the new <vp>pie</vp> packages (described below) are in the name space <vp>pfc\pie</vp>.

=== binaryNonAtomic domain ===

A new built-in domain <vp>binaryNonAtomic</vp> is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary <vp>binary</vp> domain is no longer scanned for pointers.

=== real32 ===

A domain <vp>real32</vp> is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain <vp>handle</vp> which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: <vp>nullHandle</vp> and <vp>invalidHandle</vp>.

=== Compiler directive #options ===

A new compiler directive <vp>#options</vp> is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:

<vipbnf><OptionsDirective>:
#options <StringLiteral></vipbnf>

This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where <vp>qqq</vp> is declared like this:

<vip>predicates
qqq : (positive V). </vip>

The code above might seem reasonable, we only want to call <vp>qqq</vp> if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation <vp>X - 23</vp> gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:

<vip>clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).</vip>

If <vp>X - 23</vp> gives a negative number, the <vp>tryConvert</vp> will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types <vp>string</vp>, <vp>object</vp>, <vp>string8</vp> and <vp>symbol</vp> are not sub-types of type <vp>pointer</vp> any more.

=== Restrictions for delegate- sections order were removed ===

Now <vp>delegate</vp>- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to windows starting with the letters you have pressed. Also Del button closes the open window.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

The dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file as well.

=== Welcome Page ===

The '''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

=== TODO Window ===

It is now possible to view all '''TODO comments''' (i.e. the comments like % TODO) in source files which can be rather convenient for developers. This feature is available via the Main menu: View | TODO

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate <vp>postAction</vp> on the <vp>window</vp> class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class <vp>popupWindow</vp> makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from <vp>pointer</vp> to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like <vp>object</vp> and <vp>symbol</vp>).

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate <vp>getFactChainLength_nd</vp> (in the <vp>profileMemory</vp> class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a <vp>determ</vp> predicate.

So in short a weak pointer is a pointer that will not keep memory alive. 

=== 5xChainDB8 ===

This package is introduced for compatibility support in order to handle old external databases (where strings are not in Unicode).

== Tools ==

=== vipBuilder ===

Some extra options has been added to '''vipBuilder''':
/genresource - also generate resourceIdentifiers.i
/compile <file_name> - compile the file <file_name>

Language Reference/Namespaces

2008-10-18T10:01:06Z

Alexander Doronin:

{{languageReferenceNavbar|Namespaces}}

Namespaces can be used to avoid name clashes, without having to use long strange names. The names in two different namespaces will never clash, but it may be necessary to qualify references with the namespace (or part of it) to resolve ambiguities.

A namespaces are declared and defined implicitly using <vpbnf><NamespaceEntrance></vpbnf>'es:

<vipbnf><NamespaceEntrance>:
namespace <NamespaceIdentifier></vipbnf>

<vipbnf><NamespaceIdentifier>: one of
<LowercaseIdentifier>
<LowercaseIdentifier> \ <NamespaceIdentifier></vipbnf>

In short a <vpbnf><NamespaceIdentifier></vpbnf> is a sequence of lowercase identifiers separated by backslashes.

=== Namespace Entrances and Regions ===

Namespace entrances divide source files into '''''namespace regions'''''.

A namespace entrance marks the beginning of a namespace region, which ends at the next namespace entrance or the end of the file.

Every file starts in the '''''root namespace'''''.

Namespace regions are not influenced by <vp>#include</vp> directives, meaning:
* Namespace entrances in an <vp>#include</vp>-file does not change the namespace region in the including file
* Any file starts in the root namespace (also if it is included inside a namespace region in another file).

Any interface, class and implementation that is meet inside a namespace region belongs to that namespace.

'''Example'''

<vip>class aaa
end class aaa

namespace xxx

class bbb
end class bbb

namespace xxx\yyy

class ccc
end class ccc</vip>

This file is divided in three regions (assuming that it is a complete file). The first region is in the root namespace (\), the second region belongs to the <vp>xxx</vp> namespace and the third region belongs to the <vp>xxx\yyy</vp> namespace.

Subsequently, the class <vp>aaa</vp> belongs to the root namespace, the class <vp>bbb</vp> belongs to the namespace <vp>xxx</vp> and finally the class <vp>ccc</vp> belongs to the namespace <vp>xxx\yyy</vp>.

=== Referencing names in namespaces ===

If <vp>ccc</vp> is a class in the namespace <vp>xxx\yyy</vp>, then the '''''full name''''' of <vp>ccc</vp> is <vp>\xxx\yyy\ccc</vp>.

The leading backslash indicates that we start from the root namespace.

A class/interface can always be uniquely referenced using its full name.

==== Open namespaces ====

The full names are not always convenient and therefore it is possible to use shorter names by opening namespaces.

<vipbnf><ScopeQualification>: one of
<OpenQualification>
...

<OpenQualification>: one of
open <NamespaceIdentifier> \
...</vipbnf>

Opening a namespace is distinguished from opening a class/interface by a trailing backslash.

'''Example'''

<vip>class aaa
open xxx\yyy\
...
end class aaa</vip>

The namespace <vp>xxx\yyy</vp> is opened inside <vp>aaa</vp>.

When a namespace is open that part of a full name can be left out.

'''Example''' A domains with the full name <vp>\xxx\yyy\zzz\ccc::ddd</vp> can be as referenced <vp>zzz\ccc::ddd</vp> inside <vp>aaa</vp> because <vp>xxx\yyy</vp> is open.

Notice that the short name does not start with a backslash; A name starting with a backslash is always a full name.

The namespace that a certain scope (i.e. interface/class/implementation) belongs to is (implicitly) open inside that scope.

Visual Prolog 7.2 New Features

2008-10-18T09:51:40Z

Alexander Doronin:

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

''' integer64''' and '''unsigned64''' are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use '''integer64''' and '''unsigned64''' instead of '''core::integer64''' and '''core::unsigned64'''. So now (as example) file positions are '''unsigned64'''. The same is the case with '''gmtTimeValue''', '''localTimeValue''' and '''timeIntervalValue'''.

=== Namespaces ===

Interfaces and classes can be put into name-spaces (like '''pfc\pie'''). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called '''file ''' in the namespace '''documentManager''' even though there is also a class named '''file''' in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces '''pfc''', '''pfc\vip5x '''and''' pfc\gui'''. Also the new '''pie''' packages (described below) are in the name space ''' pfc\pie'''.

=== binaryNonAtomic domain ===

A new built-in domain '''binaryNonAtomic''' is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary '''binary''' domain is no longer scanned for pointers.

=== real32 ===

A domain '''real32''' is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain '''handle''' which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: '''nullHandle''' and '''invalidHandle'''.

=== Compiler directive #options ===

A new compiler directive '''#options''' is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:
'''#options''' <string_literal>
This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>
clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where '''qqq''' is declared like this:

<vip>
predicates
qqq : (positive V). </vip>
The code above might seem reasonable, we only want to call '''qqq''' if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation X - 23 gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:
<vip>
clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).
</vip>
If X - 23 gives a negative number, the '''tryConvert''' will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types '''string''', '''object''', '''string8''' and '''symbol''' are not sub-types of type '''pointer''' any more.

=== Restrictions for delegate- sections order were removed ===

Now '''delegate'''- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to

windows starting with the letters you have pressed.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

Dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file as well.

=== Welcome Page ===

'''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

=== TODO Window ===

It is now possible to view all '''TODO comments''' (i.e. the comments like % TODO, or /* TODO */) in source files which can be rather convenient for developers. This feature is available via the Main menu: View | TODO

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate '''postAction''' on the '''window''' class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class ''' popupWindow''' makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from '''pointer''' to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like '''object''' and '''symbol''').

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme''''' ''' ''aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate '''getFactChainLength_nd''' (in the '''profileMemory''' class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a '''determ''' predicate.

So in short a weak pointer is a pointer that will not keep memory alive. 

=== 5xChainDB8 ===

This package is introduced for compatibility support in order to handle old external databases (where strings are not in Unicode).

== Tools ==

=== vipBuilder ===

Some extra options has been added to '''vipBuilder''':
/genresource - also generate resourceIdentifiers.i
/compile <file_name> - compile the file <file_name>

Visual Prolog 7.2 New Features

2008-10-18T09:51:01Z

Alexander Doronin:

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

''' integer64''' and '''unsigned64''' are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use '''integer64''' and '''unsigned64''' instead of '''core::integer64''' and '''core::unsigned64'''. So now (as example) file positions are '''unsigned64'''. The same is the case with '''gmtTimeValue''', '''localTimeValue''' and '''timeIntervalValue'''.

=== Namespaces ===

Interfaces and classes can be put into name-spaces (like '''pfc\pie'''). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called '''file ''' in the namespace '''documentManager''' even though there is also a class named '''file''' in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces '''pfc''', '''pfc\vip5x '''and''' pfc\gui'''. Also the new '''pie''' packages (described below) are in the name space ''' pfc\pie'''.

=== binaryNonAtomic domain ===

A new built-in domain '''binaryNonAtomic''' is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary '''binary''' domain is no longer scanned for pointers.

=== real32 ===

A domain '''real32''' is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain '''handle''' which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: '''nullHandle''' and '''invalidHandle'''.

=== Compiler directive #options ===

A new compiler directive '''#options''' is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:
'''#options''' <string_literal>
This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>
clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where '''qqq''' is declared like this:

<vip>
predicates
qqq : (positive V). </vip>
The code above might seem reasonable, we only want to call '''qqq''' if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation X - 23 gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:
<vip>
clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).
</vip>
If X - 23 gives a negative number, the '''tryConvert''' will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types '''string''', '''object''', '''string8''' and '''symbol''' are not sub-types of type '''pointer''' any more.

=== Restrictions for delegate- sections order were removed ===

Now '''delegate'''- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to

windows starting with the letters you have pressed.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

Dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file as well.

=== Welcome Page ===

'''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

=== TODO Window ===

It is now possible to view all '''TODO comments''' (i.e. the comments like % TODO, or /* TODO */) in source files which can be rather convenient for developers. This feature is available via the Main menu: View | TODO

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate '''postAction''' on the '''window''' class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class ''' popupWindow''' makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from '''pointer''' to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like '''object''' and '''symbol''').

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme''''' ''' ''aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate '''getFactChainLength_nd''' (in the '''profileMemory''' class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a '''determ''' predicate.

So in short a weak pointer is a pointer that will not keep memory alive. 

=== 5xChainDB8 ===

This package is introduced for compatibility support in order to handle old external databases (where strings are not in Unicode).

== Tools ==

=== vipBuilder ===

Some extra options has been added to '''vipBuilder''':
/genresource - also generate resourceIdentifiers.i
/compile <file_name> - compile the file <file_name>

Visual Prolog 7.2 New Features

2008-10-18T09:41:03Z

Alexander Doronin:

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

''' integer64''' and '''unsigned64''' are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use '''integer64''' and '''unsigned64''' instead of '''core::integer64''' and '''core::unsigned64'''. So now (as example) file positions are '''unsigned64'''. The same is the case with '''gmtTimeValue''', '''localTimeValue''' and '''timeIntervalValue'''.

=== Namespaces ===

Interfaces and classes can be put into name-spaces (like '''pfc\pie'''). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called '''file ''' in the namespace '''documentManager''' even though there is also a class named '''file''' in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces '''pfc''', '''pfc\vip5x '''and''' pfc\gui'''. Also the new '''pie''' packages (described below) are in the name space ''' pfc\pie'''.

=== binaryNonAtomic domain ===

A new built-in domain '''binaryNonAtomic''' is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary '''binary''' domain is no longer scanned for pointers.

=== real32 ===

A domain '''real32''' is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain '''handle''' which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: '''nullHandle''' and '''invalidHandle'''.

=== Compiler directive #options ===

A new compiler directive '''#options''' is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:
'''#options''' <string_literal>
This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>
clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where '''qqq''' is declared like this:

<vip>
predicates
qqq : (positive V). </vip>
The code above might seem reasonable, we only want to call '''qqq''' if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation X - 23 gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:
<vip>
clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).
</vip>
If X - 23 gives a negative number, the '''tryConvert''' will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types '''string''', '''object''', '''string8''' and '''symbol''' are not sub-types of type '''pointer''' any more.

=== Restrictions for delegate- sections order were removed ===

Now '''delegate'''- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to

windows starting with the letters you have pressed.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

Dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file as well.

=== Welcome Page ===

'''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

=== TODO Window ===

It is now possible to view all '''TODO comments''' (i.e. the comments like % TODO, or /* TODO */) in source files which can be rather convenient for developers. This feature is available via the Main menu: View | TODO

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate '''postAction''' on the '''window''' class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class ''' popupWindow''' makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from '''pointer''' to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like '''object''' and '''symbol''').

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme''''' ''' ''aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate '''getFactChainLength_nd''' (in the '''profileMemory''' class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a '''determ''' predicate.

So in short a weak pointer is a pointer that will not keep memory alive. 

=== 5xChainDB8 ===

This package is introduced for compatibility support in order to handle old external databases (where strings are not in Unicode).

Visual Prolog 7.2 New Features

2008-10-18T09:38:26Z

Alexander Doronin:

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

''' integer64''' and '''unsigned64''' are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use '''integer64''' and '''unsigned64''' instead of '''core::integer64''' and '''core::unsigned64'''. So now (as example) file positions are '''unsigned64'''. The same is the case with '''gmtTimeValue''', '''localTimeValue''' and '''timeIntervalValue'''.

=== Namespaces ===

Interfaces and classes can be put into name-spaces (like '''pfc\pie'''). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called '''file ''' in the namespace '''documentManager''' even though there is also a class named '''file''' in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces '''pfc''', '''pfc\vip5x '''and''' pfc\gui'''. Also the new '''pie''' packages (described below) are in the name space ''' pfc\pie'''.

=== binaryNonAtomic domain ===

A new built-in domain '''binaryNonAtomic''' is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary '''binary''' domain is no longer scanned for pointers.

=== real32 ===

A domain '''real32''' is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain '''handle''' which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: '''nullHandle''' and '''invalidHandle'''.

=== Compiler directive #options ===

A new compiler directive '''#options''' is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:
'''#options''' <string_literal>
This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>
clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where '''qqq''' is declared like this:

<vip>
predicates
qqq : (positive V). </vip>
The code above might seem reasonable, we only want to call '''qqq''' if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation X - 23 gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:
<vip>
clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).
</vip>
If X - 23 gives a negative number, the '''tryConvert''' will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types '''string''', '''object''', '''string8''' and '''symbol''' are not sub-types of type '''pointer''' any more.

=== Restrictions for delegate- sections order were removed ===

Now '''delegate'''- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to

windows starting with the letters you have pressed.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

Dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file as well.

=== Welcome Page ===

'''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

=== TODO Window ===

It is now possible to view all the '''TODO comments''' in source files (i.e. the comments like % TODO, or /* TODO */) which can be rather convenient for developers. This feature is available via the Main menu: View | TODO

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate '''postAction''' on the '''window''' class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class ''' popupWindow''' makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from '''pointer''' to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like '''object''' and '''symbol''').

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme''''' ''' ''aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate '''getFactChainLength_nd''' (in the '''profileMemory''' class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a '''determ''' predicate.

So in short a weak pointer is a pointer that will not keep memory alive.

Visual Prolog 7.2 New Features

2008-10-18T09:33:46Z

Alexander Doronin:

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

''' integer64''' and '''unsigned64''' are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use '''integer64''' and '''unsigned64''' instead of '''core::integer64''' and '''core::unsigned64'''. So now (as example) file positions are '''unsigned64'''. The same is the case with '''gmtTimeValue''', '''localTimeValue''' and '''timeIntervalValue'''.

=== Namespaces ===

Interfaces and classes can be put into name-spaces (like '''pfc\pie'''). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called '''file ''' in the namespace '''documentManager''' even though there is also a class named '''file''' in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces '''pfc''', '''pfc\vip5x '''and''' pfc\gui'''. Also the new '''pie''' packages (described below) are in the name space ''' pfc\pie'''.

=== binaryNonAtomic domain ===

A new built-in domain '''binaryNonAtomic''' is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary '''binary''' domain is no longer scanned for pointers.

=== real32 ===

A domain '''real32''' is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain '''handle''' which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: '''nullHandle''' and '''invalidHandle'''.

=== Compiler directive #options ===

A new compiler directive '''#options''' is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:
'''#options''' <string_literal>
This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>
clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where '''qqq''' is declared like this:

<vip>
predicates
qqq : (positive V). </vip>
The code above might seem reasonable, we only want to call '''qqq''' if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation X - 23 gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:
<vip>
clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).
</vip>
If X - 23 gives a negative number, the '''tryConvert''' will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types '''string''', '''object''', '''string8''' and '''symbol''' are not sub-types of type '''pointer''' any more.

=== Restrictions for delegate- sections order were removed ===

Now '''delegate'''- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to

windows starting with the letters you have pressed.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

Dialog '''Find In Files''' has been improved such that it now shows total number of found entries in a file.

=== Welcome Page ===

'''Welcome Page''' has been improved such that now it has an extra context menu which can be accessed via right mouse. This menu allows to inspect project file properties, remove project from the list of projects, etc.

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate '''postAction''' on the '''window''' class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class ''' popupWindow''' makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from '''pointer''' to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like '''object''' and '''symbol''').

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme''''' ''' ''aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate '''getFactChainLength_nd''' (in the '''profileMemory''' class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a '''determ''' predicate.

So in short a weak pointer is a pointer that will not keep memory alive.

Visual Prolog 7.2 New Features

2008-10-18T09:29:33Z

Alexander Doronin:

Visual Prolog 7.2 introduces many new features and improvements.
Following are the most significant changes.

== Language Features ==

Visual Prolog 7.2 brings several language improvements. This section gives a brief overview of some of them.

=== Anonymous predicates ===

Anonymous predicates are the Prolog counterparts to anonymous functions as known in functional programming languages. Anonymous predicates are described in details in the article ''[http://wiki.visual-prolog.com/index.php?title=Language_Reference/Terms/Anonymous_Predicates Anonymous Predicates]'' of Visual Prolog Language Reference.

=== 64 bit numbers ===

''' integer64''' and '''unsigned64''' are two new built-in types, that replace the PFC domains '''core::integer64''' and '''core::unsigned64'''. The new domains are like integer and unsigned expect that they have a 64-bit representation. All arithmetic operations (except the power operation) are supported for the types. They are written, read, saved and consulted in normal number format only with much larger range than 32-bit numbers. PFC has been updated to use '''integer64''' and '''unsigned64''' instead of '''core::integer64''' and '''core::unsigned64'''. So now (as example) file positions are '''unsigned64'''. The same is the case with '''gmtTimeValue''', '''localTimeValue''' and '''timeIntervalValue'''.

=== Namespaces ===

Interfaces and classes can be put into name-spaces (like '''pfc\pie'''). This allows the same interface/class name to be declared/defined in several name spaces in the same program. So now it is possible (as example) to have a class called '''file ''' in the namespace '''documentManager''' even though there is also a class named '''file''' in PFC. It is planned (but not effectuated at the time of writing) to put PFC classes in namespaces '''pfc''', '''pfc\vip5x '''and''' pfc\gui'''. Also the new '''pie''' packages (described below) are in the name space ''' pfc\pie'''.

=== binaryNonAtomic domain ===

A new built-in domain '''binaryNonAtomic''' is introduced to distinguish binaries may contain pointers and should therefore be scanned by the garbage collector. The ordinary '''binary''' domain is no longer scanned for pointers.

=== real32 ===

A domain '''real32''' is introduced to ease the integration with foreign API's that sometimes uses such short reals. It is not intended for use in "normal" code.

=== handle ===

A new built-in domain '''handle''' which corresponds to API handle type is introduced to ease the integration with foreign API's as well. Also, there are two new built-in constants of this type: '''nullHandle''' and '''invalidHandle'''.

=== Compiler directive #options ===

A new compiler directive '''#options''' is introduced to define some additional compiler options for a separate compilation init. It has the following syntax:
'''#options''' <string_literal>
This directive affects the whole compilation unit and should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates warning message and ignores the directive. The '''<string_literal>''' can only contain the following compiler's options: '''/Warning''', '''/Check''', '''/NOCheck''', '''/Optimize''', '''/DEBug''', '''/GOAL''', '''/MAXErrors''' and '''/MAXWarnings'''. Otherwise the compiler generates error message for invalid option.

== Compiler ==

The compiler is (obviously) updated to deal with the new language features. But it has also been improved in several other respects.

=== Unreachable code detection ===

The ability to detect unreachable code has been improved vastly, both when it comes to detecting unused predicates and facts and when it comes to code inside clauses which cannot be reached. Unreachable code will cause warnings.

=== Superfluous test detection ===

The compiler will also give warnings about tests, which are trivially fulfilled due to the type of the involved variables. Consider this code for example:

<vip>
clauses
ppp(X) :-
Y = X - 23,
Y >= 0,
qqq(Y).</vip>

where '''qqq''' is declared like this:

<vip>
predicates
qqq : (positive V). </vip>
The code above might seem reasonable, we only want to call '''qqq''' if Y is indeed greater than or equal to zero.

The only problem is Y is always greater than zero, because Y has the type positive, which only contains numbers that are greater than or equal to zero.

If the calculation X - 23 gives a negative number an out-of-range exception will be raised ('''''before''''' reaching the test).
So this new warning can help the programmer detect places where it seems that testing ensures validity of the code, while in reality the test will never fail because an exception will be raised instead. The code above can be corrected using this code:
<vip>
clauses
ppp(X) :-
Y = tryConvert(positive, X - 23),
qqq(Y).
</vip>
If X - 23 gives a negative number, the '''tryConvert''' will fail.

=== Smaller code ===

The size of the generated code has become smaller, especially for predicates with many clauses that match different patterns of input.

=== Less stack usage ===

Likewise, the stack size has been reduced (dramatically in some cases).

=== The sub-type relations for some built-in types were changed ===

The built-in types '''string''', '''object''', '''string8''' and '''symbol''' are not sub-types of type '''pointer''' any more.

=== Restrictions for delegate- sections order were removed ===

Now '''delegate'''- sections can be mixed with "usual" sections (like predicates, etc.) inside a class implementation.

== IDE ==

Many bugs and inconveniences have been solved in the IDE. Just like numerous smaller and larger improvements has been made. This section describes some of the major improvements.

=== Build speed ===

The build system has been changed such that it can utilize multi-core processors by compiling several packages in parallel. On a quad-core processor this typically gives a factor 4 (sometimes more) when many packages needs to be compiled.

As of this writing, we are also working on letting the compiler itself compile several packages in a single invocation and thus skip many compiler phases for files that are included in several packages.

This feature has given a factor 4 when rebuilding a ''very'' large project.

=== IntelliSence ===

Browse information (i.e. information about the source code fed from the compiler back to the IDE) is now utilized to provide IntelliSense: When you edit source code the IDE shows possible/sensible completion of the word you are typing. You can then select the completion in the list using mouse, arrow keys and TAB; the IDE will complete the word with your choice. The IDE will also show tool tip windows showing the declaration of the predicate you are about to write arguments for. That way you can see which arguments the predicate takes without changing context.

=== Window Navigation Dialog ===

The order, in which Ctrl-TAB shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, Ctrl-TAB also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to

windows starting with the letters you have pressed.

=== Grouping editor windows ===

Editor windows can be grouped together to look and behave like a single window. This has the advantage that you can arrange windows in a fixed layout inside the IDE. The IDE will remember two different layouts, one for "normal" mode and one for debug mode. Typically, you want large editor windows in "normal" mode, but smaller editors in debug mode to give more room for the variables window, etc.

=== Resources view in project tree ===

When selecting a resource (e.g. a dialog or a bitmap) in the project tree, the right pane will show a preview of the resource.

=== Zooming ===

Pressing the Ctrl and using the mouse wheel the IDE will increase/decrease font size in various windows creating a zoom effect. Zooming is also bound to Ctrl-+, Ctrl--, and Ctrl-0 reset to 100%.

=== Un-/commenting blocks ===

The editor has new commands for commenting and un-commenting a block of code with %-chars. The commands are bound to Ctrl-Alt-% and Ctrl-Alt-Shift-%. (It would be more correct to state the keys as Ctrl-Alt-5 and Ctrl-Alt-Shift-5, but it seems simpler to remember the %-key).

=== Project loading speed ===

The project loading has been changed such that the speed of this process was increased.

=== Find In Files dialog ===

The '''Find In Files''' dialog has been improved such that it now shows the total number of found entries in a file.

== PFC ==

PFC has mainly been consolidated, updated to 64-bit numbers and things like that. But there are also some new things.

=== PIE ===

The engine of PIE (Prolog Interpreter Engine) is now added to PFC and will therefore be supported as a tool in future. The most important feature is that you can easily hook-in predicates from you own application. Subsequently, the PIE programs can manipulate your application. So PIE is very useful as a scripting engine in applications. Besides this, the efficiency has been improved and PIE now supports functions and real numbers.

=== progressBarControl ===

A progressBarControl binds to the win32 common control progress bar. It is the intension to add additional win32 common controls, but to deal more easily with them certain inner parts of PFC GUI will have to be revised first.

=== postAction ===

A new predicate '''postAction''' on the '''window''' class, makes it possible to post an action to any window. The action will be packed in a user message and when the user message is handled the action is executed. Together with anonymous predicates this makes any other use of user messages superfluous.

=== popupWindow ===

A new class ''' popupWindow''' makes it easier to create popup windows like tooltips. Most importantly popup windows must have the screen as parent so that they can be drawn outside their logical owner and on top of other windows.

=== radixTree ===

A radix tree is a map from '''pointer''' to any type. Its main advantage (over for example red-black-trees) is that supports very efficient merge of several maps. The disadvantage is that the keys are pointer values, so the trees can only be used on things with unique pointers (like '''object''' and '''symbol''').

=== uxTheme native bindings ===

Native bindings to uxTheme make it possible to experiment with creating '''''theme''''' ''' ''aware''''' controls. Theme aware controls are not drawn using lines, circles, rectangles, etc. Instead they are drawn using '''''theme elements'''''. Theme elements are logical graphical entities like divider line, button surface, button outline, drop-down mark, etc. You combine/draw such logical elements into your control, and when the theme changes your control will also change appearance. If you have chosen the elements wisely your control will also blend-in with other themes.

=== getFactChainLength_nd ===

A new predicate '''getFactChainLength_nd''' (in the '''profileMemory''' class) returns the number of facts in each class fact chain in the entire program. It is intended to help tracking down problems with class facts that are not retracted when they should and therefore eats memory by keeping data alive that should have been dead.

=== weakPointer ===

Weak pointers are "pointers" that the garbage collector does not see as pointers, so if there are only weak pointers to a piece of memory the garbage collector will recycle that piece of memory. As a consequence, a weak pointer cannot always be dereferenced, sometimes the target as been recycled. Dereferencing of a weak pointer it therefore done using a '''determ''' predicate.

So in short a weak pointer is a pointer that will not keep memory alive.