diff --git a/devel/scheme/api/tmfs/tmfs-basics.en.tm b/devel/scheme/api/tmfs/tmfs-basics.en.tm new file mode 100644 index 0000000..2200cc6 --- /dev/null +++ b/devel/scheme/api/tmfs/tmfs-basics.en.tm @@ -0,0 +1,229 @@ + + + + +<\body> + primer> + + filesystem> + + Many things in can be referenced through a with + as schema. Examples of entities in this system are buffers, views + and windows or at a higher level help buffers and search results. A + follows the format: + + > + + Requests to open s such as these are sent to a , + which actually is a set of procedures implementing the basic operations + related to the type of content they handle: loading the content, saving it + (if possible or necessary), setting the window title and establishing + access permissions are the basic operations. Predefined handlers which the + user usually encounters are , , , + and : they accept a query representing search + strings, files or help pages and render results in the appropriate language + into a new buffer. The is a string in the usual format + . Its parsing can be done using + . + + Situations where using this system makes more sense than regular documents + are for instance documentation, which must be chosen from several languages + and possibly be compiled on the fly from various sources (see module + >) and + automatically generated content, like that resulting from interacting from + an external system for version control of documents (see handler + in module >). + + + + The definition of a handler is done via or with the + convenience macros , , + and . + + Below we'll implement a basic load handler named which will + accept two sorts of arguments: and . We shall use two + procedures, one to handle the requests, another to create the document. + + <\session|scheme|default> + <\unfolded-io|Scheme] > + (tm-define (simple-load header body) + + \ \ `(document + + \ \ \ \ \ (TeXmacs ,(texmacs-version)) + + \ \ \ \ \ (style (tuple "generic")) + + \ \ \ \ \ (body (document (section ,header) ,body)))) + <|unfolded-io> + ((guile-user)) + + + <\input|Scheme] > + \; + + + + As you can see, we don't do much other than creating a document. + The load handler won't be complicated either. We only parse the query + string with the help of and then display one of three + possible buffers. + + <\session|scheme|default> + <\unfolded-io|Scheme] > + (tmfs-load-handler (simple qry) + + \ \ (let ((type (query-ref qry "type")) + + \ \ \ \ \ \ \ \ (what (query-ref qry "what"))) + + \ \ \ \ (tm-\stree + + \ \ \ \ \ \ (cond ((== type "very") (simple-load "Very simple" what)) + + \ \ \ \ \ \ \ \ \ \ \ \ ((== type "totally") (simple-load "Totally + simple" what)) + + \ \ \ \ \ \ \ \ \ \ \ \ (else (simple-load "Error" + + \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (string-append "Query + unknown: " what))))))) + <|unfolded-io> + #\procedure #f (qry)\ + + + + We can test this right away with: + + <\session|scheme|default> + <\input> + Scheme]\ + <|input> + (load-buffer "tmfs://simple/type=very&what=example") + + + + Or embedded in a document using tags like and + : . + + You can set read/write permissions implementing a , + and the window's title using a : + + <\session|scheme|default> + <\unfolded-io|Scheme] > + (tmfs-permission-handler (simple name type)\ + + \ \ (display* "Name= " name "\\nType= " type "\\n") + + \ \ #t) + <|unfolded-io> + #\procedure #f (name type)\ + + + <\unfolded-io|Scheme] > + (tmfs-title-handler (simple qry doc) "Simple handler - Some title + here") + <|unfolded-io> + #\procedure #f (qry doc)\ + + + + <\explain> + ) + )> + <|explain> + A for is invoked when receives + a request to open a of type + />. The of the + handler is passed as parameter (see ) and must + return a complete buffer. Consider the following example: + + <\scm-code> + (tmfs-load-handler (id qry) + + \ \ `(document + + \ \ \ \ \ (TeXmacs ,(texmacs-version)) + + \ \ \ \ \ (style (tuple "generic")) + + \ \ \ \ \ (body (document ,qry)))) + + + This will open s with the format + . + + Creation of the buffer contents may be simplified using the procedures + defined in module >. + + + <\explain> + ) + )> + is invoked when the user tries to save a + buffer of type /...> See also + and others.> + + <\explain> + ) + )> + is invoked to build the title for a window + displaying a buffer of type /...> It is expected + to return a simple string in the right language for the user.> + + <\explain> + + ) )> + decides whether the buffer + corresponding to the query made to the handler may be loaded/saved, etc. + may take one of the values , (...)> + + <\explain> + ) + )> + is...> + + <\explain> + )> + string of type + , will return + for an value of , etc.> + + + + In order to make your handler available from any menu item or document upon + startup, you must add it to the initialization process, that is to + or , using the macro + . This will delay loading of your code either until + it is required or is idle waiting for user input. + + <\remark> + \ The keywords , and may not be used as + names for handlers since they are used internally by . + + + <\explain> + + )> + <|explain> + Inform that is available in module + . must be a list of symbols (like + ) representing the modle wher + you'll have defined your handler using or with the + convenience macros , , + and . + + + + + The file system is actually a much more complicated beast, with + versioning, network access and authentication built in among other things. + This documentation should be completed with all those features. + + \; + + team.> + \ No newline at end of file