Commit 24ce6fee authored by Jérôme Chauveau's avatar Jérôme Chauveau
Browse files

add some xqdocs annotations / comments. #9

parent 96249193
Loading
Loading
Loading
Loading
+24 −10
Changes for Makefile: 24 added lines, 10 removed lines.
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ SRC_DIR=${CURDIR}/src

install-basex: # BaseX & dépendances: Téléchargement, installation et définition du mot de passe admin
	@if [ -d '.max/basex' ]; then\
		echo 'BaseX install OK.';\
		echo 'Installation de BaseX : OK.';\
	else\
	  	mkdir .max;\
		cd .max;\
@@ -14,22 +14,22 @@ install-basex: # BaseX & dépendances: Téléchargement, installation et défini
		cd ..;\
		./.max/basex/bin/basexhttpstop || true;\
		./.max/basex/bin/basexhttp -S ;\
		echo 'Please define a BaseX admin password';\
		echo 'Définition du mot de passe admin de BaseX';\
		./.max/basex/bin/basex -c'PASSWORD';\
		./.max/basex/bin/basexhttpstop;\
		echo 'BaseX install done.';\
		echo 'Installation de BaseX terminée.';\
    fi
.PHONY: install-basex


install: install-basex ## Installation de MaX
	@if [ -d '.max/basex/webapp/max' ]; then\
		echo 'MaX install OK.';\
		echo 'Installation de MaX : OK.';\
	else\
		ln -s $(SRC_DIR)/main/ .max/basex/webapp/max;\
		ln -s $(SRC_DIR)/resources .max/resources;\
		ln -s ../fixtures .max/fixtures;\
		echo 'MaX install done.';\
		echo 'Installation de MaX effectuée.';\
	fi
.PHONY: install

@@ -50,7 +50,7 @@ package: install ## Construction d'une version distribuable de MaX
	@cp -r src/main package/.max/src/
# génération d'un fichier VERSION
	@git rev-parse HEAD >> package/VERSION
	@echo 'Package built in package directory.'
	@echo 'Package disponible dans le dossier package.'
# création du Makefile (les cibles de dev sont supprimées)
	@echo -n "SRC_DIR=$$" > package/Makefile
	@echo "{CURDIR}/.max/src" >> package/Makefile
@@ -59,23 +59,23 @@ package: install ## Construction d'une version distribuable de MaX

demo:  ## Installation d'une édition de démo
	@if [ ! -d '.max/basex' ]; then\
		echo 'MaX is not installed, please run make install first.';\
		echo 'Installation de MaX manquante, veuillez lancer : make install.';\
	else\
		cp -r .max/fixtures/max .max/basex/data/;\
		cp -r .max/fixtures/content_html .;\
		cp -r .max/fixtures/templates .;\
		cp -r .max/fixtures/autoroute .;\
		cp -r .max/fixtures/config.xml .;\
		echo 'demo installed.';\
		echo 'demo installée.';\
	fi
.PHONY: demo

check: ## vérification de la configuration
	@if [ -f 'config.xml' ]; then\
		.max/basex/bin/basex -q"validate:rng('config.xml', '.max/resources/max-configuration.rng')" || false;\
		echo 'SUCCESS : config.xml file is valid.';\
		echo 'MaX : Fichier config.xml valide.';\
	else\
  		echo 'Missing configuration file : config.xml';\
  		echo 'MaX : Fichier de configuration manquant : config.xml';\
  		exit 1;\
  	fi
.PHONY: check
@@ -108,6 +108,20 @@ clean: ## Supprime l'installation de MaX et les fichiers du projet
    fi
.PHONY: clean


feed: ## Insertion de sources XML
	@if [ -z $(path) ]; then\
  		echo "USAGE : make feed path=/path/to/dir/";\
  		exit 1;\
	elif [ ! -d $(path) ]; then\
  		echo "Dossier "$(path)" introuvable !";\
  		echo "USAGE : make feed path=/path/to/dir/"; \
  		exit 1;\
  	fi;\
    $(shell .max/basex/bin/basex -c"OPEN max; ADD "$(path))\
    echo $(path)" ajouté à la base 'max'."
.PHONY: feed

help: ## Affiche cette aide
	@echo "\nChoisissez une commande. Les choix sont:\n"
	@grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[0;36m%-12s\033[m %s\n", $$1, $$2}'
+30 −19
Changes for src/main/core/conf.xqm: 30 added lines, 19 removed lines.
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ xquery version "3.0";

(:~
: MaX "conf" module
: Reads configuration from a config.xml file
: Reads configuration from the MaX config.xml file
:)
module namespace conf = 'https://certic.unicaen.fr/max/conf';

@@ -28,35 +28,40 @@ declare variable $conf:dev-mode := 'dev';


(:~
 : @return config as xml
 : Returns MaX configuration
 : @return element
 :)
declare function conf:get-configuration() as element(){
	    doc(file:current-dir() || $conf:config-file)/max:configuration
	    doc(conf:get-configuration-path())/max:configuration
};

(:~
 : @return config file path
 : Returns the MaX configuration file path
 : @return file path
 :)
declare function conf:get-configuration-path() as xs:string{
	file:current-dir() || $conf:config-file
};

(:~
 : @return MaX expath package path
 : Returns then MaX expath package file path
 : @return file path
 :)
declare function conf:get-package-path() as xs:string{
declare function conf:get-package-file-path() as xs:string{
    conf:get-resources-path() || $conf:package-file
};

(:~
 : @return MaX resources dir path
 : Returns MaX resources dir path
 : @return dir path
 :)
declare function conf:get-resources-path() as xs:string{
    file:current-dir() ||'.max/resources/'
};

(:~
 : @return active vocabulary name
 : Returns the active vocabulary name
 : @return vocabulary name
 :)
declare function conf:get-vocabulary-bundle() as xs:string{
	let $bundle := string(conf:get-configuration()/@vocabulary-bundle)
@@ -70,7 +75,8 @@ declare function conf:get-vocabulary-bundle() as xs:string{
};

(:~
 : @return language list
 : Returns the list of available languages
 : @return sequence
 :)
declare function conf:get-languages() as xs:string*{
	conf:get-configuration()//max:languages/max:language/text()
@@ -78,14 +84,16 @@ declare function conf:get-languages() as xs:string*{


(:~
 : @return vocabulary name
 : Returns the corpus title
 : @return corpus title
 :)
declare function conf:get-title() as xs:string*{
declare function conf:get-title() as xs:string{
	string(conf:get-configuration()/max:title)
};

(:~
 : @return if dev mode is enabled
 : Returns true() when dev mode is enabled
 : @return dev mode or not
 :)
declare function conf:is-dev-mode() as xs:boolean{
	string(conf:get-configuration()/@env) = $conf:dev-mode
@@ -94,18 +102,20 @@ declare function conf:is-dev-mode() as xs:boolean{


(:~
 : @return vocabulary bundle namespace
 : Returns the namespace of the active vocabulary bundle
 : @return bundle namespace
 :)
declare function conf:get-vocabulary-namespace(){
declare function conf:get-vocabulary-namespace() as xs:string{
    let $bundleName := conf:get-vocabulary-bundle()
    let $pkgFile := utils:get-bundles-path() || $bundleName || '/' || $conf:package-file
    return doc($pkgFile)//expath:xquery/expath:namespace/text()
};

(:~
 : @return main vocabulary bundle xq file path
 : Returns the active vocabulary bundle xq file path
 : @return file path
 :)
declare function conf:get-vocabulary-xq-file(){
declare function conf:get-vocabulary-xq-file() as xs:string{
    let $bundleName := conf:get-vocabulary-bundle()
    let $pkgFile := utils:get-bundles-path() || $bundleName || '/' || $conf:package-file
    return string(doc($pkgFile)/expath:package/@abbrev) || '/' || doc($pkgFile)//expath:xquery/expath:file/text()
@@ -113,10 +123,11 @@ declare function conf:get-vocabulary-xq-file(){


(:~
 : @return MaX version
 : Returns MaX version number
 : @return version
 :)
declare function conf:get-max-version(){
    let $version := string(doc(conf:get-package-path())/expath:package/@version)
declare function conf:get-max-version() as xs:string{
    let $version := string(doc(conf:get-package-file-path())/expath:package/@version)
    return
        if(conf:is-dev-mode())
        then
+3 −1
Changes for src/main/core/database.xqm: 3 added lines, 1 removed line.
Original line number Diff line number Diff line
@@ -11,8 +11,9 @@ declare variable $database:max-db := "max";


(:~
 : Returns an XML document of MaX DB
 : @param $documentPath document path
 : @return doc in max db
 : @return document
 :)
declare function database:get-document($documentPath as xs:string) as document-node()?{
    try {
@@ -26,6 +27,7 @@ declare function database:get-document($documentPath as xs:string) as document-n


(:~
 : Returns an identified fragment in a document of MaX db
 : @param $documentPath document path
 : @param  $id  fragment id
 : @return identified fragment in a document of max db
+18 −12
Changes for src/main/core/errors.xqm: 18 added lines, 12 removed lines.
Original line number Diff line number Diff line
xquery version "3.0";

(:~
: MaX "http errors" module
: MaX  errors module
:)
module namespace errors = 'https://certic.unicaen.fr/max/errors';
import module namespace templating = 'https://certic.unicaen.fr/max/templating'  at 'templating.xqm';
import module namespace conf = 'https://certic.unicaen.fr/max/conf'  at 'conf.xqm';

(:~
 : Erreur 404 - page non trouvée
 : Cherche à utiliser le template error.html du bundle de vocabulaire, sinon le message brut est renvoyé
 : @return error page
 : Returns 404 error page
 : @return HTML page
 :)
declare
%output:method("html")
%output:html-version('5')
function errors:not-found($message, $lang as xs:string) {
function errors:not-found($message, $lang as xs:string) as element(html){
  let $tmpl := templating:template-file('error.html')
  let $detail := if(conf:is-dev-mode()) then $message else ''
  let $render := if($tmpl)
@@ -33,10 +32,11 @@ function errors:not-found($message, $lang as xs:string) {

};


(:~
 : Returns 404 error page
 : @return HTML page
 :)
declare
%output:method("html")
%output:html-version('5')
function errors:simple-error($code as xs:QName, $desc as xs:string, $line as xs:integer){
  let $message := string-join(($code,  $desc, 'line ' || $line),', ')
  return
@@ -50,11 +50,14 @@ function errors:simple-error($code as xs:QName, $desc as xs:string, $line as xs:
  'MaX Error : ' || $message)
};


(:~
 : Returns an error page
 : @return HTML page
 :)
declare
%output:method("html")
%output:html-version('5')
function errors:error($code as xs:QName, $desc as xs:string, $line as xs:integer, $lang as xs:string) {
function errors:error($code as xs:QName, $desc as xs:string, $line as xs:integer, $lang as xs:string) as element(html){
  let $tmpl := templating:template-file('error.html')
  let $detail := if(conf:is-dev-mode()) then string-join(($code,  $desc, 'line ' || $line),', ') else ''
  let $render := templating:render(
@@ -71,11 +74,14 @@ function errors:error($code as xs:QName, $desc as xs:string, $line as xs:integer
  $render)
};


(:~
 : Returns an errors page
 : @return HTML page
 :)
declare
%output:method("html")
%output:html-version('5')
function errors:errors($messages, $lang as xs:string?) {
function errors:errors($messages, $lang as xs:string?) as element(html){
  let $tmpl := templating:template-file('error.html')
  let $detail := if(conf:is-dev-mode())
    then  <ul>{
+6 −6
Changes for src/main/core/i18n.xqm: 6 added lines, 6 removed lines.
Original line number Diff line number Diff line
@@ -33,28 +33,28 @@ declare function i18n:default-translate ($key as xs:string, $lang as xs:string)
};

(:~
 : User locales path
 : Returns user locales path
 : @return string
 :)
declare function i18n:getUserLocalesPath(){
declare function i18n:getUserLocalesPath() as xs:string{
    file:current-dir() || 'locales/'
};

(:~
 : bundle locales path
 : Returns bundle locales path
 : @return string
 :)
declare function i18n:getVocabularyLocalesPath(){
declare function i18n:getVocabularyLocalesPath() as xs:string{
    let $voc := conf:get-vocabulary-bundle()
    let $repoPath := utils:get-bundles-path()
    return $repoPath || $voc || '/locales/'
};

(:~
 : locales paths
 : Returns both user and vocabulary locales paths
 : @return sequence of strings
 :)
declare function i18n:getLocalePaths(){
declare function i18n:getLocalePaths() as xs:string+{
    (i18n:getUserLocalesPath(), i18n:getVocabularyLocalesPath())
};
Loading