1/*  Part of SWI-Prolog
   2
   3    Author:        Jan Wielemaker
   4    E-mail:        J.Wielemaker@vu.nl
   5    WWW:           http://www.swi-prolog.org
   6    Copyright (c)  2012, VU University Amsterdam
   7    All rights reserved.
   8
   9    Redistribution and use in source and binary forms, with or without
  10    modification, are permitted provided that the following conditions
  11    are met:
  12
  13    1. Redistributions of source code must retain the above copyright
  14       notice, this list of conditions and the following disclaimer.
  15
  16    2. Redistributions in binary form must reproduce the above copyright
  17       notice, this list of conditions and the following disclaimer in
  18       the documentation and/or other materials provided with the
  19       distribution.
  20
  21    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  24    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  25    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  27    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  28    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  29    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  31    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  32    POSSIBILITY OF SUCH DAMAGE.
  33*/
  34
  35:- module(pldoc_pack,
  36          [ doc_pack/1                  % +Pack
  37          ]).
  38:- use_module(library(prolog_pack)).
  39:- use_module(library(http/html_write)).
  40:- use_module(library(http/html_head)).
  41:- use_module(library(http/http_dispatch)).
  42:- use_module(doc_html).
  43:- use_module(doc_index).
  44
  45/** <module> PlDoc for Prolog extension packs
  46
  47This module profiles PlDoc support specific   to Prolog extension packs.
  48It extends the PlDoc web-browser with the ability to lists the installed
  49packs and provide an overview of  a   pack,  whether  loaded or not. The
  50predicate  doc_pack/1  can  be  used    to   generate  stand-alone  HTML
  51documentation for a pack.
  52*/
  53
  54:- http_handler(pldoc(pack),     http_redirect(moved, pldoc('pack/')), []).
  55:- http_handler(pldoc('pack/'),  pldoc_pack, [prefix]).
  56
  57%!  pldoc_pack(+Request)
  58%
  59%   HTTP handler that handles /pack/ in the PlDoc server. Without an
  60%   additional  path,  it  lists  the    installed  packs.  With  an
  61%   additional package name, it lists  the   content  of  a pack and
  62%   finally, /pack/<pack>/<file> can be used to get documentation or
  63%   the source of a pack file.
  64
  65pldoc_pack(Request) :-
  66    memberchk(path_info(PackPath), Request),
  67    PackPath \== '',
  68    !,
  69    (   pack_path(Pack, PackFile, PackPath)
  70    ->  list_pack(Pack, PackFile, Request)
  71    ;   http_404([], Request)
  72    ).
  73pldoc_pack(_Request) :-
  74    reply_html_page(
  75        pldoc(packs),
  76        title('Installed extension packs'),
  77        \pack_page([])).
  78
  79pack_path(Pack, PackFile, PackPath) :-
  80    sub_atom(PackPath, B, _, A, /),
  81    !,
  82    sub_atom(PackPath, 0, B, _, Pack),
  83    sub_atom(PackPath, _, A, 0, PackFile).
  84
  85pack_page(Options) -->
  86    html_requires(pldoc),
  87    object_page_header(-, Options),
  88    html([ h1('Installed extension packs'),
  89           p([ 'The following extension packages are installed in ',
  90               'the this Prolog system.  Other packages can be found at ',
  91               a(href('http://www.swi-prolog.org/pack/list'),
  92                 'the SWI-Prolog website')
  93             ]),
  94           \pack_table(Options)
  95         ]).
  96
  97
  98%!  pack_table(+Options)// is det.
  99%
 100%   Generate a table with installed packages
 101
 102pack_table(_Options) -->
 103    { findall(Pack, pack_property(Pack, directory(_)), Packs0),
 104      sort(Packs0, Packs)
 105    },
 106    html(table(class(packs),
 107               [ tr([th('Pack'), th('Version'), th('Title')])
 108               | \packs(Packs)
 109               ])).
 110
 111packs([]) --> [].
 112packs([H|T]) --> pack(H), packs(T).
 113
 114pack(Pack) -->
 115    { uri_encoded(path, Pack, HREF),
 116      pack_property(Pack, version(Version)),
 117      (   pack_property(Pack, title(Title))
 118      ->  true
 119      ;   Title = '<no title>'
 120      )
 121    },
 122    html(tr([ td(class(pack_name),    a(href(HREF+'/'), Pack)),
 123              td(class(pack_version), Version),
 124              td(class(pack_title),   Title)
 125            ])).
 126
 127
 128%!  list_pack(+Pack, +PackFile, +Request)
 129%
 130%   List a directory or file in a pack
 131
 132list_pack(Pack, '', _) :-
 133    !,
 134    reply_html_page(
 135        pldoc(pack),
 136        title('Documentation for pack ~w'-[Pack]),
 137        \pack_doc(Pack)).
 138list_pack(Pack, File, Request) :-
 139    pack_property(Pack, directory(PackDir)),
 140    directory_file_path(PackDir, File, Path0),
 141    absolute_file_name(Path0, Path),        % Canonical
 142    sub_atom(Path, 0, _, _, PackDir),
 143    pldoc_http:doc_reply_file(Path, Request).
 144
 145pack_doc(Pack) -->
 146    { pack_property(Pack, directory(PackDir)),
 147      pack_title(Pack, Title),
 148      findall(O, pack_option(Pack, O), Options)
 149    },
 150    dir_index(PackDir,
 151              [ if(true),
 152                recursive(true),
 153                title(Title)
 154              | Options
 155              ]).
 156
 157
 158                 /*******************************
 159                 *        STAND ALONE DOCS      *
 160                 *******************************/
 161
 162%!  doc_pack(+Pack)
 163%
 164%   Generate stand-alone documentation for  the   package  Pack. The
 165%   documentation is generated in a directory =doc= inside the pack.
 166%   The  index  page  consists  of  the    content  of  =readme=  or
 167%   =|readme.txt|= in the main directory of the pack and an index of
 168%   all files and their public predicates.
 169
 170doc_pack(Pack) :-
 171    pack_property(Pack, directory(PackDir)),
 172    pack_title(Pack, PackTitle),
 173    findall(O, pack_option(Pack, O), Options),
 174    directory_file_path(PackDir, prolog, SourceDir),
 175    directory_file_path(PackDir, doc, DocDir),
 176    doc_save(SourceDir,
 177             [ title(PackTitle),
 178               doc_root(DocDir),
 179               if(true),
 180               recursive(true)
 181             | Options
 182             ]).
 183
 184pack_title(Pack, PackTitle) :-
 185    pack_property(Pack, title(Title)),
 186    !,
 187    format(atom(PackTitle), 'Pack ~w -- ~w', [Pack, Title]).
 188pack_title(Pack, PackTitle) :-
 189    format(atom(PackTitle), 'Pack ~w', [Pack]).
 190
 191pack_option(Pack, Option) :-
 192    pack_option(Option),
 193    pack_property(Pack, Option).
 194
 195pack_option(readme(_)).
 196pack_option(todo(_)).