- Sapeur

 - Installation

 - Aide / Doc

 - forum Sapeur

 - PONX 

 - PLUIE

 - MClaveau

Introduction

Sapeur est un éditeur de code-source spécialisé pour Python.
Le nom SAPEUR est la contraction de : Scintilla Autoit Ponx éditEUR

Sapeur ne fonctionne que sous Windows, car il nécessite Python 2.5.x, PyWin32 et Ponx. A noter que l'installation de Ponx vérifie la présence des autres éléments nécessaires, et les installe au besoin.
Pour l'aide Python, il est impératif que : l'aide (Python25.chm) soit installée dans C:\Python25\Doc

Fonctionnalités

Quelques particularités de sapeur :
- travail systématique en UTF-8
- indentation systématiquement avec 4 espaces
- grande sobriété : zone de saisie maximisée, menus épurés
- pas de menu "nouveau" (utiliser "ouvrir", et donner un nouveau nom)
- un seul menu (sauf l'aide), à ouvrir avec la touche {Echap}
- orienté clavier simple, sans combinaisons de touches (sauf les raccourcis-clavier de Scintilla)

Quelques fonctionnalités (liste non exhaustive) :
- coloration syntaxique
- UnDO / ReDO multiples
- dépliement / repliement des fonctions, méthodes et classes
- indentation automatique
- conversion automatique des TAB d'indentation en 4 espaces
- indentation / désindentation de bloc
- recherche simple, suivante, précédente, fonction, immédiate
- recherche dans les fichiers *.py d'un Répertoire
- macro-commandes (enregistrement, modification, jouer)
- scriptable (partiellement) en Python
- quatre touches personnalisable ({F5} {F6} {F7} {F8})
- templates (blocs de code/exemples, à insérer)
- projets (juste des "ensembles de fichiers", avec une commande de bascule rapide ({F1}+{B})
- fichiers récents
- répétition de la dernière commande du menu (par {F2})
- aide python reliée
- lancement des scripts dans des consoles externes
- gratuit  (mais, éventuellement, je peux accepter un ou deux millions d'euros)
- mode monofichier (voir plus bas)
- forum en ligne (http://ponx.fr/messages?forum=Sapeur)
- module d'édition intégré, pour les menus, le fichier .ini, le fichier d'aide
- traduction possible des menus et de l'aide (voir ligne précédente)
- mise à jour en ligne (en fait, c'est la mise à jour de Ponx qui travaille)
 

Commandes de base

{Echap} Menu
{F1} Aide / Bascule
{F2} Répète la dernière action du menu (Très utile)
{F5} à {F8} Commandes personnalisées (scriptables en Python)

Conseils

Il est (fortement) conseillé de :
- sous Vista, désactiver l'UAC
- lisser les caractères à l'écran (avec Cleartype)
        XP :
            clic-droit sur le bureau
                propriétés
                    apparences
                    [Effets]
                        utiliser méthode... lisser / ClearType
        Vista :
            clic-droit sur le bureau
                personnaliser
                    couleurs et apparences des fenêtres
                        ouvrir les propriétés d'apparence classique... (en bas)
                            Effets
                                Utiliser méthode... lisser
                                    choisir "ClearType"
- vérifier que la police Arial Narrow est bien installée dans le système

Commandes au clavier (raccourcis-clavier de l'éditeur Scintilla)

Projets

Menus, traduction et sapeur.menu.ini

Les fichiers .ini et de configuration

Divers

Appel de script Python

Macro commandes

Les macrocommandes consistent en des fichiers textes (en UTF-8), dotés de l'extension .mac , et situés dans le même répertoire que sapeur.
Chaque macro contient des lignes. Normalement, il y a une instruction par ligne. Les lignes respectent les contraintes suivantes :
  - les lignes vides sont ignorées
  - les lignes commençant par # sont considérées comme des commentaires (ignorés à l'exécution)
  - chaque instruction peut être suivie de paramètres
  - les paramètres sont séparés par des virgules
  - une virgule littérale s'écrit : ","
  - une ligne terminant pas _ continue à la ligne suivante

Les instructions possibles sont les suivantes (attention, c'est sensible à la casse) :
MSGBOX   affiche une alerte ; deux paramètres: titre et texte (court)
CLOSE   ferme sapeur
INSERT_TEXT   insère le texte passé en paramètre (multi-ligne possible avec _ )
CHARLEFT   va à gauche
CHARRIGHT   va à droite
LINEDOWN   monte d'une ligne
LINEUP   descend d'une ligne
LINESCROLLDOWN   scroll d'une ligne
LINESCROLLUP   scroll d'une ligne
WORDLEFT   mot à gauche
WORDRIGHT   mot à droite
HOME   début de ligne
LINEEND   fin de ligne
DOCUMENTSTART   début de document
DOCUMENTEND   fin de document
PAGEDOWN   page vers le bas
PAGEUP   page vers le haut
DELETEBACK   supprime caractère à gauche du curseur
DELLINELEFT   supprime la partie de la ligne à gauche du curseur
DELLINERIGHT   supprime la partie de la ligne à droite du curseur
LINEDELETE   supprime la ligne
TAB   tabule
BACKTAB   dé-tabule

D'autres instructions seront possibles, dans un proche avenir.
Si vous voulez lancer plusieurs fois de suite une macro-commandes, souvenez-vous que {F2} répète le dernier choix du menu.

Templates

Les templates sont des blocs de code prédéfinis (blocs de lignes, en réalité), à insérer dans le source courant.
Tous les templates sont dans le même fichier texte : sapeur.tmpl.txt qui doit se trouver dans le même répertoire que sapeur.

Dans ce fichier, les templates sont les uns en dessous des autres (à la suite).
Chaque template est structuré de cette façon :
- en-tête
- corps du template (code-source)
- pied

L'en-tête est composé de plusieurs lignes commençant par @@@ :
@@@-------------------------------------------
@@@nom: NOM DU TEMPLATE
@@@classement: Global, Internet, Réseau
@@@-------------------------------------------

Explications :
@@@nom:   désigne le nom du template, qui sera utilisé comme ligne du menu
@@@classement:   contient les mots-clef, séparés par des virgules, utilisés pour classer le template dans les menus
Les autres lignes commençant par @@@ sont des commentaires.

Le corps du template est du texte (en UTF-8). Ce texte peut contenir des mots clefs. Les (deux) mots-clefs possibles sont :
--CURSOR--   (maxi une seule fois par template) ; indique où devra être positionné le curseur après l'insertion du template.
--SELECTION--   (autant de fois que désiré) ; si un texte est sélectionné, dans l'éditeur, au moment de l'appel du template, le contenu de cette sélection sera utilisé pour remplacer toutes les occurrences de --SELECTION-- dans le template, au moment de son insertion.

Le pied est une simple ligne commençant par @@@ . Cette ligne sert à connaitre la fin du template.

mode monofichier

En appelant SAPEUR avec un nom de fichier (avec son chemin) en paramètre, SAPEUR se comporte comme un éditeur interne.
Tous les fonctions de fichiers sont alors désactivées des menus. Seule la sauvegarde reste ; mais elle ne demande rien, et enregistre systématiquement dans le fichier d'origine.

Cela permet d'utiliser SAPEUR comme éditeur "simili" interne pour d'autres logiciels / applications.

L'organisaion du menu

Le menu est organisé pour être : rapide et simple.
Le menu est ouvert par  {Echap}, et fermé soit par {Echap}, soit par validation d'une fonction.
Les fonctions sont validées soit par un clic de souris, soit par appui sur {Entrée} en étant positionné sur la ligne, soit par appui de la touche-raccourci, matérialisée par une majuscule soulignée.

Les commandes les plus couramment utilisée sont positionnée sur le premier menu ouvert (menu principal), de façon à en rendre l'utilisation plus rapide.

Le menu principal

Il contient :

• Edit   un sous-menu qui regroupe des fonctions sur l'édition en cours (voir plus bas)
• UnDO  permet d'annuler la dernière modification
• Chercher  ce sous-menu contient les différentes opérations de recherche
• Imédiate Recherche  au premier appel, la chaîne à chercher est demandée, et cherchée. Les appels suivants continuent la recherche, avec la même chaîne. Après 30 secondes sans utilisation, l' immédiate-Recherche est ré-initialisée (la chaîne sera demandée à nouveau).
  Il est également possible de ré-initialiser à partir du sous-menu Chercher
• Balise  permet de poser une (seule) balise, ou d'y retourner. La balise est un repère de ligne, matérialisé par un point rouge dans la marge de gauche. Le fonctionnement est le suivant :
        - si la balise n'est pas posée, elle est attribuée à la liggne courante. Un point rouge apparaît à gauche, et un (B) dans l'état (tout en haut à droite de la fenêtre).
        - si la balise est posée, et si le curseur n'est pas sur la ligne de la balise, on se déplace (le curseur aussi) jusqu'à cette ligne.
        - si la balise est posée, et si le curseur est sur la même ligne que la balise, la balise est enlevée.
        - la balise est enlevée (et perdue), lors d'un changement de fichier (ouverture, bascule, etc.)
• Ouvrir / nouveau  permet d'ouvrir un fichier.  Pour créer un nouveau fichier, il suffit de taper un nom dui n'existe pas (encore). La boîte de dialogue de choix de fichier travaille sur le dossier de travail, qui est, en fait, le dossier du dernier fichier ouvert. Mais, on peut changer à volonté. A noter que SAPEUR peut servir à éditer des fichiers textes quelconques ; mais ces fichiers seront traités exactement comme des scripts Python (indentation, coloration, etc.)
  Rappelez-vous aussi que les possibilités étendues de cette boîte de dialogue a permit d'épurer le menu d'options peu utiles.
  Par exemple, pour supprimer un fichier, utiliser le clic-droit de la souris. Vous pouvez également créer de nouveaux dossiers, trier l'affichage, ou le modifier, etc.  Pour plus de détails, voir l'utilisation de Windows.
  Enfin,  {Echap} annule l'ouverture.
• Sauvegarder  la sauvegarde propose toujours le nom du fichier. Cela permet :
        - d'avoir une confirmation, toujours utile
        - de grouper en une seule commande  Sauvegarder et Sauvegarder sous
  A noter que, si le fichier a été modifié, il suffit d'appuyer sur  {Entrée} ;  mais, si le fichier n'a pas été modifié, SAPEUR demande confirmation. Ceci, pour mieux distinguer 
  Comme pour l'ouverture,  {Echap} annule l'ouverture.
• Fichiers (récents/autres commandes)  regroupe en un sous-menu les douze derniers fichiers ouverts, et quelques commandes moins courantes sur les fichiers.  Voir plus bas.
• Projets  sous-menu contenant les différents projets (voir plus bas)
• Templates  sous-menu contenant les différents templates (voir plus bas)
• Run console orpheline faisant parler les morts  permet de lancer le script courant dans une console pilotée, avec interception des exceptions (erreurs) avec pdb, le débogueur standard de Python.
• run consoLe orpheline sans lanceur  lance le script courant dans une console séparée.
• Run console interne A(utoit)  lance le script courant dans une console gérée par SAPEUR.
• Run console interne P(ython)  lance le script courant dans une console gérée par PONX
• Divers et Spécial  sous-menu contenant des commandes moins courantes (voir plus bas)
• Macro-commandes  sous-menu de gestiondes macroè-commandes (voir plus bas)

Le sous-menu  Edit  

• UnDO  annule la dernière modification / saisie.
• ReDO  refait le dernier UnDO  (annule le dernier UnDO)
• Wordwrap (passage à la ligne des longues lignes)  bascule entre mode "passage à la ligne" et "lignes prolongées à droite".
• Colonne rémanente  Bascule du mode. Dans le mode "colonne rémanente", à chaque changement de ligne, le curseur est positionné dans la même colonne. C'est très utile, lorsqu'on a une série d'opérations à effectuer, sur une série de lignes, et toujours à la même position (de colonne).
• Espaces visibles  Bascule entre espace invisible, et espaces visible (l'espace est alors matérialisé par un minuscule point).
• Balance ; brace = { }  [ ]  <>     visualise le caractère équivalent au caractère courant, dans l'autre sens. Par exemple  (  pour  )   ou    ] pour [
• Plie ou Déplie sous la ligne courante  réduit l'aspect visible d'une fonction, ou d'une classe, à sa seule première ligne. S'il s'agit d'un bloc de lignes déjà plié, ça rétablit la visualisation complète.
• Tout Plier / Déplier  même chose que précédemment, pour toutes les fonctions et classes du script courant. Pour les gros scripts, cela peut prendre un peu de temps.
• Aller à la ligne n° ...  demande un numéro de ligne, et y déplace le curseur.
• Copier dans le presse-papier bufferisé (Ctrl+Alt+C)  Copie le texte sélectionné dans un presse-papier spécial, qui conserve les cinq (5) dernières copies. Ces données dont conservées tant que SAPEUR n'est pas fermé.
• CoLler à partir du presse-papier bufferisé (Ctrl+Alt+V)  ouvre une fenêtre, montrant les cinq congtenus de presse-papier disponibles, pour choisir lequel copier.
  

Le sous-menu  Chercher  

• Chercher  Demande quelle est la chaîne à chercher, puis effectue la recherche, à partir de la position courante.
• Chercher début  Demande quelle est la chaîne à chercher, puis effectue la recherche, à partir du début du script courant.
• Suivant  Continue la recherche précédente, à partir de la position courante (ne pose pas de question).
• Précédent  Continue la recherche précédente, à partir de la position courante, mais en remontant vers le début du script.
• Fonction  Recherche, dans le script courant, la definition de la fonction sous le curseur.
• fichiers (d'un &Répertoire)  Demande la chaîne à rechercher, et le répertoire où trouver les fichiers. Ensuite, effectue la recherche dans tous les fichiers  .py  du répertoire indiqué. Le résultat est affiché sous la forme d'un arbre à deux niveaux, le premier indiquant le nom du script (du fichier), le deuxième les lignes où la chaîne a été trouvée. Il est alors possible d'ouvrir le script dans SAPEUR.
• remise à &Zéro de la recherche immédiate  Ré-initialise la recherche immédiate. Au prochain appel de cette dernière, la question de la chaîne à chercher sera donc à nouveau posée. 
  

Le sous-menu  Navig  

• Console (invite de commande)  ouvre l'invite de commande, dans le dossier du script courant.
• Interpreteur Python  lance l'interpréteur de commande.
• Edit sapeur.ini  ouve un mini-éditeur, sur le fichier sapeur.ini, qui contient de nombreux paramètres de SAPEUR.
• Edit sapeur.menu.ini  ouve un mini-éditeur, sur le fichier des menus de SAPEUR. Il est possible de modifier les textes, mais il ne faut pas supprimer de lignes, ni modifier les clefs. L'usage principal est une traduction des menus dans une autre langue.
• Edit sapeur.proj.ini  ouve un mini-éditeur, sur le fichier décrivant les projets. Voir le paragraphe consacré aux projets, ici.
• Edit sapeur_help.htm  ouve un mini-éditeur, sur le fichier d'aide que vous êtres en trains de lire. 
• Test  Usage réservé au développer (moi !). Sert pour évaluer/tester de nouvelles fonctions. 

Le sous-menu  Macro  

• Macro immédiate (lance)  Execute la dernière macro enregistrée, ou celle nommée "immediate.mac". Cela évite la phase de sélection d'une macro. Le but est de rendre plus rapide l'utilisation d'une macro habituelle (il suffit de faire  {Echap} M M) 
• Commence l'enregistrement (clavier) d'une macro  permet d'enregistrer une nouvelle macro-commande. Seules les commandes-clavier (raccourcis, déplacement, saisie) sont enregistrées.
• Termine l'enregistrement (clavier) d'une macro  termine l'enregistrement en cours d'une macro-commande. La macro est systématiquement nommée "immediate.mac" ; le fichier se trouve dans le dossier de SAPEUR.
• Editer une macro-commande lance un mini-éditeur, pour modifier le contenu d'une macro, ou en écrire une nouvelle. Une boîte de dialogue permet de choisir le fichier. La même boîte de dialogue permet de renommer / supprimer / déplacer des macros (clic-droit sur le nom du fichier ; fonctionnalité Windows).
• Sélectionner une macro-commande  permet de sélectionner une macro, via une boîte de dialogue. Une seule macro est sélectionnable.
• sélectionner une macro-commande par son &Nom  sélectionne une macro en donnant son nom (exemple: "toto.mac")
• Lancer la macro-commande sélectionnée  exécute la macro-commande sélectionnée (courante).
  

Le sous-menu  Fichiers  

• (les 12 fichiers récemment ouverts)  charge un des fichiers récemment ouverts. Le fichier courant est ensuite placé au début de la liste. Les fichiers récents sont sauvegardés lorsque l'on ferme SAPEUR.
• Importer cp1252  permet de charger un fichier-source encodé en CP1252, en le convertissant en UTF-8 (format natif de SAPEUR).

Le sous-menu  Aide  

• Bascule le fichier-projet-courant  charge le fichier suivant dans la liste des fichiers du projet courant.
• aide &Python (mot-courant)  appelle l'aide de Python, en pré-sélectionnant le mot courant (sous le curseur) (ou sélectionné). Le fichier Python25.chm doit être c:\python25\doc. 
• aide Python (&Accueil doc)  appelle l'aide de Python, sur la page d'accueil.
• aide Python (&Modules index)  appelle l'aide de Python, sur l'index des modules.
• aide Python (&Reference)  appelle l'aide de Python, sur la page de
• aide Python (&Index)  appelle l'aide de Python, sur l'index.
• aide Python (&Tutorial)  appelle l'aide de Python, sur le tutorial (hélas en anglais).
• aide &Sapeur  appelle le fichier que vous êtes en train de lire.
• aide au &Développement  Super méga-fun génial écran, pour obtenir une aide beaucoup plus importante.