Api chapter (#13)

* wip: plan for API

* wip: Set up annexes for later

* fix: workaround for big longs lines

* wip: add 

too much ORM details in chapter 5 may be space killer

* wip: set up this part

* wip: add env variable def

* wip: two implementation details explained fast

* wip: middelwares

* wip: add ref for states

* wip: add ref

* wip: hardest part (WIP)

* wip: backup

* wip: first proposal

* wip: correction orthographique

* wip: change listings things

Author: jy95

codes/crawler.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+const path = require('path');
+const {promises: fs, readFileSync} = require("fs");
+const PATH_FOR_STRATEGY = path.resolve(__dirname, "..", "./strategies");
+const DEBUG_FILE = path.resolve("./results.json");
+
+exports = module.exports = {
+    "command": "crawler",
+    "describe": "export metadata from your exercises to Source Code",
+    "builder": function (y) {
+        return y
+            .option("strategy", {
+                alias: "s",
+                type: "string",
+                description: "Name of the already implemented strategy you want to use",
+                choices: ["inginious-git"]
+            })
+            .option("custom_strategy", {
+                alias: "cs",
+                type: "string",
+                conflicts: "strategy",
+                description: "Absolute path to a JS file implementing your strategy (see docs for more info)"
+            })
+            .option("workingDirectory", {
+                alias: "w",
+                type: "string",
+                description: "Absolute path to a folder where the crawler can do its stuff",
+                demandOption: true
+            })
+            .option("resultFile", {
+                alias: "out",
+                type: "string",
+                description: "Absolute path to a JSON file the crawler could write its results",
+                default: DEBUG_FILE
+            })
+            .coerce("workingDirectory", (arg) => {
+                return path.resolve(arg);
+            })
+            .config("settings", "Absolute path to a JSON config file for strategy + crawler", (configPath) => {
+                return JSON.parse(readFileSync(path.resolve(configPath), 'utf-8'));
+            })
+            .help()
+            .argv;
+    },
+    "handler": function (argv) {
+        fs
+            .mkdir(argv.workingDirectory, {recursive: true})
+            .then(() => fetch_and_save_results(argv))
+            .catch((err) => {
+                console.error(err);
+            });
+    }
+};
+
+async function fetch_and_save_results(argv) {
+    // If custom script, invoke this to get results
+    try {
+        const results =
+            (argv.hasOwnProperty("custom_strategy"))
+                ? await require(argv.custom_strategy)(argv)
+                : await require(path.resolve(PATH_FOR_STRATEGY, argv.strategy))(argv);
+
+        await fs.writeFile(argv.resultFile, JSON.stringify(results, null, 4));
+        console.log("SUCCESSFULLY SAVED THE RESULTS");
+        return await Promise.resolve(results)
+    } catch (e) {
+        return await Promise.reject(e);
+    }
+}

codes/mainCLI.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+require('yargs')
+    .command(require('./commands/crawler'))
+    .command(require('./commands/uploader'))
+    .command(require("./commands/archiver"))
+    .command(require("./commands/validator"))
+    .help()
+    .argv;

codes/searchAPI.js

@@ -0,0 +1,73 @@
+// Extracted from models/Exercises (it should be renamed to "Fiche" one day)
+// The interesting method is tagsConditionsBuilder
+const Sequelize = require("sequelize");
+const Op = Sequelize.Op;
+
+const simpleCase = (array, mustBePresent) => {
+    // positive tags : 2 OR 3 OR 4 , etc...
+    // negative tags : NOT 2 OR NOT 3 , etc...
+    return Sequelize.where(
+        // for negative check, we should use contains instead
+        // For example (using the examples above) :
+        //   For positive check : tags_ids && [2,3,4]
+        //   For negative check : tags_ids @> [2,3]
+        Sequelize.where(
+            Sequelize.col("tags_ids"),
+            (mustBePresent) ? Op.overlap : Op.contains,
+            array
+        ),
+        Op.is,
+        mustBePresent
+    )
+};
+
+const tagsWhereBuilder = {
+    "simpleCase": simpleCase,
+    "complexCase": (must_have, must_not) => ({
+        [Op.or]: [
+            simpleCase(must_have, true),
+            simpleCase(must_not, false),
+        ]
+    })
+};
+
+// tag condition builder 
+function tagsConditionsBuilder(tags) {
+
+    const conditions = tags.map(tagOrTags => {
+
+        // filter negative/positive integer(s) into array ( more efficient to check that way )
+        const must_have = Array.isArray(tagOrTags)
+            ? tagOrTags.filter(tag => tag >= 0)
+            : tagOrTags >= 0
+                ? [tagOrTags]
+                : [];
+        const must_not = Array.isArray(tagOrTags)
+            ? tagOrTags.filter(tag => !(tag >= 0)).map(tag => -tag)
+            : tagOrTags >= 0
+                ? []
+                : [-tagOrTags];
+
+        // multiple case can occur because of the mixin of must_have / must_not checks
+        // One is these case is mandatory true
+        const kind = (must_not.length > 0 && must_have.length > 0) ? "complexCase" : "simpleCase";
+
+        // in simple case, it's straightforward
+        if (kind === "simpleCase") {
+            return tagsWhereBuilder[kind](
+                (must_have.length > 0) ? must_have : must_not,
+                // simplification : if must_have is not empty, mustOverlap will be true , otherwise false (must_not)
+                must_have.length > 0
+            )
+        } else {
+            // the most horrible case
+            return tagsWhereBuilder[kind](must_have, must_not)
+        }
+
+    });
+
+    // as the expression is in Conjunctive Normal Form, we know we can combine AND and OR formulas
+    return {
+        [Op.and]: conditions
+    };
+}

commonPreamble.sty

@@ -131,6 +131,7 @@
 \usepackage[dvipsnames]{xcolor}
 
 % Pour les maudits accents dans listings, vaut mieux prévenir que guérir
+% Aussi gérer les lignes trop longues 
 \lstset{%
 inputencoding=utf8,
 extendedchars=true,
@@ -176,7 +177,11 @@ literate=%
   backgroundcolor=\color{white},
   basicstyle=\ttfamily,
   breakatwhitespace=false,
-  breaklines=false,
+  % To deal with too long lines
+  % https://tex.stackexchange.com/questions/116534/lstlisting-line-wrapping
+  breaklines=true,
+  postbreak=\mbox{\textcolor{red}{$\hookrightarrow$}\space},
+  % in the original JSES6Base, it was breaklines=false
   captionpos=b,
   columns=fullflexible,
   commentstyle=\color{mediumgray}\upshape,
@@ -263,6 +268,10 @@ literate=%
     %\setcounter{tocdepth}{#1}%
 }
 
+% Pour renommer les listings
+\renewcommand\lstlistlistingname{Table des extraits de code}
+\renewcommand{\lstlistingname}{Code} % Listing->Code
+
 % Pour être sur que ces footnotes soient bien en bottom de page
 \usepackage[bottom]{footmisc}
 

glossary.tex

@@ -147,7 +147,7 @@
 {
     name={Middleware},
     text={middleware},
-    plural={middleware},
+    plural={middlewares},
     description={
         Terme générique pour désigner tout logiciel permettant de mettre en relation plusieurs applications.
         Ce terme existe également sous une version francisée : le "logiciel médiateur".
@@ -162,4 +162,14 @@
     description={
         Ce terme désigne, comme expliqué par Wikipédia\cite{libraryDef}, "une collection de fonctions utilitaires prêtes à être utilisées par des programmes".
     }
+}
+
+\newglossaryentry{envvar}
+{
+    name={Variable d'environnement},
+    text={variable d'environnement},
+    plural={variables d'environnement},
+    description={
+        Ce terme désigne, comme expliqué par Wikipédia\cite{envvarDef}, "une variables dynamique utilisée par les différents processus d’un système d’exploitation".
+    }
 }

images/serveur/doc_example.PNG

@@ -43,6 +43,13 @@ @online{
     url= {https://fr.wikipedia.org/wiki/Biblioth%C3%A8que_logicielle}
 }
 
+@online{
+    envvarDef,
+    title = "Variable d'environnement",
+    author = {Wikipedia},
+    url= {https://fr.wikipedia.org/wiki/Variable_d%27environnement}
+}
+
 @online{
     MoSCoW,
     title = "Méthode MoSCoW",

images/serveur/middleware_onion.png

@@ -0,0 +1,4 @@
+\chapter{Analyse Bibliographique}
+\label{annexe:AnalyseBiblio}
+
+TODO includegraphics pdf