├── resources
    └── banner.png
├── .gitignore
├── src
    ├── include
    │   └── common.pl
    ├── util.pl
    ├── substarter.plt
    ├── substarter.pl
    ├── starter.plt
    └── starter.pl
├── Makefile
├── LICENSE
├── load.pl
└── README.md


/resources/banner.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/adkelley/prolog-starter/HEAD/resources/banner.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | # Backup files and other irrelevant stuff.
 2 | *~
 3 | *.swp
 4 | .DS_Store
 5 | Icon?
 6 | ._*
 7 | .Spotlight-V100
 8 | .Trashes
 9 | lib/*
10 | resources/*.sketch
11 | resources/*.xcf


--------------------------------------------------------------------------------
/src/include/common.pl:
--------------------------------------------------------------------------------
 1 | /** <module> Prolog starter common utility predicates
 2 | 
 3 | Directives to be textually included by all files.
 4 | 
 5 | @author Fixme
 6 | @copyright Fixme
 7 | @license Fixme
 8 | @see <http://github.com/adkelley/prolog-starter
 9 | */
10 | 
11 | 
12 | %! encoding(+UTF8) is det
13 | %
14 | %  All source files should be in UTF-8.
15 | %
16 | :- encoding(utf8).
17 | 


--------------------------------------------------------------------------------
/src/util.pl:
--------------------------------------------------------------------------------
 1 | /** <module> Common Utility predicates
 2 | 
 3 | This is an example structure for modular software development in Prolog.
 4 | 
 5 | @author Fixme
 6 | @copyright Fixme
 7 | @license Fixme
 8 | @see <http://github.com/adkelley/prolog-starter
 9 | 
10 | */
11 | 
12 | :- module(_, [ throw_error/3 ]).
13 | 
14 | 
15 | %! throw_error(+Type, +Predicate, +Message) is semidet
16 | %
17 | %  Throw an error and report the predicate and message
18 | %  to the user
19 | %
20 | throw_error(Type, Predicate, Message) :-
21 |     throw(starter_error(Type, context(Predicate, Message))).
22 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
 1 | PROLOG = swipl -O
 2 | 
 3 | .PHONY: test
 4 | test:
 5 | 	@ echo "-- Run tests and exit  ..."
 6 | 	time $(PROLOG) -s load -g starter_test -t halt
 7 | 
 8 | .PHONY: cov
 9 | cov:
10 | 	@ echo "-- Run tests, print test coverage and exit ..."
11 | 	$(PROLOG) -s load -g starter_cov -t halt
12 | 
13 | .PHONY: repl
14 | repl:
15 | 	@ echo "-- Load and enter REPL ..."
16 | 	$(PROLOG) -s load -g starter_repl
17 | 
18 | #
19 | # Args="Module Goal ExtraArgs"
20 | #
21 | .PHONY: args
22 | args:
23 | 	@ echo "-- Load and execute goal from command line args ..."
24 | 	$(PROLOG) -s load -g starter_args -t halt -- $(ARGS)
25 | 


--------------------------------------------------------------------------------
/src/substarter.plt:
--------------------------------------------------------------------------------
 1 | :- include(starter(include/common)).
 2 | 
 3 | :- use_module(substarter, []).
 4 | 
 5 | :- begin_tests('substarter').
 6 | 
 7 | test('test1', true(Got == Expected)) :-
 8 |     format('~nsubstarter:test1 - string_lowercase/2: string transformed to lower case~n'),
 9 |     Expected = "substarter",
10 |     substarter:string_lowercase("SUBSTARTER", Got).
11 | 
12 | test('test2', [
13 |          throws(starter_error(instantiation, context(substarter:string_lowercase/2, "LowerCase argument must be a free variable")))]) :-
14 |     format('~nsubstarter:test2 - string_lowercase/2: throws on a bounded var'),
15 |     Var = "bounded already",
16 |     substarter:string_lowercase("SUBSTARTER", Var).
17 | 
18 | :- end_tests('substarter').
19 | 


--------------------------------------------------------------------------------
/src/substarter.pl:
--------------------------------------------------------------------------------
 1 | /** <module> Prolog starter template substarter module
 2 | 
 3 | This is an example structure for modular software development in Prolog.
 4 | 
 5 | @author Fixme
 6 | @copyright Fixme
 7 | @license Fixme
 8 | @see <http://github.com/adkelley/prolog-starter
 9 | */
10 | 
11 | :- module(_, [string_lowercase/2]).
12 | 
13 | :- use_module(util, []).
14 | 
15 | %! string_lowercase(+String, -LowerCase) is semidet
16 | %
17 | % Transform string to lower case
18 | %
19 | string_lowercase(Word, LowerCase) :-
20 |     core:var(LowerCase),
21 |     !,
22 |     core:string_lower(Word, LowerCase).
23 | 
24 | string_lowercase(_Name, _LowerCase) :-
25 |     util:throw_error(instantiation, substarter:string_lowercase/2, "LowerCase argument must be a free variable").
26 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | Copyright (C) 2020 by Alex Kelley (https://github.com/adkelley/)
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining a copy
 4 | of this software and associated documentation files (the "Software"), to deal
 5 | in the Software without restriction, including without limitation the rights
 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 7 | copies of the Software, and to permit persons to whom the Software is
 8 | furnished to do so, subject to the following conditions:
 9 | 
10 | The above copyright notice and this permission notice shall be included in
11 | all copies or substantial portions of the Software.
12 | 
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19 | THE SOFTWARE.
20 | 


--------------------------------------------------------------------------------
/src/starter.plt:
--------------------------------------------------------------------------------
 1 | :- include(starter(include/common)).
 2 | 
 3 | :- use_module(starter, []).
 4 | 
 5 | :- begin_tests('starter').
 6 | 
 7 | test('test1', [true(Got == Expected)]) :-
 8 |     format('~nstarter:test1 - library version~n'),
 9 |     Expected = [0, 0, 1],
10 |     starter:version(Got).
11 | 
12 | test('test2A', true(Got == Expected)) :-
13 |     format('~nstarter:test2A - string_uppercase/2: name transformed to upper case~n'),
14 |     Expected = "STARTER",
15 |     starter:string_uppercase("starter", Got).
16 | 
17 | test('test2B', [
18 |          throws(starter_error(instantiation, context(starter:string_uppercase/2, "UpperCase argument must be a free variable")))]) :-
19 |     format('~nstarter:test2B - string_uppercase/2: throws on a bounded argument~n'),
20 |     Var = "bounded already",
21 |     starter:string_uppercase("starter", Var).
22 | 
23 | test('test3A', true(Got == Expected)) :-
24 |     format('~nstarter:test3A - string_lowercase_reverse/2: name transformed to lower case and reversed~n'),
25 |     Expected = "retrats",
26 |     starter:string_lowercase_reverse("STARTER", Got).
27 | 
28 | test('test3B', [
29 |          throws(starter_error(instantiation, context(starter:string_lowercase_reverse/2, "LowerCaseReversed argument must be a free variable")))]) :-
30 |     format('~nstarter:test3B - string_lowercase_reverse/2: throws on a bounded argument~n'),
31 |     Var = "bounded already",
32 |     starter:string_lowercase_reverse("STARTER", Var).
33 | 
34 | 
35 | :- end_tests('starter').
36 | 


--------------------------------------------------------------------------------
/src/starter.pl:
--------------------------------------------------------------------------------
 1 | /** <module> Prolog starter template main module
 2 | 
 3 | This is an example structure for modular software development in Prolog.
 4 | 
 5 | @author Fixme
 6 | @copyright Fixme
 7 | @license Fixme
 8 | @see <http://github.com/adkelley/prolog-starter
 9 | */
10 | 
11 | :- module(_, [ starter/0
12 |              , string_uppercase/2
13 |              , string_lowercase_reverse/2
14 |              , version/1
15 |              ]).
16 | 
17 | :- include(starter(include/common)).
18 | 
19 | :- use_module(substarter, []).
20 | :- use_module(util, []).
21 | 
22 | %!  version(?Version) is det.
23 | %
24 | %   True if version is a list representing the major, minor
25 | %   and patch version numbers of this library.
26 | 
27 | version([0,0,1]).
28 | 
29 | %! starter is det
30 | %
31 | %  Replace these modules with your own main program
32 | %
33 | 
34 | starter :-
35 |     core:writeln("Hello, Starter!").
36 | 
37 | %! string_uppercase(+String, -UpperCase) is semidet
38 | %
39 | % Transform a String string to UpperCase
40 | %
41 | 
42 | string_uppercase(String, UpperCase) :-
43 |     core:var(UpperCase),
44 |     !,
45 |     core:string_upper(String, UpperCase).
46 | 
47 | string_uppercase(_String, _Uppercase) :-
48 |     util:throw_error(instantiation, starter:string_uppercase/2, "UpperCase argument must be a free variable").
49 | 
50 | %! string_lowercase_reverse(String, LowerReverse) is semidet
51 | %
52 | %  convert String to lowercase and reverse it
53 | %
54 | string_lowercase_reverse(String, LowerCaseReversed) :-
55 |     core:var(LowerCaseReversed),
56 |     !,
57 |     substarter:string_lowercase(String, LowerCase),
58 |     core:string_chars(LowerCase, LowerCaseList),
59 |     core:reverse(LowerCaseList, ReversedList),
60 |     core:text_to_string(ReversedList, LowerCaseReversed).
61 | 
62 | string_lowercase_reverse(_String, _LowerCaseReversed) :-
63 |     util:throw_error(instantiation, starter:string_lowercase_reverse/2, "LowerCaseReversed argument must be a free variable").
64 | 


--------------------------------------------------------------------------------
/load.pl:
--------------------------------------------------------------------------------
  1 | /** <module> Interface for Prolog starter template.
  2 | 
  3 | Acts as an interface to the system. Configures load paths and provides
  4 | predicates for initiating the system.
  5 | 
  6 | To configure for your own project, replace 'starter', with the name
  7 | of your main program file.
  8 | 
  9 | Configures internal load paths in preparation of use_module calls.
 10 | Provides predicates for adding an entity to the current database
 11 | 
 12 | @author Fixme
 13 | @copyright Fixme
 14 | @license Fixme
 15 | */
 16 | 
 17 | starter_configure_globals :-
 18 |     set_test_options([load(always)]).
 19 | 
 20 | 
 21 | % starter_configure_load_paths() is det
 22 | %
 23 | % Configures internal load paths in preparation of use_module calls.
 24 | 
 25 | starter_configure_load_paths :-
 26 |     prolog_load_context(directory, Root), % Available during compilation
 27 |     starter_configure_path(Root, 'src', starter).
 28 | 
 29 | starter_configure_path(PathPrefix, PathSuffix, Name) :-
 30 |     atomic_list_concat([PathPrefix,PathSuffix], '/', Path),
 31 |     asserta(user:file_search_path(Name, Path)).
 32 | 
 33 | % Set everything up
 34 | :- starter_configure_globals.
 35 | :- starter_configure_load_paths.
 36 | 
 37 | % documentation - uncomment to run documentation server
 38 | %:- doc_server(4000).
 39 | %:- portray_text(true).
 40 | 
 41 | 
 42 | :- include(starter(include/common)).
 43 | 
 44 | starter_load_project_modules :-
 45 |     %% TODO: Look into pldoc
 46 |     use_module(library(pldoc), []),  % Load first to enable comment processing
 47 |     use_module(starter(starter), []),
 48 |     use_module(starter(substarter), []).
 49 | 
 50 | starter_load_project_tests :-
 51 |     plunit:load_test_files([]).
 52 | 
 53 | %% starter_test() is det.
 54 | %
 55 | %  Loads everything and runs test suite
 56 | 
 57 | starter_test :-
 58 |     starter_load_project_modules,
 59 |     starter_load_project_tests,
 60 |     starter_run_test_suite.
 61 | 
 62 | starter_run_test_suite :-
 63 |     core:format('~n% Run tests ...~n'),
 64 |     plunit:run_tests.
 65 | 
 66 | %%  starter_cov() is det.
 67 | %
 68 | %   Loads everything and runs the test suite with coverage analysis.
 69 | 
 70 | starter_cov :-
 71 |     starter_load_project_modules,
 72 |     starter_load_project_tests,
 73 |     starter_run_test_suite_with_coverage.
 74 | 
 75 | starter_run_test_suite_with_coverage :-
 76 |     core:format('~n% Run tests ...~n'),
 77 |     plunit:show_coverage(plunit:run_tests).
 78 | 
 79 | %% starter_repl() is det.
 80 | %
 81 | %  Loads everything and enters interactive mode.
 82 | 
 83 | starter_repl :-
 84 |     starter_load_project_modules,
 85 |     starter_load_project_tests.
 86 | 
 87 | 
 88 | %% starter_args() is det.
 89 | %
 90 | %  Loads everything and executes a goal entered by the user from the command line.
 91 | %  Format of command line args is Module Name ExtraArgs, where Name is the
 92 | %  predicate you wish to run.  See Makefile
 93 | %
 94 | starter_args :-
 95 |     starter_load_project_modules,
 96 |     core:current_prolog_flag(argv, [M,Name|ExtraArgs]),
 97 |     format('Goal: ~w:~w~n', [M,Name]),
 98 |     go(M:Name, ExtraArgs).
 99 | 
100 | go(_,[]).
101 | go(M:Name, [Arg|Args]) :-
102 |     core:apply(M:Name, [Arg, Result]),
103 |     core:format('Argument: ~w, Result: ~w~n', [Arg,Result]),
104 |     go(M:Name, Args).
105 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | ![series_banner](resources/banner.png)
 2 | # Template for new SWI-Prolog projects
 3 | 
 4 | Before proceeding with the instructions below, be sure to download and install [SWI-Prolog](https://www.swi-prolog.org/Download.html).
 5 | ## Instructions
 6 | 
 7 | To convert this template to your own project:
 8 | 1. Replace the word *starter* with the name of your main program in both `Makefile` and `load.pl`.
 9 | 2. Replace `src/starter.pl` and `src/substarter.pl` with your own main program.
10 | 3. Replace `src/starter.plt` and `src/substarter.plt` with your own tests.
11 | 4. Use `make <target>` where `<target>` is either `test`, `cov`, `repl`, or `args` to compile and run your program.
12 | 5. Uncomment lines 37-39 in `load.pl` to run a `pldoc` documentation server locally (see References)
13 | 
14 | ## Makefile explanation
15 | 1. `make test` will compile the source code, and run the unit tests.
16 | 2. `make cov` performs step 1 and, in addition, will print information about coverage by file (e.g., number of clauses).
17 | 3. `make repl` will compile the source code, and will start the Prolog top level (i.e., REPL).  Note that you can run a unit test(s) in the top level with [run_tests/1](https://www.swi-prolog.org/search?for=run_tests).
18 | 4. `make args ARGS="Module Goal ExtraArgs"` will compile the source code, and apply `Module:Goal` with the `ExtraArgs`. For example, `ARGS="starter string_uppercase 'hello'"` calls `starter:string_uppercase('hello', Result)`.  Note that `Result` is an unbound variable supplied by `load.pl`. Its possible to supply your own unbound variables, but it requires more pattern matching than what I've coded in `load.pl`.
19 | 
20 | ## License
21 | Licensed under the MIT license which can be found in the file
22 | `LICENSE` in the project root.
23 | 
24 | ## References
25 | 
26 | 1. [Prolog Unit Tests](https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/plunit.html%27))
27 | 2. [SWI-Prolog Source Documentation Infrastructure](https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/pldoc.html%27))
28 | 
29 | ## Coding Guidelines
30 | 
31 |  * Use empty imports (use_module(mymodule, [])) in order to not
32 |    pollute the namespace.
33 |  * Always use module prefixes (mymodule:predicate(...)) in order to
34 |    clarify where things are coming from.
35 |  * Always use the "made-up" module prefix "core:" when calling
36 |    built-in predicates. This is completely unnecessary, and doesn't even
37 |    work in all cases, but I think it is a good idea as long as it doesn't
38 |    cause any problems. This decision may need to be revised when
39 |    compatibility between different Prologs is investigated.
40 |  * Avoid the if-then-else construct. It just looks ugly.
41 |  * Avoid disjunctions. They are ugly, and can be replaced by properly
42 |    written helpers. Think: premises are "and", clauses are "or".
43 |  * Use cuts where appropriate, and try to keep each cut on a line by
44 |    itself unless its placement is obvious and consistent in each clause.
45 |    PlUnit is excellent at pointing out when tests succeed but leave
46 |    choice points.
47 |  * Try to avoid spaces within lists and structures, but always use
48 |    spaces between arguments.
49 |  * Predicates, atoms, etc. should use "this_naming_style" while variables
50 |    should use "ThisNamingStyle".
51 |  * Try to stick to the PlDoc structure.
52 |  * If in doubt, consult: [Some Coding Guidelines for Prolog](https://www.cmpe.boun.edu.tr/sites/default/files/prolog_coding_guidelines.pdf)
53 |  
54 | ## Credits
55 |  The structure of this starter template was modeled after a prolog project by [khueue](https://github.com/khueue/prolog-json).
56 | 


--------------------------------------------------------------------------------